001: /*
002: * $RCSfile: TIFFImageWriteParam.java,v $
003: *
004: *
005: * Copyright (c) 2005 Sun Microsystems, Inc. All Rights Reserved.
006: *
007: * Redistribution and use in source and binary forms, with or without
008: * modification, are permitted provided that the following conditions
009: * are met:
010: *
011: * - Redistribution of source code must retain the above copyright
012: * notice, this list of conditions and the following disclaimer.
013: *
014: * - Redistribution in binary form must reproduce the above copyright
015: * notice, this list of conditions and the following disclaimer in
016: * the documentation and/or other materials provided with the
017: * distribution.
018: *
019: * Neither the name of Sun Microsystems, Inc. or the names of
020: * contributors may be used to endorse or promote products derived
021: * from this software without specific prior written permission.
022: *
023: * This software is provided "AS IS," without a warranty of any
024: * kind. ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND
025: * WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY,
026: * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE HEREBY
027: * EXCLUDED. SUN MIDROSYSTEMS, INC. ("SUN") AND ITS LICENSORS SHALL
028: * NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF
029: * USING, MODIFYING OR DISTRIBUTING THIS SOFTWARE OR ITS
030: * DERIVATIVES. IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR
031: * ANY LOST REVENUE, PROFIT OR DATA, OR FOR DIRECT, INDIRECT, SPECIAL,
032: * CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND
033: * REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF THE USE OF OR
034: * INABILITY TO USE THIS SOFTWARE, EVEN IF SUN HAS BEEN ADVISED OF THE
035: * POSSIBILITY OF SUCH DAMAGES.
036: *
037: * You acknowledge that this software is not designed or intended for
038: * use in the design, construction, operation or maintenance of any
039: * nuclear facility.
040: *
041: * $Revision: 1.3 $
042: * $Date: 2006/04/28 01:01:59 $
043: * $State: Exp $
044: */
045: package com.sun.media.imageio.plugins.tiff;
046:
047: import java.util.Arrays;
048: import java.util.List;
049: import java.util.Locale;
050: import javax.imageio.ImageWriteParam;
051: import com.sun.media.imageioimpl.plugins.tiff.TIFFImageWriter;
052:
053: /**
054: * A subclass of {@link ImageWriteParam <code>ImageWriteParam</code>}
055: * allowing control over the TIFF writing process. The set of innately
056: * supported compression types is listed in the following table:
057: *
058: * <p>
059: * <table border=1>
060: * <caption><b>Supported Compression Types</b></caption>
061: * <tr><th>Compression Type</th> <th>Description</th> <th>Reference</th></tr>
062: * <tr>
063: * <td>CCITT RLE</td>
064: * <td>Modified Huffman compression</td>
065: * <td>TIFF 6.0 Specification, Section 10</td>
066: * </tr>
067: * <tr>
068: * <td>CCITT T.4</td>
069: * <td>CCITT T.4 bilevel encoding/Group 3 facsimile compression</td>
070: * <td>TIFF 6.0 Specification, Section 11</td>
071: * </tr>
072: * <tr>
073: * <td>CCITT T.6</td>
074: * <td>CCITT T.6 bilevel encoding/Group 4 facsimile compression</td>
075: * <td>TIFF 6.0 Specification, Section 11</td></tr>
076: * <tr>
077: * <td>LZW</td>
078: * <td>LZW compression</td>
079: * <td>TIFF 6.0 Specification, Section 13</td></tr>
080: * <tr>
081: * <td>JPEG</td>
082: * <td>"New" JPEG-in-TIFF compression</td>
083: * <td><a href="ftp://ftp.sgi.com/graphics/tiff/TTN2.draft.txt">TIFF
084: * Technical Note #2</a></td>
085: * </tr>
086: * <tr>
087: * <td>ZLib</td>
088: * <td>"Deflate/Inflate" compression (see note following this table)</td>
089: * <td><a href="http://partners.adobe.com/asn/developer/pdfs/tn/TIFFphotoshop.pdf">
090: * Adobe Photoshop® TIFF Technical Notes</a> (PDF)</td>
091: * </tr>
092: * <tr>
093: * <td>PackBits</td>
094: * <td>Byte-oriented, run length compression</td>
095: * <td>TIFF 6.0 Specification, Section 9</td>
096: * </tr>
097: * <tr>
098: * <td>Deflate</td>
099: * <td>"Zip-in-TIFF" compression (see note following this table)</td>
100: * <td><a href="http://www.isi.edu/in-notes/rfc1950.txt">
101: * ZLIB Compressed Data Format Specification</a>,
102: * <a href="http://www.isi.edu/in-notes/rfc1951.txt">
103: * DEFLATE Compressed Data Format Specification</a></td>
104: * </tr>
105: * <tr>
106: * <td>EXIF JPEG</td>
107: * <td>EXIF-specific JPEG compression (see note following this table)</td>
108: * <td><a href="http://www.exif.org/Exif2-2.PDF">EXIF 2.2 Specification</a>
109: * (PDF), section 4.5.5, "Basic Structure of Thumbnail Data"</td>
110: * </table>
111: * </p>
112: * <p>
113: * Old-style JPEG compression as described in section 22 of the TIFF 6.0
114: * Specification is <i>not</i> supported.
115: * </p>
116: *
117: * <p> The CCITT compression types are applicable to bilevel (1-bit)
118: * images only. The JPEG compression type is applicable to byte
119: * grayscale (1-band) and RGB (3-band) images only.</p>
120: *
121: * <p>
122: * ZLib and Deflate compression are identical except for the value of the
123: * TIFF Compression field: for ZLib the Compression field has value 8
124: * whereas for Deflate it has value 32946 (0x80b2). In both cases each
125: * image segment (strip or tile) is written as a single complete zlib data
126: * stream.
127: * </p>
128: *
129: * <p>
130: * "EXIF JPEG" is a compression type used when writing the contents of an
131: * APP1 EXIF marker segment for inclusion in a JPEG native image metadata
132: * tree. The contents appended to the output when this compression type is
133: * used are a function of whether an empty or non-empty image is written.
134: * If the image is empty, then a TIFF IFD adhering to the specification of
135: * a compressed EXIF primary IFD is appended. If the image is non-empty,
136: * then a complete IFD and image adhering to the specification of a
137: * compressed EXIF thumbnail IFD and image are appended. Note that the
138: * data of the empty image may <i>not</i> later be appended using the pixel
139: * replacement capability of the TIFF writer.
140: * </p>
141: *
142: * <p> If ZLib/Deflate or JPEG compression is used, the compression quality
143: * may be set. For ZLib/Deflate the supplied floating point quality value is
144: * rescaled to the range <tt>[1, 9]</tt> and truncated to an integer
145: * to derive the Deflate compression level. For JPEG the floating point
146: * quality value is passed directly to the JPEG writer plug-in which
147: * interprets it in the usual way.</p>
148: *
149: * <p> The <code>canWriteTiles</code> and
150: * <code>canWriteCompressed</code> methods will return
151: * <code>true</code>; the <code>canOffsetTiles</code> and
152: * <code>canWriteProgressive</code> methods will return
153: * <code>false</code>.</p>
154: *
155: * <p> If tiles are being written, then each of their dimensions will be
156: * rounded to the nearest multiple of 16 per the TIFF specification. If
157: * JPEG-in-TIFF compression is being used, and tiles are being written
158: * each tile dimension will be rounded to the nearest multiple of 8 times
159: * the JPEG minimum coded unit (MCU) in that dimension. If JPEG-in-TIFF
160: * compression is being used and strips are being written, the number of
161: * rows per strip is rounded to a multiple of 8 times the maximum MCU over
162: * both dimensions.</p>
163: */
164: public class TIFFImageWriteParam extends ImageWriteParam {
165:
166: TIFFCompressor compressor = null;
167:
168: TIFFColorConverter colorConverter = null;
169: int photometricInterpretation;
170:
171: private boolean appendedCompressionType = false;
172:
173: /**
174: * Constructs a <code>TIFFImageWriteParam</code> instance
175: * for a given <code>Locale</code>.
176: *
177: * @param locale the <code>Locale</code> for which messages
178: * should be localized.
179: */
180: public TIFFImageWriteParam(Locale locale) {
181: super (locale);
182: this .canWriteCompressed = true;
183: this .canWriteTiles = true;
184: this .compressionTypes = TIFFImageWriter.TIFFCompressionTypes;
185: };
186:
187: public boolean isCompressionLossless() {
188: if (getCompressionMode() != MODE_EXPLICIT) {
189: throw new IllegalStateException(
190: "Compression mode not MODE_EXPLICIT!");
191: }
192:
193: if (compressionType == null) {
194: throw new IllegalStateException("No compression type set!");
195: }
196:
197: if (compressor != null
198: && compressionType.equals(compressor
199: .getCompressionType())) {
200: return compressor.isCompressionLossless();
201: }
202:
203: for (int i = 0; i < compressionTypes.length; i++) {
204: if (compressionType.equals(compressionTypes[i])) {
205: return TIFFImageWriter.isCompressionLossless[i];
206: }
207: }
208:
209: return false;
210: }
211:
212: /**
213: * Sets the <code>TIFFCompressor</code> object to be used by the
214: * <code>ImageWriter</code> to encode each image strip or tile.
215: * A value of <code>null</code> allows the writer to choose its
216: * own TIFFCompressor.
217: *
218: * <p>Note that invoking this method is not sufficient to set
219: * the compression type:
220: * {@link ImageWriteParam#setCompressionType(String) <code>setCompressionType()</code>}
221: * must be invoked explicitly for this purpose. The following
222: * code illustrates the correct procedure:
223: * <pre>
224: * TIFFImageWriteParam writeParam;
225: * TIFFCompressor compressor;
226: * writeParam.setCompressionMode(writeParam.MODE_EXPLICIT);
227: * writeParam.setTIFFCompressor(compressor);
228: * writeParam.setCompressionType(compressor.getCompressionType());
229: * </pre>
230: * If <code>compressionType</code> is set to a value different from
231: * that supported by the <code>TIFFCompressor</code> then the
232: * compressor object will not be used.
233: * </p>
234: *
235: * <p>If the compression type supported by the supplied
236: * <code>TIFFCompressor</code> is not among those in
237: * {@link ImageWriteParam#compressionTypes <code>compressionTypes</code>},
238: * then it will be appended to this array after removing any previously
239: * appended compression type. If <code>compressor</code> is
240: * <code>null</code> this will also cause any previously appended
241: * type to be removed from the array.</p>
242: *
243: * @param compressor the <code>TIFFCompressor</code> to be
244: * used for encoding, or <code>null</code> to allow the writer to
245: * choose its own.
246: *
247: * @throws IllegalStateException if the compression mode is not
248: * <code>MODE_EXPLICIT</code>.
249: *
250: * @see #getTIFFCompressor
251: */
252: public void setTIFFCompressor(TIFFCompressor compressor) {
253: if (getCompressionMode() != MODE_EXPLICIT) {
254: throw new IllegalStateException(
255: "Compression mode not MODE_EXPLICIT!");
256: }
257:
258: this .compressor = compressor;
259:
260: if (appendedCompressionType) {
261: // Remove previously appended compression type.
262: int len = compressionTypes.length - 1;
263: String[] types = new String[len];
264: System.arraycopy(compressionTypes, 0, types, 0, len);
265: compressionTypes = types;
266: appendedCompressionType = false;
267: }
268:
269: if (compressor != null) {
270: // Check whether compressor's type is already in the list.
271: String compressorType = compressor.getCompressionType();
272: int len = compressionTypes.length;
273: boolean appendCompressionType = true;
274: for (int i = 0; i < len; i++) {
275: if (compressorType.equals(compressionTypes[i])) {
276: appendCompressionType = false;
277: break;
278: }
279: }
280:
281: if (appendCompressionType) {
282: // Compressor's compression type not in the list; append it.
283: String[] types = new String[len + 1];
284: System.arraycopy(compressionTypes, 0, types, 0, len);
285: types[len] = compressorType;
286: compressionTypes = types;
287: appendedCompressionType = true;
288: }
289: }
290: }
291:
292: /**
293: * Returns the <code>TIFFCompressor</code> that is currently set
294: * to be used by the <code>ImageWriter</code> to encode each image
295: * strip or tile, or <code>null</code> if none has been set.
296: *
297: * @return compressor the <code>TIFFCompressor</code> to be
298: * used for encoding, or <code>null</code> if none has been set
299: * (allowing the writer to choose its own).
300: *
301: * @throws IllegalStateException if the compression mode is not
302: * <code>MODE_EXPLICIT</code>.
303: *
304: * @see #setTIFFCompressor(TIFFCompressor)
305: */
306: public TIFFCompressor getTIFFCompressor() {
307: if (getCompressionMode() != MODE_EXPLICIT) {
308: throw new IllegalStateException(
309: "Compression mode not MODE_EXPLICIT!");
310: }
311: return this .compressor;
312: }
313:
314: /**
315: * Sets the <code>TIFFColorConverter</code> object describing the
316: * color space to which the input data should be converted for
317: * storage in the input stream. In addition, the value to be
318: * written to the <code>PhotometricInterpretation</code> tag is
319: * supplied.
320: *
321: * @param colorConverter a <code>TIFFColorConverter</code> object,
322: * or <code>null</code>.
323: * @param photometricInterpretation the value to be written to the
324: * <code>PhotometricInterpretation</code> tag in the root IFD.
325: *
326: * @see #getColorConverter
327: * @see #getPhotometricInterpretation
328: */
329: public void setColorConverter(TIFFColorConverter colorConverter,
330: int photometricInterpretation) {
331: this .colorConverter = colorConverter;
332: this .photometricInterpretation = photometricInterpretation;
333: }
334:
335: /**
336: * Returns the current <code>TIFFColorConverter</code> object that
337: * will be used to perform color conversion when writing the
338: * image, or <code>null</code> if none is set.
339: *
340: * @return a <code>TIFFColorConverter</code> object, or
341: * <code>null</code>.
342: *
343: * @see #setColorConverter(TIFFColorConverter, int)
344: */
345: public TIFFColorConverter getColorConverter() {
346: return colorConverter;
347: }
348:
349: /**
350: * Returns the current value that will be written to the
351: * <code>Photometricinterpretation</code> tag. This method should
352: * only be called if a value has been set using the
353: * <code>setColorConverter</code> method.
354: *
355: * @return an <code>int</code> to be used as the value of the
356: * <code>PhotometricInterpretation</code> tag.
357: *
358: * @see #setColorConverter(TIFFColorConverter, int)
359: *
360: * @throws IllegalStateException if no value is set.
361: */
362: public int getPhotometricInterpretation() {
363: if (colorConverter == null) {
364: throw new IllegalStateException("Color converter not set!");
365: }
366: return photometricInterpretation;
367: }
368:
369: /**
370: * Removes any currently set <code>ColorConverter</code> object and
371: * <code>PhotometricInterpretation</code> tag value.
372: *
373: * @see #setColorConverter(TIFFColorConverter, int)
374: */
375: public void unsetColorConverter() {
376: this.colorConverter = null;
377: }
378: }
|