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