001 package org.mycore.services.imaging;
002
003 import java.awt.Dimension;
004 import java.io.InputStream;
005 import java.io.OutputStream;
006
007 /**
008 * An image processor (short ImgProcesor) represent an object with the ability
009 * to manipulate image data. The image data is passed as InputStream. The edited
010 * image data is encoded at least in JPEG or TIFF and passed as OutputStream.
011 * There are two modes how the processor work. The first mode is when you want
012 * to perform only one image operation. So you can use the methods which has
013 * input and output parameter. The second mode is when you want to perform
014 * several image operation on the same image like "scale, encode, scale,
015 * encode,...". So first you have to load the image into the processor and then
016 * you can perform any image operation.
017 *
018 * @author chi
019 *
020 */
021 public interface ImgProcessor {
022 /**
023 * Scales the image to the new width in due proportion and encode it
024 * depending on the encoder setting of the ImgProcessor. Default encoder is
025 * JPEG. </br>
026 *
027 * @param input
028 * the image data as InputStream
029 * @param newWidth
030 * the new width
031 * @param output
032 * the scaled and encoded image as OutputStream
033 */
034 void resizeFitWidth(InputStream input, int newWidth, OutputStream output);
035
036 /**
037 * Scales the image to the new height and encode it depending on the encoder
038 * setting of the ImgProcessor. Default encoder is JPEG. </br>
039 *
040 * @param input
041 * the image data as InputStream
042 * @param newHeight
043 * the new height
044 * @param output
045 * the scaled and encoded image as OutputStream
046 */
047 void resizeFitHeight(InputStream input, int newHeight, OutputStream output);
048
049 /**
050 * Scales the image to fit into the new width and height in due proportion
051 * and encode it depending on the encoder setting of the ImgProcessor.
052 * Default encoder is JPEG. </br>
053 *
054 * @param input
055 * the image data as InputStream
056 * @param newWidth
057 * the new width to fit in
058 * @param newHeight
059 * the new height to fit in
060 * @param output
061 * the scaled and encoded image as OutputStream
062 */
063 void resize(InputStream input, int newWidth, int newHeight, OutputStream output);
064
065 /**
066 * Scales the image with the given scale factor in due proportion and encode
067 * it depending on the encoder setting of the ImgProcessor. Default encoder
068 * is JPEG. </br>
069 *
070 * @param input
071 * the image data as InputStream
072 * @param scaleFactor
073 * the scale factor for width and height
074 * @param output
075 * the scaled and encoded image as OutputStream
076 */
077 void scale(InputStream input, float scaleFactor, OutputStream output);
078
079 /**
080 * Scales the image with the given scale factor in due proportion cut off a
081 * region of interest and encode it depending on the encoder setting of the
082 * ImgProcessor. Default encoder is JPEG. </br>
083 *
084 * @param input
085 * the image data as InputStream
086 * @param xTopPos
087 * the x-coordinate of the top left position of the region of
088 * interest
089 * @param yTopPos
090 * the y-coordinate of the top left position of the region of
091 * interest
092 * @param boundWidth
093 * the width of the region of interest
094 * @param boundHeight
095 * the height of the region of interest
096 * @param scaleFactor
097 * the scale factor for width and height of the image
098 * @param output
099 * the scaled and encoded region of interest as OutputStream
100 */
101 void scaleROI(InputStream input, int xTopPos, int yTopPos, int boundWidth, int boundHeight, float scaleFactor, OutputStream output);
102
103 /**
104 * Returns the scale factor used for the accomplished scale operation. </br>
105 *
106 * @return float value of the scale factor
107 */
108 float getScaleFactor();
109
110 /**
111 * Return the JPEG quality setting of the image processor.
112 *
113 * @return float value of the JPEG quality </br>
114 */
115 float getJpegQuality();
116
117 /**
118 * Set the JPEG quality of the image processor. </br>
119 *
120 * @param jpegQuality
121 * the float value of the JPEG quality
122 */
123 void setJpegQuality(float jpegQuality);
124
125 /**
126 * Set the tile width and height for a TIFF image, which is used in the
127 * encoding process. </br>
128 *
129 * @param tileWidth
130 * @param tileHeight
131 */
132 void setTileSize(int tileWidth, int tileHeight);
133
134 /**
135 * Set which encoder to use in the encoding process. </br>
136 *
137 * @param encoder
138 * the encoder should be a static field variable of the impleming
139 * class e.g. ImplementedClass.JPEG
140 * @throws Exception
141 * if you enter a number which is not in the encoder list
142 */
143 void useEncoder(int encoder) throws Exception;
144
145 /**
146 * Change the format of an image.
147 *
148 * @param input
149 * the image data as InputStream
150 * @param output
151 * the image in a new format
152 * @param encoder
153 * the encoder should be a static field variable of the impleming
154 * class e.g. ImplementedClass.JPEG
155 * @throws Exception
156 * if you enter a number which is not in the encoder list
157 */
158 void encode(InputStream input, OutputStream output, int encoder) throws Exception;
159
160 /**
161 * Returns the original image size of the image currently loades in the
162 * processor.
163 *
164 * @return Dimension of the image
165 * @throws Exception
166 * if no image is loaded in the processor
167 */
168 Dimension getOrigSize() throws Exception;
169
170 /**
171 * Returns the size of the edited image. The current size change after every
172 * scale operation.
173 *
174 * @return Dimension of the edited image
175 * @throws Exception
176 * if no image is loaded in the processor
177 */
178 Dimension getCurrentSize() throws Exception;
179
180 /**
181 * Returns the size of the image which is passed as InputStream.
182 *
183 * @param input
184 * the image data as InputStream
185 * @return Dimension of the image
186 */
187 Dimension getImageSize(InputStream input);
188
189 // separated Methods
190 /**
191 * Loads an image into the processor.
192 *
193 * @param input
194 * the image data as InputStream
195 */
196 void loadImage(InputStream input);
197
198 /**
199 * Check if an image loaded into the processor has the correct tile size.
200 * The "correct" size is the size set in the processor. Default is 480 x
201 * 480.
202 *
203 * @return true if the image has the correct tile size
204 * @throws Exception
205 * if no image is loaded in the processor
206 */
207 boolean hasCorrectTileSize() throws Exception;
208
209 /**
210 * Scales the image to the new width in due proportion. An image should be
211 * loaded into the processor before using this method. </br>
212 *
213 * @param newWidth
214 * the new width
215 * @throws Exception
216 * if no image is loaded in the processor
217 */
218 void resizeFitWidth(int newWidth) throws Exception;
219
220 /**
221 * Scales the image to the new height in due proportion. An image should be
222 * loaded into the processor before using this method. </br>
223 *
224 * @param newHeight
225 * the new height
226 * @throws Exception
227 * if no image is loaded in the processor
228 */
229 void resizeFitHeight(int newHeight) throws Exception;
230
231 /**
232 * Scales the image to fit into the new width and height in due proportion.
233 * An image should be loaded into the processor before using this method.
234 * </br>
235 *
236 * @param newWidth
237 * new width to fit in
238 * @param newHeight
239 * new height to fit in
240 * @throws Exception
241 * if no image is loaded in the processor
242 */
243 void resize(int newWidth, int newHeight) throws Exception;
244
245 /**
246 * Scales the image with the given scale factor in due proportion.
247 *
248 * @param scaleFactor
249 * the scale factor for width and height of the image
250 * @throws Exception
251 * if no image is loaded in the processor
252 */
253 void scale(float scaleFactor) throws Exception;
254
255 /**
256 * Scales the image with the given scale factor in due proportion cut off a
257 * region of interest and encode it depending on the encoder setting of the
258 * ImgProcessor. Default encoder is JPEG. </br>
259 *
260 * @param xTopPos
261 * the x-coordinate of the top left position of the region of
262 * interest
263 * @param yTopPos
264 * the y-coordinate of the top left position of the region of
265 * interest
266 * @param boundWidth
267 * the width of the region of interest
268 * @param boundHeight
269 * the height of the region of interest
270 * @param scaleFactor
271 * the scale factor for width and height of the image
272 * @throws Exception
273 * if no image is loaded in the processor
274 */
275 void scaleROI(int xTopPos, int yTopPos, int boundWidth, int boundHeight, float scaleFactor) throws Exception;
276
277 /**
278 * Encode the loaded image as a JPEG image to a given OutputStream.
279 *
280 * @param output
281 * the encoded image
282 * @throws Exception
283 * if no image is loaded in the processor
284 */
285 void jpegEncode(OutputStream output) throws Exception;
286
287 /**
288 * Encode the loaded image as a TIFF image to a given OutputStream.
289 *
290 * @param output
291 * the encodes image
292 * @throws Exception
293 * if no image is loaded in the processor
294 */
295 void tiffEncode(OutputStream output) throws Exception;
296 }