|
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> |
|
2 <html> |
|
3 <head> |
|
4 <!-- |
|
5 Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved. |
|
6 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
|
7 |
|
8 This code is free software; you can redistribute it and/or modify it |
|
9 under the terms of the GNU General Public License version 2 only, as |
|
10 published by the Free Software Foundation. Oracle designates this |
|
11 particular file as subject to the "Classpath" exception as provided |
|
12 by Oracle in the LICENSE file that accompanied this code. |
|
13 |
|
14 This code is distributed in the hope that it will be useful, but WITHOUT |
|
15 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
|
16 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
|
17 version 2 for more details (a copy is included in the LICENSE file that |
|
18 accompanied this code). |
|
19 |
|
20 You should have received a copy of the GNU General Public License version |
|
21 2 along with this work; if not, write to the Free Software Foundation, |
|
22 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
|
23 |
|
24 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
|
25 or visit www.oracle.com if you need additional information or have any |
|
26 questions. |
|
27 --> |
|
28 |
|
29 <title>TIFF Metadata Format Specification and Usage Notes</title> |
|
30 </head> |
|
31 |
|
32 <body bgcolor="white"> |
|
33 |
|
34 <center><h1> |
|
35 TIFF Metadata Format Specification and Usage Notes |
|
36 </h1></center> |
|
37 |
|
38 <p> |
|
39 <a href="#Reading">Reading Images</a><br/> |
|
40 <font size="-1"> |
|
41 <ul> |
|
42 <li><a href="#ColorConversionRead">Color Conversion</a></li> |
|
43 <li><a href="#ColorSpacesRead">Color Spaces</a></li> |
|
44 <li><a href="#ICCProfilesRead">ICC Profiles</a></li> |
|
45 <li><a href="#MetadataIssuesRead">Metadata Issues</a> |
|
46 <font size="-2"> |
|
47 <ul> |
|
48 <li><a href="#MapNativeStandard">Native to Standard Metadata Mapping</a></li> |
|
49 </ul> |
|
50 </font> |
|
51 </li> |
|
52 <li><a href="#ExifRead">Reading Exif Images</a> |
|
53 <font size="-2"> |
|
54 <ul> |
|
55 <li><a href="#ExifReadTIFF">Reading Uncompressed Exif Images</a></li> |
|
56 <li><a href="#ExifReadJPEG">Reading Compressed Exif Images</a></li> |
|
57 </ul> |
|
58 </font> |
|
59 </li> |
|
60 </ul> |
|
61 </font> |
|
62 <a href="#Writing">Writing Images</a><br/> |
|
63 <font size="-1"> |
|
64 <ul> |
|
65 <li><a href="#Compression">Compression</a></li> |
|
66 <li><a href="#ColorConversionWrite">Color Conversion</a></li> |
|
67 <li><a href="#ICCProfilesWrite">ICC Profiles</a></li> |
|
68 <li><a href="#MetadataIssuesWrite">Metadata Issues</a></li> |
|
69 <font size="-2"> |
|
70 <ul> |
|
71 <li><a href="#MapStandardNative">Standard to Native Metadata Mapping</a></li> |
|
72 </ul> |
|
73 </font> |
|
74 <li><a href="#ExifWrite">Writing Exif Images</a> |
|
75 <font size="-2"> |
|
76 <ul> |
|
77 <li><a href="#ExifWriteTIFF">Writing Uncompressed Exif Images</a></li> |
|
78 <li><a href="#ExifWriteJPEG">Writing Compressed Exif Images</a></li> |
|
79 </ul> |
|
80 </font> |
|
81 </li> |
|
82 </ul> |
|
83 </font> |
|
84 <a href="#StreamMetadata">Native Stream Metadata Format</a><br/> |
|
85 <a href="#ImageMetadata">Native Image Metadata Format</a> |
|
86 </p> |
|
87 |
|
88 <h3><a name="Reading"/>Reading Images</h3> |
|
89 |
|
90 TIFF images are read by an <a href="../../ImageReader.html">ImageReader</a> |
|
91 which may be controlled by its public interface as well as via a supplied |
|
92 <a href="../../plugins/tiff/TIFFImageReadParam.html">TIFFImageReadParam</a>. |
|
93 |
|
94 <!-- <h4>Supported Image Types</h4> --> |
|
95 |
|
96 <!-- Table? --> |
|
97 |
|
98 <h4><a name="ColorConversionRead"/>Color Conversion</h4> |
|
99 |
|
100 <p>If the source image data |
|
101 have photometric type CIE L*a*b* or YCbCr, and the destination color space |
|
102 type is RGB, then the source image data will be automatically converted to |
|
103 RGB using an internal color converter.</p> |
|
104 |
|
105 <h4><a name="ColorSpacesRead"/>Color Spaces</h4> |
|
106 |
|
107 The raw color space assigned by default, i.e., in the absence of a |
|
108 user-supplied <a href="../../ImageTypeSpecifier.html">ImageTypeSpecifier</a>, |
|
109 will be the first among the following which applies: |
|
110 |
|
111 <ul> |
|
112 <li>A color space created from the <a href="#ICCProfilesRead">ICC Profile</a> |
|
113 metadata field if it is present and compatible with the image data |
|
114 layout.</li> |
|
115 <a name="nonICCProfile"><li>sRGB if the image is monochrome/bilevel |
|
116 (a two-level color map is created internally).</li> |
|
117 <li>sRGB if the image is palette-color.</li> |
|
118 <li>Linear RGB if the image has three samples per pixel, has photometric type |
|
119 CIE L*a*b*, or has photometric type YCbCr and is <i>not</i> |
|
120 JPEG-compressed.</li> |
|
121 <li>A <a href="#DefaultCMYK">default CMYK color space</a> if the image has |
|
122 photometric type CMYK and four samples per pixel.</li> |
|
123 <li>Grayscale if the image has one or two samples per pixel and uniformly |
|
124 1, 2, 4, 8, 16, or 32 bits per sample or is floating point.</li> |
|
125 <li>sRGB if the image has three or four samples per pixel and uniformly |
|
126 1, 2, 4, 8, 16, or 32 bits per sample or is floating point.</li> |
|
127 <li>A fabricated, <a href="#GenericCS">generic color space</a> if the image |
|
128 has more than four samples per pixel and the number of bits per sample for |
|
129 all bands is the same and is a multiple of 8.</li> |
|
130 <li>Grayscale if the image has one or two samples per pixel regardless of |
|
131 the number of bits per sample.</li> |
|
132 <li>sRGB if the image has three or four samples per pixel regardless of |
|
133 the number of bits per sample.</li> |
|
134 <li>A fabricated, <a href="#GenericCS">generic color space</a> if the image |
|
135 has more than four samples per pixel regardless of the number of bits per |
|
136 sample.</li> |
|
137 </ul> |
|
138 |
|
139 <p><a name="DefaultCMYK"/>The normalized color coordinate transformations |
|
140 used for the default CMYK color space are defined as follows: |
|
141 |
|
142 <ul> |
|
143 <li>CMYK to linear RGB |
|
144 <pre> |
|
145 R = (1 - K)*(1 - C) |
|
146 G = (1 - K)*(1 - M) |
|
147 B = (1 - K)*(1 - Y) |
|
148 </pre> |
|
149 </li> |
|
150 <li>Linear RGB to CMYK |
|
151 <pre> |
|
152 K = min{1 - R, 1 - G, 1 - B} |
|
153 if(K != 1) { |
|
154 C = (1 - R - K)/(1 - K) |
|
155 M = (1 - G - K)/(1 - K) |
|
156 Y = (1 - B - K)/(1 - K) |
|
157 } else { |
|
158 C = M = Y = 0 |
|
159 } |
|
160 </pre> |
|
161 </li> |
|
162 </ul> |
|
163 </p> |
|
164 |
|
165 <p><a name="GenericCS"/>The generic color space used when no other color space |
|
166 can be inferred is provided merely to enable the data to be loaded. It is not |
|
167 intended to provide accurate conversions of any kind.</p> |
|
168 |
|
169 <p>If the data are known to be in a color space not correctly handled by the |
|
170 foregoing, then an <code>ImageTypeSpecifier</code> should be |
|
171 supplied to the reader and should be derived from a color space which is correct |
|
172 for the data in question.</p> |
|
173 |
|
174 <h4><a name="ICCProfilesRead"/>ICC Profiles</h4> |
|
175 |
|
176 If an ICC profile is contained in the image metadata |
|
177 (<a href="../../plugins/tiff/BaselineTIFFTagSet.html"> |
|
178 BaselineTIFFTagSet</a>.TAG_ICC_PROFILE, tag number 34675), |
|
179 an attempt will be made to use it to create the color space |
|
180 of the loaded image. It will be used if the data layout is of component type |
|
181 and the number of samples per pixel equals or is one greater than the number |
|
182 of components described by the ICC profile. If the ICC profile is not used |
|
183 then the color space will be inferred in one of the subsequent steps described |
|
184 <a href="#nonICCProfile">above</a>. |
|
185 |
|
186 <p>If for some reason the embedded ICC profile is not used automatically, then |
|
187 it may be used manually by following this procedure: |
|
188 |
|
189 <ol> |
|
190 <li>Obtain the image metadata from |
|
191 <code>ImageReader.getImageMetadata</code></li> |
|
192 <li>Extract the ICC profile field and its value.</li> |
|
193 <li>Create an <a href="../../../../java/awt/color/ICC_ColorSpace.html"> |
|
194 ICC_ColorSpace</a> from an |
|
195 <a href="../../../../java/awt/color/ICC_Profile.html"> |
|
196 ICC_Profile</a> created from the ICC profile field data |
|
197 using <code>ICC_Profile.getInstance(byte[])</code>.</li> |
|
198 <li>Create an <code>ImageTypeSpecifier</code> from the new color |
|
199 space using one of its factory methods which accepts an |
|
200 <code>ICC_ColorSpace</code>. |
|
201 <li>Create a compatible <a href="../../ImageReadParam.html">ImageReadParam</a> |
|
202 and set the <code>ImageTypeSpecifier</code> using |
|
203 <code>ImageReadParam.setDestinationType</code>.</li> |
|
204 <li>Pass the parameter object to the appropriate <code>read</code> method.</li> |
|
205 </ol> |
|
206 </p> |
|
207 |
|
208 <p>If the inferred color space not based on the ICC Profile field is compatible |
|
209 with the ICC profile-based color space, then a second |
|
210 <code>ImageTypeSpecifier</code> derived from this inferred color |
|
211 space will be included in the |
|
212 <a href="../../../../java/util/Iterator.html">Iterator</a> returned by |
|
213 <code>ImageReader.getImageTypes</code>. If the iterator contains |
|
214 more than one type, the first one will be based on the ICC profile and the |
|
215 second on the inferred color space.</p> |
|
216 |
|
217 <h4><a name="MetadataIssuesRead"/>Metadata Issues</h4> |
|
218 |
|
219 By default all fields in the TIFF image file directory (IFD) are loaded into |
|
220 the native image metadata object. In cases where the IFD includes fields which |
|
221 contain large amounts of data this could be very inefficient. Which fields |
|
222 are loaded may be controlled by setting which TIFF tags the reader is allowed |
|
223 to recognize and whether it is ignoring metadata. The reader is informed to |
|
224 disregard metadata as usual via the <code>ignoreMetadata</code> parameter of |
|
225 <code>ImageReader.setInput(Object,boolean,boolean)</code>. It is |
|
226 informed of which <a href="../../plugins/tiff/TIFFTag.html">TIFFTag</a>s to |
|
227 recognize or not to recognize via |
|
228 <code>TIFFImageReadParam.addAllowedTagSet(TIFFTagSet)</code> |
|
229 and |
|
230 <code>TIFFImageReadParam.removeAllowedTagSet(TIFFTagSet)</code>. |
|
231 If <code>ignoreMetadata</code> is <code>true</code>, then the reader will |
|
232 load into the native image metadata object only those fields which have a |
|
233 <code>TIFFTag</code> contained in the one of the allowed |
|
234 <code>TIFFTagSet</code>s. |
|
235 |
|
236 <p>Use of a <a href="../../plugins/tiff/TIFFDirectory.html">TIFFDirectory</a> |
|
237 object may simplify gaining access to metadata values. An instance of |
|
238 <code>TIFFDirectory</code> may be created from the <code>IIOMetadata</code> |
|
239 object returned by the TIFF reader using the |
|
240 <code>TIFFDirectory.createFromMetadata</code> method.</p> |
|
241 |
|
242 <h5><a name="MapNativeStandard"/> |
|
243 Mapping of TIFF Native Image Metadata to the Standard Metadata Format</h5> |
|
244 |
|
245 The derivation of standard metadata format |
|
246 <a href="standard_metadata.html">javax_imageio_1.0</a> |
|
247 elements from <a href="#ImageMetadata">TIFF native image metadata</a> is given |
|
248 in the following table. |
|
249 |
|
250 <p> |
|
251 <table border="1"> |
|
252 <tr> |
|
253 <th>Standard Metadata Element</th> |
|
254 <th>Derivation from TIFF Fields</th> |
|
255 </tr> |
|
256 <tr> |
|
257 <td>/Chroma/ColorSpaceType@name</td> |
|
258 <td>PhotometricInterpretation: WhiteIsZero, BlackIsZero, TransparencyMask = |
|
259 "GRAY"; RGB, PaletteColor => "RGB"; CMYK => "CMYK"; |
|
260 YCbCr => "YCbCr"; |
|
261 CIELab, ICCLab => "Lab".</td> |
|
262 </tr> |
|
263 <tr> |
|
264 <td>/Chroma/NumChannels@value</td> |
|
265 <td>SamplesPerPixel</td> |
|
266 </tr> |
|
267 <tr> |
|
268 <td>/Chroma/BlackIsZero@value</td> |
|
269 <td>"TRUE" <=> PhotometricInterpretation => WhiteIsZero</td> |
|
270 </tr> |
|
271 <tr> |
|
272 <td>/Chroma/Palette</td> |
|
273 <td>ColorMap</td> |
|
274 </tr> |
|
275 <tr> |
|
276 <td>/Compression/CompressionTypeName@value</td> |
|
277 <td>Compression: Uncompressed => "none"; CCITT 1D => "CCITT |
|
278 RLE"; |
|
279 Group 3 Fax => "CCITT T.4"; Group 4 Fax => "CCITT T.6"; |
|
280 LZW => "LZW"; |
|
281 JPEG => "Old JPEG"; New JPEG => "JPEG"; Zlib =>> "ZLib"; PackBits => |
|
282 "PackBits"; |
|
283 Deflate => "Deflate"; Exif JPEG => "JPEG".</td> |
|
284 </tr> |
|
285 <tr> |
|
286 <td>/Compression/Lossless@value</td> |
|
287 <td>Compression: JPEG or New JPEG => "FALSE"; otherwise "TRUE".</td> |
|
288 </tr> |
|
289 <tr> |
|
290 <td>/Data/PlanarConfiguration@value</td> |
|
291 <td>Chunky => "PixelInterleaved"; Planar => "PlaneInterleaved".</td> |
|
292 </tr> |
|
293 <tr> |
|
294 <td>/Data/SampleFormat@value</td> |
|
295 <td>PhotometricInterpretation PaletteColor => "Index"; |
|
296 SampleFormat unsigned integer data => "UnsignedIntegral"; |
|
297 SampleFormat two's complement signed integer data => "SignedIntegral"; |
|
298 SampleFormat IEEE floating point data => "Real"; |
|
299 otherwise element not emitted. |
|
300 </td> |
|
301 </tr> |
|
302 <tr> |
|
303 <td>/Data/BitsPerSample@value</td> |
|
304 <td>BitsPerSample as a space-separated list.</td> |
|
305 </tr> |
|
306 <tr> |
|
307 <td>/Data/SampleMSB@value</td> |
|
308 <td>FillOrder: left-to-right => space-separated list of BitsPerSample-1; |
|
309 right-to-left => space-separated list of 0s.</td> |
|
310 </tr> |
|
311 <tr> |
|
312 <td>/Dimension/PixelAspectRatio@value</td> |
|
313 <td>(1/XResolution)/(1/YResolution)</td> |
|
314 </tr> |
|
315 <tr> |
|
316 <td>/Dimension/ImageOrientation@value</td> |
|
317 <td>Orientation</td> |
|
318 </tr> |
|
319 <tr> |
|
320 <td>/Dimension/HorizontalPixelSize@value</td> |
|
321 <td>1/XResolution in millimeters if ResolutionUnit is not None.</td> |
|
322 </tr> |
|
323 <tr> |
|
324 <td>/Dimension/VerticalPixelSize@value</td> |
|
325 <td>1/YResolution in millimeters if ResolutionUnit is not None.</td> |
|
326 </tr> |
|
327 <tr> |
|
328 <td>/Dimension/HorizontalPosition@value</td> |
|
329 <td>XPosition in millimeters if ResolutionUnit is not None.</td> |
|
330 </tr> |
|
331 <tr> |
|
332 <td>/Dimension/VerticalPosition@value</td> |
|
333 <td>YPosition in millimeters if ResolutionUnit is not None.</td> |
|
334 </tr> |
|
335 <tr> |
|
336 <td>/Document/FormatVersion@value</td> |
|
337 <td>6.0</td> |
|
338 </tr> |
|
339 <tr> |
|
340 <td>/Document/SubimageInterpretation@value</td> |
|
341 <td>NewSubFileType: transparency => "TransparencyMask"; |
|
342 reduced-resolution => "ReducedResolution"; |
|
343 single page => "SinglePage".</td> |
|
344 </tr> |
|
345 <tr> |
|
346 <td>/Document/ImageCreationTime@value</td> |
|
347 <td>DateTime</td> |
|
348 </tr> |
|
349 <tr> |
|
350 <td>/Text/TextEntry</td> |
|
351 <td>DocumentName, ImageDescription, Make, Model, PageName, Software, |
|
352 Artist, HostComputer, InkNames, Copyright: |
|
353 /Text/TextEntry@keyword = field name, |
|
354 /Text/TextEntry@value = field value.<br> |
|
355 Example: TIFF Software field => /Text/TextEntry@keyword = "Software", |
|
356 /Text/TextEntry@value = Name and version number of the software package(s) |
|
357 used to create the image.</td> |
|
358 </tr> |
|
359 <tr> |
|
360 <td>/Transparency/Alpha@value</td> |
|
361 <td>ExtraSamples: associated alpha => "premultiplied"; |
|
362 unassociated alpha => "nonpremultiplied".</td> |
|
363 </tr> |
|
364 </table> |
|
365 </p> |
|
366 |
|
367 <h4><a name="ExifRead"/>Reading Exif Images</h4> |
|
368 |
|
369 The TIFF reader may be used to read an uncompressed Exif image or the |
|
370 contents of the <tt>APP1</tt> marker segment of a compressed Exif image. |
|
371 |
|
372 <h5><a name="ExifReadTIFF"/>Reading Uncompressed Exif Images</h5> |
|
373 |
|
374 An uncompressed Exif image is a one- or two-page uncompressed TIFF image |
|
375 with a specific ordering of its IFD and image data content. Each pixel |
|
376 has three 8-bit samples with photometric interpretation RGB or YCbCr. |
|
377 The image stream must contain a single primary image and may contain a |
|
378 single thumbnail which if present must also be uncompressed. The usual |
|
379 <code>ImageReader</code> methods may be used to read the image |
|
380 data and metadata: |
|
381 |
|
382 <pre><code> |
|
383 ImageInputStream input; |
|
384 ImageReader tiffReader; |
|
385 ImageReadParam tiffReadParam; |
|
386 |
|
387 tiffReader.setInput(input); |
|
388 |
|
389 // Read primary image and IFD. |
|
390 BufferedImage image = tiffReader.read(0, tiffReadParam); |
|
391 IIOMetadata primaryIFD = tiffReader.getImageMetadata(0); |
|
392 |
|
393 // Read thumbnail if present. |
|
394 BufferedImage thumbnail = null; |
|
395 if (tiffReader.getNumImages(true) > 1) { |
|
396 thumbnail = tiffReader.read(1, tiffReadParam); |
|
397 } |
|
398 </code></pre> |
|
399 |
|
400 Note that the Exif thumbnail is treated as a separate page in the TIFF |
|
401 stream and not as a thumbnail, i.e., |
|
402 <code>tiffReader.hasThumbnails(0)</code> will return <code>false</code>. |
|
403 |
|
404 <h5><a name="ExifReadJPEG"/>Reading Compressed Exif Images</h5> |
|
405 |
|
406 A compressed Exif image is a 3-band ISO/IEC 10918-1 baseline DCT JPEG stream |
|
407 with an inserted <tt>APP1</tt> marker segment. The parameters of the marker |
|
408 segment after the length are the 6-byte sequence |
|
409 <code>{'E', 'x', 'i', 'f', 0x00, 0x00}</code></code> |
|
410 followed by a complete TIFF stream. The embedded TIFF stream contains a primary |
|
411 IFD describing the JPEG image optionally followed by a thumbnail IFD and |
|
412 compressed or uncompressed thumbnail image data. Note that the embedded TIFF |
|
413 stream does not contain any image data associated with the primary IFD |
|
414 nor any descriptive fields which duplicate information found in the JPEG |
|
415 stream itself. |
|
416 |
|
417 <p>The parameter content of the <tt>APP1</tt> marker segment may be obtained |
|
418 from the user object of the associated <code>Node</code> in a |
|
419 <tt>javax_imageio_jpeg_image_1.0</tt> native image metadata tree extracted |
|
420 from the image metadata object returned by the JPEG reader. This APP1 Exif |
|
421 node will be a child of the node named "markerSequence" and will |
|
422 have name <tt>unknown</tt> and an attribute named <tt>MarkerTag</tt> with |
|
423 integral value <code>0xE1</code> (<code>String</code> value |
|
424 <code>"225"</code>). The user object of this node will be a byte array |
|
425 which starts with the six bytes <code>{'E', 'x', 'i', 'f', '0', '0'}</code>. |
|
426 The primary IFD and the thumbnail IFD and image may be |
|
427 read from the user object by the usual <code>ImageReader</code> |
|
428 methods: |
|
429 |
|
430 <pre><code> |
|
431 ImageReader jpegReader; |
|
432 ImageReader tiffReader; |
|
433 |
|
434 // Obtain the APP1 Exif marker data from the JPEG image metadata. |
|
435 IIOMetadata jpegImageMetadata = jpegReader.getImageMetadata(0); |
|
436 String nativeFormat = jpegImageMetadata.getNativeMetadataFormatName(); |
|
437 Node jpegImageMetadataTree = jpegImageMetadata.getAsTree(nativeFormat); |
|
438 |
|
439 // getExifMarkerData() returns the byte array which is the user object |
|
440 // of the APP1 Exif marker node. |
|
441 byte[] app1Params = getExifMarkerData(jpegImageMetadataTree); |
|
442 if (app1Params == null) { |
|
443 throw new IIOException("APP1 Exif marker not found."); |
|
444 } |
|
445 |
|
446 // Set up input, skipping Exif ID 6-byte sequence. |
|
447 MemoryCacheImageInputStream app1ExifInput |
|
448 = new MemoryCacheImageInputStream |
|
449 (new ByteArrayInputStream(app1Params, 6, app1Params.length - 6)); |
|
450 tiffReader.setInput(app1ExifInput); |
|
451 |
|
452 // Read primary IFD. |
|
453 IIOMetadata primaryIFD = tiffReader.getImageMetadata(0); |
|
454 |
|
455 // Read thumbnail if present. |
|
456 BufferedImage thumbnail = null; |
|
457 if (tiffReader.getNumImages(true) > 1) { |
|
458 thumbnail = tiffReader.read(1, tiffReadParam); |
|
459 } |
|
460 |
|
461 // Read the primary image. |
|
462 BufferedImage image = jpegReader.read(0); |
|
463 </code></pre> |
|
464 |
|
465 Note that <code>tiffReader.getNumImages(true)</code> returns the number of |
|
466 IFDs in the embedded TIFF stream including those corresponding to empty |
|
467 images. Calling <code>tiffReader.read(0, readParam)</code> will throw |
|
468 an exception as the primary image in the embedded TIFF stream is always |
|
469 empty; the primary image should be obtained using the JPEG reader itself. |
|
470 </p> |
|
471 |
|
472 <h3><a name="Writing"/>Writing Images</h3> |
|
473 |
|
474 TIFF images are written by a <a href="../../ImageWriter.html">ImageWriter</a> which may be |
|
475 controlled by its public interface as well as via a supplied |
|
476 <a href="../../ImageWriteParam.html">ImageWriteParam</a>. For an <code>ImageWriteParam</code> returned |
|
477 by the <code>getDefaultWriteParam()</code> method of the TIFF <code>ImageWriter</code>, |
|
478 the <code>canWriteTiles()</code> and <code>canWriteCompressed()</code> methods |
|
479 will return <code>true</code>; the <code>canOffsetTiles()</code> and |
|
480 <code>canWriteProgressive()</code> methods will return <code>false</code>.</p> |
|
481 |
|
482 The TIFF writer supports many optional capabilities including writing tiled |
|
483 images, inserting images, writing or inserting empty images, and replacing image |
|
484 data. Pixels may be replaced in either empty or non-empty images but if and |
|
485 only if the data are not compressed. |
|
486 |
|
487 <p> If tiles are being written, then each of their dimensions will be |
|
488 rounded to the nearest multiple of 16 per the TIFF specification. If |
|
489 JPEG-in-TIFF compression is being used, and tiles are being written |
|
490 each tile dimension will be rounded to the nearest multiple of 8 times |
|
491 the JPEG minimum coded unit (MCU) in that dimension. If JPEG-in-TIFF |
|
492 compression is being used and strips are being written, the number of |
|
493 rows per strip is rounded to a multiple of 8 times the maximum MCU over |
|
494 both dimensions.</p> |
|
495 |
|
496 <!-- <h4>Supported Image Types</h4> --> |
|
497 |
|
498 <!-- Table? --> |
|
499 |
|
500 <h4><a name="Compression"/>Compression</h4> |
|
501 |
|
502 The compression type may be set via the <code>setCompressionType()</code> method of |
|
503 the <code>ImageWriteParam</code> after setting the compression mode to |
|
504 <code>MODE_EXPLICIT</code>. The set of innately |
|
505 supported compression types is listed in the following table: |
|
506 |
|
507 <table border=1> |
|
508 <caption><b>Supported Compression Types</b></caption> |
|
509 <tr><th>Compression Type</th> <th>Description</th> <th>Reference</th></tr> |
|
510 <tr> |
|
511 <td>CCITT RLE</td> |
|
512 <td>Modified Huffman compression</td> |
|
513 <td>TIFF 6.0 Specification, Section 10</td> |
|
514 </tr> |
|
515 <tr> |
|
516 <td>CCITT T.4</td> |
|
517 <td>CCITT T.4 bilevel encoding/Group 3 facsimile compression</td> |
|
518 <td>TIFF 6.0 Specification, Section 11</td> |
|
519 </tr> |
|
520 <tr> |
|
521 <td>CCITT T.6</td> |
|
522 <td>CCITT T.6 bilevel encoding/Group 4 facsimile compression</td> |
|
523 <td>TIFF 6.0 Specification, Section 11</td></tr> |
|
524 <tr> |
|
525 <td>LZW</td> |
|
526 <td>LZW compression</td> |
|
527 <td>TIFF 6.0 Specification, Section 13</td></tr> |
|
528 <tr> |
|
529 <td>JPEG</td> |
|
530 <td>"New" JPEG-in-TIFF compression</td> |
|
531 <td><a href="ftp://ftp.sgi.com/graphics/tiff/TTN2.draft.txt">TIFF |
|
532 Technical Note #2</a></td> |
|
533 </tr> |
|
534 <tr> |
|
535 <td>ZLib</td> |
|
536 <td>"Deflate/Inflate" compression (see note following this table)</td> |
|
537 <td><a href="http://partners.adobe.com/asn/developer/pdfs/tn/TIFFphotoshop.pdf"> |
|
538 Adobe Photoshop® TIFF Technical Notes</a> (PDF)</td> |
|
539 </tr> |
|
540 <tr> |
|
541 <td>PackBits</td> |
|
542 <td>Byte-oriented, run length compression</td> |
|
543 <td>TIFF 6.0 Specification, Section 9</td> |
|
544 </tr> |
|
545 <tr> |
|
546 <td>Deflate</td> |
|
547 <td>"Zip-in-TIFF" compression (see note following this table)</td> |
|
548 <td><a href="http://www.isi.edu/in-notes/rfc1950.txt"> |
|
549 ZLIB Compressed Data Format Specification</a>, |
|
550 <a href="http://www.isi.edu/in-notes/rfc1951.txt"> |
|
551 DEFLATE Compressed Data Format Specification</a></td> |
|
552 </tr> |
|
553 <tr> |
|
554 <td>Exif JPEG</td> |
|
555 <td>Exif-specific JPEG compression (see note following this table)</td> |
|
556 <td><a href="http://www.exif.org/Exif2-2.PDF">Exif 2.2 Specification</a> |
|
557 (PDF), section 4.5.5, "Basic Structure of Thumbnail Data"</td> |
|
558 </table> |
|
559 |
|
560 <p> |
|
561 Old-style JPEG compression as described in section 22 of the TIFF 6.0 |
|
562 Specification is <i>not</i> supported. |
|
563 </p> |
|
564 |
|
565 <p> The CCITT compression types are applicable to bilevel (1-bit) |
|
566 images only. The JPEG compression type is applicable to byte |
|
567 grayscale (1-band) and RGB (3-band) images only.</p> |
|
568 |
|
569 <p> |
|
570 ZLib and Deflate compression are identical except for the value of the |
|
571 TIFF Compression field: for ZLib the Compression field has value 8 |
|
572 whereas for Deflate it has value 32946 (0x80b2). In both cases each |
|
573 image segment (strip or tile) is written as a single complete zlib data |
|
574 stream. |
|
575 </p> |
|
576 |
|
577 <p> |
|
578 "Exif JPEG" is a compression type used when writing the contents of an |
|
579 APP1 Exif marker segment for inclusion in a JPEG native image metadata |
|
580 tree. The contents appended to the output when this compression type is |
|
581 used are a function of whether an empty or non-empty image is written. |
|
582 If the image is empty, then a TIFF IFD adhering to the specification of |
|
583 a compressed Exif primary IFD is appended. If the image is non-empty, |
|
584 then a complete IFD and image adhering to the specification of a |
|
585 compressed Exif thumbnail IFD and image are appended. Note that the |
|
586 data of the empty image may <i>not</i> later be appended using the pixel |
|
587 replacement capability of the TIFF writer. |
|
588 </p> |
|
589 |
|
590 <p> If ZLib/Deflate or JPEG compression is used, the compression quality |
|
591 may be set. For ZLib/Deflate the supplied floating point quality value is |
|
592 rescaled to the range <tt>[1, 9]</tt> and truncated to an integer |
|
593 to derive the Deflate compression level. For JPEG the floating point |
|
594 quality value is passed directly to the JPEG writer plug-in which |
|
595 interprets it in the usual way.</p> |
|
596 |
|
597 <h4><a name="ColorConversionWrite"/>Color Conversion</h4> |
|
598 |
|
599 <p>If the source image data |
|
600 color space type is RGB, and the destination photometric type is CIE L*a*b* or |
|
601 YCbCr, then the source image data will be automatically converted from |
|
602 RGB using an internal color converter.</p> |
|
603 |
|
604 <h4><a name="ICCProfilesWrite"/>ICC Profiles</h4> |
|
605 |
|
606 An <tt>ICC Profile</tt> field will be written if either: |
|
607 <ul> |
|
608 <li>one is present in the native image metadata |
|
609 <a href="../IIOMetadata.html">IIOMetadata</a> instance supplied to the writer, |
|
610 or</li> |
|
611 <li>the <a href="../../../../java/awt/color/ColorSpace.html">ColorSpace</a> |
|
612 of the destination <code>ImageTypeSpecifier</code> is an instance of |
|
613 <code>ICC_ColorSpace</code> which is not one of the standard |
|
614 color spaces defined by the <tt>CS_*</tt> constants in the |
|
615 <code>ColorSpace</code> class. The destination type is set via |
|
616 <code>ImageWriteParam.setDestinationType(ImageTypeSpecifier)</code> and defaults |
|
617 to the <code>ImageTypeSpecifier</code> of the image being written. |
|
618 </li> |
|
619 </ul> |
|
620 |
|
621 <h4><a name="MetadataIssuesWrite"/>Metadata Issues</h4> |
|
622 |
|
623 Some behavior of the writer is affected by or may affect the contents of |
|
624 the image metadata which may be supplied by the user. |
|
625 |
|
626 <p>For bilevel images, the <tt>FillOrder</tt>, and <tt>T4Options</tt> |
|
627 fields affect the output data. The data will be filled right-to-left if |
|
628 <tt>FillOrder</tt> is present with a value of 2 |
|
629 (<code>BaselineTIFFTagSet.FILL_ORDER_RIGHT_TO_LEFT</code>) |
|
630 and will be filled left-to-right otherwise. The value of <tt>T4Options</tt> |
|
631 specifies whether the data should be 1D- or 2D-encoded and whether EOL |
|
632 padding should be used.</p> |
|
633 |
|
634 <p>For all images the value of the <tt>RowsPerStrip</tt> field is used |
|
635 to the set the number of rows per strip if the image is not tiled. The |
|
636 default number of rows per strip is either 8 or the number of rows which |
|
637 would fill no more than 8 kilobytes, whichever is larger.</p> |
|
638 |
|
639 <p>For all images the tile dimensions may be set using the <tt>TileWidth</tt> |
|
640 and <tt>TileLength</tt> field values if the tiling mode is |
|
641 <code>ImageWriteParam.MODE_COPY_FROM_METADATA</code>. If this mode |
|
642 is set but the fields are not, their respective default values are the image |
|
643 width and height.</p> |
|
644 |
|
645 <p>When using JPEG-in-TIFF compression, a <tt>JPEGTables</tt> field will be |
|
646 written to the IFD and abbreviated JPEG streams to each strip or tile if and |
|
647 only if a <tt>JPEGTables</tt> field is contained in the metadata object |
|
648 provided to the writer. If the contents of the <tt>JPEGTables</tt> field is |
|
649 a valid tables-only JPEG stream, then it will be used; otherwise the contents |
|
650 of the field will be replaced with default visually lossless tables. If no |
|
651 such <tt>JPEGTables</tt> field is present in the metadata, then no |
|
652 <tt>JPEGTables</tt> field will be written to the output and each strip or |
|
653 tile will be written as a separate, self-contained JPEG stream.</p> |
|
654 |
|
655 <p>When using Deflate/ZLib or LZW compression, if the image has 8 bits per |
|
656 sample, a horizontal differencing predictor will be used if the |
|
657 <tt>Predictor</tt> field is present with a value of 2 |
|
658 (<code>BaselineTIFFTagSet.PREDICTOR_HORIZONTAL_DIFFERENCING</code>). |
|
659 If prediction is so requested but the image does not have |
|
660 8 bits per sample the field will be reset to have the value 1 |
|
661 (<code>BaselineTIFFTagSet.PREDICTOR_NONE</code>). |
|
662 </p> |
|
663 |
|
664 <p>Some fields may be added or modified: |
|
665 |
|
666 <ul> |
|
667 <li><tt>PhotometricInterpretation</tt> if not present.</li> |
|
668 <li><tt>PlanarConfiguration</tt> if this field is present with value |
|
669 <tt>Planar</tt> is is reset to <tt>Chunky</tt>.</li> |
|
670 <li><tt>Compression</tt> always.</li> |
|
671 <li><tt>BitsPerSample</tt> if the image is not bilevel.</li> |
|
672 <li><tt>SamplesPerPixel</tt> always.</li> |
|
673 <li><tt>ExtraSamples</tt> if an alpha channel is present.</li> |
|
674 <li><tt>SampleFormat</tt> if not present and the data are 16- or 32-bit |
|
675 integers or floating point.</li> |
|
676 <li><tt>ColorMap</tt> if the <tt>PhotometricInterpretation</tt> is |
|
677 <tt>RGBPalette</tt>.</li> |
|
678 <li><tt>ImageWidth</tt> and <tt>ImageLength</tt> always.</li> |
|
679 <li><tt>TileWidth</tt>, <tt>TileLength</tt>, <tt>TileOffsets</tt>, and |
|
680 <tt>TileByteCounts</tt> if a tiled image is being written.</li> |
|
681 <li><tt>RowsPerStrip</tt>, <tt>StripOffsets</tt>, and <tt>StripByteCounts</tt> |
|
682 if a tiled image is <i>not</i> being written.</li> |
|
683 <li><tt>XResolution</tt>, <tt>YResolution</tt>, and <tt>ResolutionUnit</tt> |
|
684 if none of these is present.</li> |
|
685 <li><tt>YCbCrSubsampling</tt> and <tt>YCbCrPositioning</tt> if the |
|
686 photometric interpretation is YCbCr and the compression type is not JPEG |
|
687 (only [1, 1] subsampling and cosited positioning are supported for |
|
688 non-JPEG YCbCr output).</li> |
|
689 <li><tt>YCbCrSubsampling</tt>, <tt>YCbCrPositioning</tt>, and |
|
690 <tt>ReferenceBlackWhite</tt>: if the compression type is JPEG and the color |
|
691 space is RGB these will be reset to [2, 2] centered subsampling with no |
|
692 headroom/footroom (0:255,128:255,128:255).</li> |
|
693 </ul> |
|
694 |
|
695 <p>Some fields may be removed: |
|
696 |
|
697 <ul> |
|
698 <li><tt>BitsPerSample</tt> if the image is bilevel.</li> |
|
699 <li><tt>ExtraSamples</tt> if the image does not have an alpha channel.</li> |
|
700 <li><tt>ColorMap</tt> if the photometric interpretation is not |
|
701 <tt>RGBPalette</tt>.</li> |
|
702 <li><tt>TileWidth</tt>, <tt>TileLength</tt>, <tt>TileOffsets</tt>, and |
|
703 <tt>TileByteCounts</tt> if tiling <i>is not</i> being used.</li> |
|
704 <li><tt>RowsPerStrip</tt>, <tt>StripOffsets</tt>, and <tt>StripByteCounts</tt> |
|
705 if tiling <i>is</i> being used.</li> |
|
706 <li><tt>YCbCrSubsampling</tt>, <tt>YCbCrPositioning</tt>, and |
|
707 <tt>ReferenceBlackWhite</tt> if the compression type is JPEG and the |
|
708 color space is grayscale.</li> |
|
709 <li><tt>JPEGProc</tt>, <tt>JPEGInterchangeFormat</tt>, |
|
710 <tt>JPEGInterchangeFormatLength</tt>, <tt>JPEGRestartInterval</tt>, |
|
711 <tt>JPEGLosslessPredictors</tt>, <tt>JPEGPointTransforms</tt>, |
|
712 <tt>JPEGQTables</tt>, <tt>JPEGDCTables</tt>, and |
|
713 <tt>JPEGACTables</tt> if the compression type is JPEG.</li> |
|
714 </ul> |
|
715 </p> |
|
716 |
|
717 <p>Other fields present in the supplied metadata are uninterpreted and will |
|
718 be written as supplied.</p> |
|
719 |
|
720 <p>If an Exif image is being written, the set of fields present and their |
|
721 values will be modified such that the result is in accord with the Exif 2.2 |
|
722 specification.</p> |
|
723 |
|
724 <p>Setting up the image metadata to write to a TIFF stream may be simplified |
|
725 by using the <code>TIFFDirectory</code> class |
|
726 which represents a TIFF IFD. A field in a TIFF IFD is represented by an |
|
727 instance of <a href="../../plugins/tiff/TIFFField.html">TIFFField</a>. For each |
|
728 field to be written a <code>TIFFField</code> may be added to the |
|
729 <code>TIFFDirectory</code> and the latter converted to an |
|
730 <code>IIOMetadata</code> object by invoking |
|
731 <code>TIFFDirectory.getAsMetadata</code>. The |
|
732 <code>IIOMetadata</code> object so obtained may then be passed to the TIFF |
|
733 writer.</p> |
|
734 |
|
735 <h5><a name="MapStandardNative"/> |
|
736 Mapping of the Standard Metadata Format to TIFF Native Image Metadata</h5> |
|
737 |
|
738 The derivation of <a href="#ImageMetadata">TIFF native image metadata</a> |
|
739 elements from the standard metadata format |
|
740 <a href="standard_metadata.html">javax_imageio_1.0</a> is |
|
741 given in the following table. |
|
742 |
|
743 <p> |
|
744 <table border="1"> |
|
745 <tr> |
|
746 <th>TIFF Field</th> |
|
747 <th>Derivation from Standard Metadata Elements</th> |
|
748 </tr> |
|
749 <tr> |
|
750 <td> |
|
751 PhotometricInterpretation |
|
752 </td> |
|
753 <td>/Chroma/ColorSpaceType@name: "GRAY" and /Chroma/BlackIsZero@value = "FALSE" |
|
754 => WhiteIsZero; "GRAY" and /Document/SubimageInterpretation@value = |
|
755 "TransparencyMask" => TransparencyMask; "RGB" and /Chroma/Palette present => |
|
756 PaletteColor; "GRAY" => BlackIsZero; "RGB" => RGB; "YCbCr" => YCbCr; |
|
757 "CMYK" => CMYK; "Lab" => CIELab.</td> |
|
758 </tr> |
|
759 <tr> |
|
760 <td>SamplesPerPixel</td> |
|
761 <td>/Chroma/NumChannels@value</td> |
|
762 </tr> |
|
763 <tr> |
|
764 <td>ColorMap</td> |
|
765 <td>/Chroma/Palette</td> |
|
766 </tr> |
|
767 <tr> |
|
768 <td>Compression</td> |
|
769 <td>/Compression/CompressionTypeName@value: "none" => Uncompressed; |
|
770 "CCITT RLE" => CCITT 1D; "CCITT T.4" => Group 3 Fax; "CCITT T.6" => Group 4 |
|
771 Fax; "LZW" => LZW; "Old JPEG" => JPEG; "JPEG" => New JPEG; "ZLib" => ZLib; |
|
772 "PackBits" => PackBits; "Deflate" => Deflate.</td> |
|
773 </tr> |
|
774 <tr> |
|
775 <td>PlanarConfiguration</td> |
|
776 <td>/Data/PlanarConfiguration@value: "PixelInterleaved" => Chunky; |
|
777 "PlaneInterleaved" => Planar.</td> |
|
778 </tr> |
|
779 <tr> |
|
780 <td>SampleFormat</td> |
|
781 <td>/Data/SampleFormat@value: "SignedIntegral" => two's complement signed |
|
782 integer data; "UnsignedIntegral" => unsigned integer data; "Real" => |
|
783 IEEE floating point data; "Index" => unsigned integer data. |
|
784 </td> |
|
785 </tr> |
|
786 <tr> |
|
787 <td>BitsPerSample</td> |
|
788 <td>/Data/BitsPerSample@value: space-separated list parsed to char array.</td> |
|
789 </tr> |
|
790 <tr> |
|
791 <td>FillOrder</td> |
|
792 <td>/Data/SampleMSB@value: if all values in space-separated list are 0s => |
|
793 right-to-left; otherwise => left-to-right. |
|
794 </td> |
|
795 </tr> |
|
796 <tr> |
|
797 <td>XResolution</td> |
|
798 <td>(10 / /Dimension/HorizontalPixelSize@value) or |
|
799 (10 / (/Dimension/VerticalPixelSize@value * |
|
800 /Dimension/PixelAspectRatio@value))</td> |
|
801 </tr> |
|
802 <tr> |
|
803 <td>YResolution</td> |
|
804 <td>(10 / /Dimension/VerticalPixelSize@value) or |
|
805 (10 / (/Dimension/HorizontalPixelSize@value / |
|
806 /Dimension/PixelAspectRatio@value))</td> |
|
807 </tr> |
|
808 <tr> |
|
809 <td>ResolutionUnit</td> |
|
810 <td>Centimeter if XResolution or YResolution set; otherwise None.</td> |
|
811 </tr> |
|
812 <tr> |
|
813 <td>Orientation</td> |
|
814 <td>/Dimension/ImageOrientation@value</td> |
|
815 </tr> |
|
816 <tr> |
|
817 <td>XPosition</td> |
|
818 <td>/Dimension/HorizontalPosition@value / 10</td> |
|
819 </tr> |
|
820 <tr> |
|
821 <td>YPosition</td> |
|
822 <td>/Dimension/VerticalPosition@value / 10</td> |
|
823 </tr> |
|
824 <tr> |
|
825 <td>NewSubFileType</td> |
|
826 <td>/Document/SubimageInterpretation@value: "TransparencyMask" => |
|
827 transparency mask; "ReducedResolution" => reduced-resolution; |
|
828 "SinglePage" => single page.</td> |
|
829 </tr> |
|
830 <tr> |
|
831 <td>DateTime</td> |
|
832 <td>/Document/ImageCreationTime@value</td> |
|
833 </tr> |
|
834 <tr> |
|
835 <td>DocumentName, ImageDescription, Make, Model, PageName, Software, |
|
836 Artist, HostComputer, InkNames, Copyright</td> |
|
837 <td>/Text/TextEntry: if /Text/TextEntry@keyword is the name of any of the |
|
838 TIFF Fields, e.g., "Software", then the field is added with content |
|
839 /Text/TextEntry@value and count 1.</td> |
|
840 </tr> |
|
841 <tr> |
|
842 <td>ExtraSamples</td> |
|
843 <td>/Transparency/Alpha@value: "premultiplied" => associated alpha, count 1; |
|
844 "nonpremultiplied" => unassociated alpha, count 1.</td> |
|
845 </tr> |
|
846 <tr> |
|
847 <td></td> |
|
848 <td></td> |
|
849 </tr> |
|
850 </table> |
|
851 </p> |
|
852 |
|
853 <h4><a name="ExifWrite"/>Writing Exif Images</h4> |
|
854 |
|
855 The TIFF writer may be used to write an uncompressed Exif image or the |
|
856 contents of the <tt>APP1</tt> marker segment of a compressed Exif image. |
|
857 |
|
858 <h5><a name="ExifWriteTIFF"/>Writing Uncompressed Exif Images</h5> |
|
859 |
|
860 When writing a sequence of images each image is normally recorded as |
|
861 {IFD, IFD Value, Image Data}. The Exif specification requires |
|
862 that an uncompressed Exif image be structured as follows: |
|
863 |
|
864 <ol> |
|
865 <a name="ExifStructure"/> |
|
866 <li>Image File Header</li> |
|
867 <li>Primary IFD</li> |
|
868 <li>Primary IFD Value</li> |
|
869 <li>Thumbnail IFD</li> |
|
870 <li>Thumbnail IFD Value</li> |
|
871 <li>Thumbnail Image Data</li> |
|
872 <li>Primary Image Data</li> |
|
873 </ol> |
|
874 |
|
875 To meet the requirement of the primary image data being recorded last, the |
|
876 primary image must be written initially as an empty image and have its data |
|
877 added via pixel replacement after the thumbnail IFD and image data have been |
|
878 written: |
|
879 |
|
880 <pre><code> |
|
881 ImageWriter tiffWriter; |
|
882 ImageWriteParam tiffWriteParam; |
|
883 IIOMetadata tiffStreamMetadata; |
|
884 IIOMetadata primaryIFD; |
|
885 BufferedImage image; |
|
886 BufferedImage thumbnail; |
|
887 |
|
888 // Specify uncompressed output. |
|
889 tiffWriteParam.setCompressionMode(ImageWriteParam.MODE_DISABLED); |
|
890 |
|
891 if (thumbnail != null) { |
|
892 // Write the TIFF header. |
|
893 tiffWriter.prepareWriteSequence(tiffStreamMetadata); |
|
894 |
|
895 // Append the primary IFD. |
|
896 tiffWriter.prepareInsertEmpty(-1, // append |
|
897 new ImageTypeSpecifier(image), |
|
898 image.getWidth(), |
|
899 image.getHeight(), |
|
900 primaryIFD, |
|
901 null, // thumbnails |
|
902 tiffWriteParam); |
|
903 tiffWriter.endInsertEmpty(); |
|
904 |
|
905 // Append the thumbnail image data. |
|
906 tiffWriter.writeToSequence(new IIOImage(thumbnail, null, null), |
|
907 tiffWriteParam); |
|
908 |
|
909 // Insert the primary image data. |
|
910 tiffWriter.prepareReplacePixels(0, new Rectangle(image.getWidth(), |
|
911 image.getHeight())); |
|
912 tiffWriter.replacePixels(image, tiffWriteParam); |
|
913 tiffWriter.endReplacePixels(); |
|
914 |
|
915 // End writing. |
|
916 tiffWriter.endWriteSequence(); |
|
917 } else { |
|
918 // Write only the primary IFD and image data. |
|
919 tiffWriter.write(tiffStreamMetadata, |
|
920 new IIOImage(image, null, primaryIFD), |
|
921 tiffWriteParam); |
|
922 } |
|
923 </code></pre> |
|
924 |
|
925 <h5><a name="ExifWriteJPEG"/>Writing Compressed Exif Images</h5> |
|
926 |
|
927 The structure of the embedded TIFF stream in the <tt>APP1</tt> segment of a |
|
928 compressed Exif image is identical to the <a href="#ExifStructure"> |
|
929 uncompressed Exif image structure</a> except that there are no primary |
|
930 image data, i.e., the primary IFD does not refer to any image data. |
|
931 |
|
932 <pre><code> |
|
933 ImageWriter tiffWriter; |
|
934 ImageWriteParam tiffWriteParam; |
|
935 IIOMetadata tiffStreamMetadata; |
|
936 BufferedImage image; |
|
937 BufferedImage thumbnail; |
|
938 IIOMetadata primaryIFD; |
|
939 ImageOutputStream output; |
|
940 |
|
941 // Set up an output to contain the APP1 Exif TIFF stream. |
|
942 ByteArrayOutputStream baos = new ByteArrayOutputStream(); |
|
943 MemoryCacheImageOutputStream app1ExifOutput = |
|
944 new MemoryCacheImageOutputStream(baos); |
|
945 tiffWriter.setOutput(app1ExifOutput); |
|
946 |
|
947 // Set compression for the thumbnail. |
|
948 tiffWriteParam.setCompressionMode(ImageWriteParam.MODE_EXPLICIT); |
|
949 tiffWriteParam.setCompressionType("Exif JPEG"); |
|
950 |
|
951 // Write the APP1 Exif TIFF stream. |
|
952 if (thumbnail != null) { |
|
953 // Write the TIFF header. |
|
954 tiffWriter.prepareWriteSequence(tiffStreamMetadata); |
|
955 |
|
956 // Append the primary IFD. |
|
957 tiffWriter.prepareInsertEmpty(-1, // append |
|
958 new ImageTypeSpecifier(image), |
|
959 image.getWidth(), |
|
960 image.getHeight(), |
|
961 primaryIFD, |
|
962 null, // thumbnails |
|
963 tiffWriteParam); |
|
964 tiffWriter.endInsertEmpty(); |
|
965 |
|
966 // Append the thumbnail IFD and image data. |
|
967 tiffWriter.writeToSequence(new IIOImage(thumbnail, null, |
|
968 null), tiffWriteParam); |
|
969 |
|
970 // End writing. |
|
971 tiffWriter.endWriteSequence(); |
|
972 } else { |
|
973 // Write only the primary IFD. |
|
974 tiffWriter.prepareWriteEmpty(tiffStreamMetadata, |
|
975 new ImageTypeSpecifier(image), |
|
976 image.getWidth(), |
|
977 image.getHeight(), |
|
978 primaryIFD, |
|
979 null, // thumbnails |
|
980 tiffWriteParam); |
|
981 tiffWriter.endWriteEmpty(); |
|
982 } |
|
983 |
|
984 // Flush data into byte stream. |
|
985 app1ExifOutput.flush(); |
|
986 |
|
987 // Create APP1 parameter array. |
|
988 byte[] app1Parameters = new byte[6 + baos.size()]; |
|
989 |
|
990 // Add APP1 Exif ID bytes. |
|
991 app1Parameters[0] = (byte) 'E'; |
|
992 app1Parameters[1] = (byte) 'x'; |
|
993 app1Parameters[2] = (byte) 'i'; |
|
994 app1Parameters[3] = (byte) 'f'; |
|
995 app1Parameters[4] = app1Parameters[5] = (byte) 0; |
|
996 |
|
997 // Append TIFF stream to APP1 parameters. |
|
998 System.arraycopy(baos.toByteArray(), 0, app1Parameters, 6, baos.size()); |
|
999 |
|
1000 // Create the APP1 Exif node to be added to native JPEG image metadata. |
|
1001 IIOMetadataNode app1Node = new IIOMetadataNode("unknown"); |
|
1002 app1Node.setAttribute("MarkerTag", String.valueOf(0xE1)); |
|
1003 app1Node.setUserObject(app1Parameters); |
|
1004 |
|
1005 // Append the APP1 Exif marker to the "markerSequence" node. |
|
1006 IIOMetadata jpegImageMetadata = |
|
1007 jpegWriter.getDefaultImageMetadata(new ImageTypeSpecifier(image), |
|
1008 jpegWriteParam); |
|
1009 String nativeFormat = jpegImageMetadata.getNativeMetadataFormatName(); |
|
1010 Node tree = jpegImageMetadata.getAsTree(nativeFormat); |
|
1011 NodeList children = tree.getChildNodes(); |
|
1012 int numChildren = children.getLength(); |
|
1013 for (int i = 0; i < numChildren; i++) { |
|
1014 Node child = children.item(i); |
|
1015 if (child.getNodeName().equals("markerSequence")) { |
|
1016 child.appendChild(app1Node); |
|
1017 break; |
|
1018 } |
|
1019 } |
|
1020 jpegImageMetadata.setFromTree(nativeFormat, tree); |
|
1021 |
|
1022 // Write the JPEG image data including the APP1 Exif marker. |
|
1023 jpegWriter.setOutput(output); |
|
1024 jpegWriter.write(new IIOImage(image, null, jpegImageMetadata)); |
|
1025 </code></pre> |
|
1026 |
|
1027 The <code>"unknown"</code> node created above would be appended to the |
|
1028 <code>"markerSequence"</code> node of the native JPEG image metadata |
|
1029 and written to the JPEG stream when the primary image is written using |
|
1030 the JPEG writer. |
|
1031 |
|
1032 <h3><a name="StreamMetadata"/>Stream Metadata</h3> |
|
1033 |
|
1034 The DTD for the TIFF native stream metadata format is as follows: |
|
1035 |
|
1036 <pre> |
|
1037 <!DOCTYPE "javax_imageio_tiff_stream_1.0" [ |
|
1038 |
|
1039 <!ELEMENT "javax_imageio_tiff_stream_1.0" (ByteOrder)> |
|
1040 |
|
1041 <!ELEMENT "ByteOrder" EMPTY> |
|
1042 <!-- The stream byte order --> |
|
1043 <!ATTLIST "ByteOrder" "value" #CDATA #REQUIRED> |
|
1044 <!-- One of "BIG_ENDIAN" or "LITTLE_ENDIAN" --> |
|
1045 <!-- Data type: String --> |
|
1046 ]> |
|
1047 </pre> |
|
1048 |
|
1049 <h3><a name="ImageMetadata"/>Image Metadata</h3> |
|
1050 |
|
1051 The DTD for the TIFF native image metadata format is as follows: |
|
1052 |
|
1053 <pre> |
|
1054 <!DOCTYPE "javax_imageio_tiff_image_1.0" [ |
|
1055 |
|
1056 <!ELEMENT "javax_imageio_tiff_image_1.0" (TIFFIFD)*> |
|
1057 |
|
1058 <!ELEMENT "TIFFIFD" (TIFFField | TIFFIFD)*> |
|
1059 <!-- An IFD (directory) containing fields --> |
|
1060 <!ATTLIST "TIFFIFD" "tagSets" #CDATA #REQUIRED> |
|
1061 <!-- Data type: String --> |
|
1062 <!ATTLIST "TIFFIFD" "parentTagNumber" #CDATA #IMPLIED> |
|
1063 <!-- The tag number of the field pointing to this IFD --> |
|
1064 <!-- Data type: Integer --> |
|
1065 <!ATTLIST "TIFFIFD" "parentTagName" #CDATA #IMPLIED> |
|
1066 <!-- A mnemonic name for the field pointing to this IFD, if known |
|
1067 --> |
|
1068 <!-- Data type: String --> |
|
1069 |
|
1070 <!ELEMENT "TIFFField" (TIFFBytes | TIFFAsciis | |
|
1071 TIFFShorts | TIFFSShorts | TIFFLongs | TIFFSLongs | |
|
1072 TIFFRationals | TIFFSRationals | |
|
1073 TIFFFloats | TIFFDoubles | TIFFUndefined)> |
|
1074 <!-- A field containing data --> |
|
1075 <!ATTLIST "TIFFField" "number" #CDATA #REQUIRED> |
|
1076 <!-- The tag number asociated with the field --> |
|
1077 <!-- Data type: String --> |
|
1078 <!ATTLIST "TIFFField" "name" #CDATA #IMPLIED> |
|
1079 <!-- A mnemonic name associated with the field, if known --> |
|
1080 <!-- Data type: String --> |
|
1081 |
|
1082 <!ELEMENT "TIFFBytes" (TIFFByte)*> |
|
1083 <!-- A sequence of TIFFByte nodes --> |
|
1084 |
|
1085 <!ELEMENT "TIFFByte" EMPTY> |
|
1086 <!-- An integral value between 0 and 255 --> |
|
1087 <!ATTLIST "TIFFByte" "value" #CDATA #IMPLIED> |
|
1088 <!-- The value --> |
|
1089 <!-- Data type: String --> |
|
1090 <!ATTLIST "TIFFByte" "description" #CDATA #IMPLIED> |
|
1091 <!-- A description, if available --> |
|
1092 <!-- Data type: String --> |
|
1093 |
|
1094 <!ELEMENT "TIFFAsciis" (TIFFAscii)*> |
|
1095 <!-- A sequence of TIFFAscii nodes --> |
|
1096 |
|
1097 <!ELEMENT "TIFFAscii" EMPTY> |
|
1098 <!-- A String value --> |
|
1099 <!ATTLIST "TIFFAscii" "value" #CDATA #IMPLIED> |
|
1100 <!-- The value --> |
|
1101 <!-- Data type: String --> |
|
1102 |
|
1103 <!ELEMENT "TIFFShorts" (TIFFShort)*> |
|
1104 <!-- A sequence of TIFFShort nodes --> |
|
1105 |
|
1106 <!ELEMENT "TIFFShort" EMPTY> |
|
1107 <!-- An integral value between 0 and 65535 --> |
|
1108 <!ATTLIST "TIFFShort" "value" #CDATA #IMPLIED> |
|
1109 <!-- The value --> |
|
1110 <!-- Data type: String --> |
|
1111 <!ATTLIST "TIFFShort" "description" #CDATA #IMPLIED> |
|
1112 <!-- A description, if available --> |
|
1113 <!-- Data type: String --> |
|
1114 |
|
1115 <!ELEMENT "TIFFSShorts" (TIFFSShort)*> |
|
1116 <!-- A sequence of TIFFSShort nodes --> |
|
1117 |
|
1118 <!ELEMENT "TIFFSShort" EMPTY> |
|
1119 <!-- An integral value between -32768 and 32767 --> |
|
1120 <!ATTLIST "TIFFSShort" "value" #CDATA #IMPLIED> |
|
1121 <!-- The value --> |
|
1122 <!-- Data type: String --> |
|
1123 <!ATTLIST "TIFFSShort" "description" #CDATA #IMPLIED> |
|
1124 <!-- A description, if available --> |
|
1125 <!-- Data type: String --> |
|
1126 |
|
1127 <!ELEMENT "TIFFLongs" (TIFFLong)*> |
|
1128 <!-- A sequence of TIFFLong nodes --> |
|
1129 |
|
1130 <!ELEMENT "TIFFLong" EMPTY> |
|
1131 <!-- An integral value between 0 and 4294967295 --> |
|
1132 <!ATTLIST "TIFFLong" "value" #CDATA #IMPLIED> |
|
1133 <!-- The value --> |
|
1134 <!-- Data type: String --> |
|
1135 <!ATTLIST "TIFFLong" "description" #CDATA #IMPLIED> |
|
1136 <!-- A description, if available --> |
|
1137 <!-- Data type: String --> |
|
1138 |
|
1139 <!ELEMENT "TIFFSLongs" (TIFFSLong)*> |
|
1140 <!-- A sequence of TIFFSLong nodes --> |
|
1141 |
|
1142 <!ELEMENT "TIFFSLong" EMPTY> |
|
1143 <!-- An integral value between -2147483648 and 2147482647 --> |
|
1144 <!ATTLIST "TIFFSLong" "value" #CDATA #IMPLIED> |
|
1145 <!-- The value --> |
|
1146 <!-- Data type: String --> |
|
1147 <!ATTLIST "TIFFSLong" "description" #CDATA #IMPLIED> |
|
1148 <!-- A description, if available --> |
|
1149 <!-- Data type: String --> |
|
1150 |
|
1151 <!ELEMENT "TIFFRationals" (TIFFRational)*> |
|
1152 <!-- A sequence of TIFFRational nodes --> |
|
1153 |
|
1154 <!ELEMENT "TIFFRational" EMPTY> |
|
1155 <!-- A rational value consisting of an unsigned numerator and |
|
1156 denominator --> |
|
1157 <!ATTLIST "TIFFRational" "value" #CDATA #IMPLIED> |
|
1158 <!-- The numerator and denominator, separated by a slash --> |
|
1159 <!-- Data type: String --> |
|
1160 |
|
1161 <!ELEMENT "TIFFSRationals" (TIFFSRational)*> |
|
1162 <!-- A sequence of TIFFSRational nodes --> |
|
1163 |
|
1164 <!ELEMENT "TIFFSRational" EMPTY> |
|
1165 <!-- A rational value consisting of a signed numerator and |
|
1166 denominator --> |
|
1167 <!ATTLIST "TIFFSRational" "value" #CDATA #IMPLIED> |
|
1168 <!-- The numerator and denominator, separated by a slash --> |
|
1169 <!-- Data type: String --> |
|
1170 |
|
1171 <!ELEMENT "TIFFFloats" (TIFFFloat)*> |
|
1172 <!-- A sequence of TIFFFloat nodes --> |
|
1173 |
|
1174 <!ELEMENT "TIFFFloat" EMPTY> |
|
1175 <!-- A single-precision floating-point value --> |
|
1176 <!ATTLIST "TIFFFloat" "value" #CDATA #IMPLIED> |
|
1177 <!-- The value --> |
|
1178 <!-- Data type: String --> |
|
1179 |
|
1180 <!ELEMENT "TIFFDoubles" (TIFFDouble)*> |
|
1181 <!-- A sequence of TIFFDouble nodes --> |
|
1182 |
|
1183 <!ELEMENT "TIFFDouble" EMPTY> |
|
1184 <!-- A double-precision floating-point value --> |
|
1185 <!ATTLIST "TIFFDouble" "value" #CDATA #IMPLIED> |
|
1186 <!-- The value --> |
|
1187 <!-- Data type: String --> |
|
1188 |
|
1189 <!ELEMENT "TIFFUndefined" EMPTY> |
|
1190 <!-- Uninterpreted byte data --> |
|
1191 <!ATTLIST "TIFFUndefined" "value" #CDATA #IMPLIED> |
|
1192 <!-- A list of comma-separated byte values --> |
|
1193 <!-- Data type: String --> |
|
1194 ]> |
|
1195 </pre> |
|
1196 |
|
1197 @since 1.9 |
|
1198 |
|
1199 </body> |
|
1200 </html> |