< prev index next >

src/java.desktop/share/classes/javax/imageio/metadata/doc-files/tiff_metadata.html

Print this page


   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',&nbsp;'x',&nbsp;'i',&nbsp;'f',&nbsp;0x00,&nbsp;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,&nbsp;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,&nbsp;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,&nbsp;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,&nbsp;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,&nbsp;IFD Value,&nbsp;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 &lt;!DOCTYPE "javax_imageio_tiff_stream_1.0" [
1043 
1044   &lt;!ELEMENT "javax_imageio_tiff_stream_1.0" (ByteOrder)>
1045 
1046     &lt;!ELEMENT "ByteOrder" EMPTY&gt;
1047       &lt;!-- The stream byte order --&gt; 
1048       &lt;!ATTLIST "ByteOrder" "value" #CDATA #REQUIRED&gt;
1049         &lt;!-- One of "BIG_ENDIAN" or "LITTLE_ENDIAN" --&gt; 
1050         &lt;!-- Data type: String --&gt;
1051 ]&gt;
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 &lt;!DOCTYPE "javax_imageio_tiff_image_1.0" [
1060 
1061   &lt;!ELEMENT "javax_imageio_tiff_image_1.0" (TIFFIFD)*&gt;
1062 
1063     &lt;!ELEMENT "TIFFIFD" (TIFFField | TIFFIFD)*&gt;
1064       &lt;!-- An IFD (directory) containing fields --&gt; 
1065       &lt;!ATTLIST "TIFFIFD" "tagSets" #CDATA #REQUIRED&gt;
1066         &lt;!-- Data type: String --&gt;
1067       &lt;!ATTLIST "TIFFIFD" "parentTagNumber" #CDATA #IMPLIED&gt;
1068         &lt;!-- The tag number of the field pointing to this IFD --&gt; 
1069         &lt;!-- Data type: Integer --&gt;
1070       &lt;!ATTLIST "TIFFIFD" "parentTagName" #CDATA #IMPLIED&gt;
1071         &lt;!-- A mnemonic name for the field pointing to this IFD, if known 
1072              --&gt; 
1073         &lt;!-- Data type: String --&gt;
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 =&gt; "RGB"; CMYK =&gt; "CMYK";
 246 YCbCr =&gt; "YCbCr";
 247 CIELab, ICCLab =&gt; "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" &lt;=&gt; PhotometricInterpretation =&gt; 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 =&gt; "none"; CCITT 1D =&gt; "CCITT
 264 RLE";
 265 Group 3 Fax =&gt; "CCITT T.4"; Group 4 Fax =&gt; "CCITT T.6";
 266 LZW =&gt; "LZW";
 267 JPEG =&gt; "Old JPEG"; New JPEG =&gt; "JPEG"; Zlib =&gt;&gt; "ZLib"; PackBits =&gt;
 268 "PackBits";
 269 Deflate =&gt; "Deflate"; Exif JPEG =&gt; "JPEG".</td>
 270 </tr>
 271 <tr>
 272 <td>/Compression/Lossless@value</td>
 273 <td>Compression: JPEG or New JPEG =&gt; "FALSE"; otherwise "TRUE".</td>
 274 </tr>
 275 <tr>
 276 <td>/Data/PlanarConfiguration@value</td>
 277 <td>Chunky =&gt; "PixelInterleaved"; Planar =&gt; "PlaneInterleaved".</td>
 278 </tr>
 279 <tr>
 280 <td>/Data/SampleFormat@value</td>
 281 <td>PhotometricInterpretation PaletteColor =&gt; "Index";
 282 SampleFormat unsigned integer data =&gt; "UnsignedIntegral";
 283 SampleFormat two's complement signed integer data =&gt; "SignedIntegral";
 284 SampleFormat IEEE floating point data =&gt; "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 =&gt; space-separated list of BitsPerSample-1;
 295 right-to-left =&gt; 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 =&gt; "TransparencyMask";
 328 reduced-resolution =&gt; "ReducedResolution";
 329 single page =&gt; "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 =&gt; /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 =&gt; "premultiplied";
 348 unassociated alpha =&gt; "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',&nbsp;'x',&nbsp;'i',&nbsp;'f',&nbsp;0x00,&nbsp;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,&nbsp;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,&nbsp;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,&nbsp;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,&nbsp;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 =&gt; WhiteIsZero; "GRAY" and /Document/SubimageInterpretation@value =
 737 "TransparencyMask" =&gt; TransparencyMask; "RGB" and /Chroma/Palette present =&gt;
 738 PaletteColor; "GRAY" =&gt; BlackIsZero; "RGB" =&gt; RGB; "YCbCr" =&gt; YCbCr;
 739 "CMYK" =&gt; CMYK; "Lab" =&gt; 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" =&gt; Uncompressed;
 752 "CCITT RLE" =&gt; CCITT 1D; "CCITT T.4" =&gt; Group 3 Fax; "CCITT T.6" =&gt; Group 4
 753 Fax; "LZW" =&gt; LZW; "Old JPEG" =&gt; JPEG; "JPEG" =&gt; New JPEG; "ZLib" =&gt; ZLib;
 754 "PackBits" =&gt; PackBits; "Deflate" =&gt; Deflate.</td>
 755 </tr>
 756 <tr>
 757 <td>PlanarConfiguration</td>
 758 <td>/Data/PlanarConfiguration@value: "PixelInterleaved" =&gt; Chunky;
 759 "PlaneInterleaved" =&gt; Planar.</td>
 760 </tr>
 761 <tr>
 762 <td>SampleFormat</td>
 763 <td>/Data/SampleFormat@value: "SignedIntegral" =&gt; two's complement signed
 764 integer data; "UnsignedIntegral" =&gt; unsigned integer data; "Real" =&gt;
 765 IEEE floating point data; "Index" =&gt; 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 =&gt;
 775 right-to-left; otherwise =&gt; 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" =&gt;
 809 transparency mask; "ReducedResolution" =&gt; reduced-resolution;
 810 "SinglePage" =&gt; 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" =&gt; associated alpha, count 1;
 826 "nonpremultiplied" =&gt; 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,&nbsp;IFD Value,&nbsp;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 &lt; 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 &lt;!DOCTYPE "javax_imageio_tiff_stream_1.0" [
1019 
1020   &lt;!ELEMENT "javax_imageio_tiff_stream_1.0" (ByteOrder)>
1021 
1022     &lt;!ELEMENT "ByteOrder" EMPTY&gt;
1023       &lt;!-- The stream byte order --&gt;
1024       &lt;!ATTLIST "ByteOrder" "value" #CDATA #REQUIRED&gt;
1025         &lt;!-- One of "BIG_ENDIAN" or "LITTLE_ENDIAN" --&gt;
1026         &lt;!-- Data type: String --&gt;
1027 ]&gt;
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 &lt;!DOCTYPE "javax_imageio_tiff_image_1.0" [
1036 
1037   &lt;!ELEMENT "javax_imageio_tiff_image_1.0" (TIFFIFD)*&gt;
1038 
1039     &lt;!ELEMENT "TIFFIFD" (TIFFField | TIFFIFD)*&gt;
1040       &lt;!-- An IFD (directory) containing fields --&gt;
1041       &lt;!ATTLIST "TIFFIFD" "tagSets" #CDATA #REQUIRED&gt;
1042         &lt;!-- Data type: String --&gt;
1043       &lt;!ATTLIST "TIFFIFD" "parentTagNumber" #CDATA #IMPLIED&gt;
1044         &lt;!-- The tag number of the field pointing to this IFD --&gt;
1045         &lt;!-- Data type: Integer --&gt;
1046       &lt;!ATTLIST "TIFFIFD" "parentTagName" #CDATA #IMPLIED&gt;
1047         &lt;!-- A mnemonic name for the field pointing to this IFD, if known
1048              --&gt;
1049         &lt;!-- Data type: String --&gt;
1050 


< prev index next >