TIFF Metadata Format Specification and Usage Notes

Reading Images

• Color Conversion
• Color Spaces
• ICC Profiles
• Metadata Issues
  • Native to Standard Metadata Mapping
• Reading Exif Images
  • Reading Uncompressed Exif Images
  • Reading Compressed Exif Images

Reading Images

Color Conversion

If the source image data have photometric type CIE L*a*b* or YCbCr, and the destination color space type is RGB, then the source image data will be automatically converted to RGB using an internal color converter.

Color Spaces

• A color space created from the ICC Profile metadata field if it is present and compatible with the image data layout.
• sRGB if the image is monochrome/bilevel (a two-level color map is created internally).
• sRGB if the image is palette-color.
• Linear RGB if the image has three samples per pixel, has photometric type CIE L*a*b*, or has photometric type YCbCr and is not JPEG-compressed.
• A default CMYK color space if the image has photometric type CMYK and four samples per pixel.
• Grayscale if the image has one or two samples per pixel and uniformly 1, 2, 4, 8, 16, or 32 bits per sample or is floating point.
• sRGB if the image has three or four samples per pixel and uniformly 1, 2, 4, 8, 16, or 32 bits per sample or is floating point.
• A fabricated, generic color space if the image has more than four samples per pixel and the number of bits per sample for all bands is the same and is a multiple of 8.
• Grayscale if the image has one or two samples per pixel regardless of the number of bits per sample.
• sRGB if the image has three or four samples per pixel regardless of the number of bits per sample.
• A fabricated, generic color space if the image has more than four samples per pixel regardless of the number of bits per sample.

The normalized color coordinate transformations used for the default CMYK color space are defined as follows:

• CMYK to linear RGB

  R = (1 - K)*(1 - C)
  G = (1 - K)*(1 - M)
  B = (1 - K)*(1 - Y)
  

• Linear RGB to CMYK

  K = min{1 - R, 1 - G, 1 - B}
  if(K != 1) {
      C = (1 - R - K)/(1 - K)
      M = (1 - G - K)/(1 - K)
      Y = (1 - B - K)/(1 - K)
  } else {
      C = M = Y = 0
  }
  

The generic color space used when no other color space can be inferred is provided merely to enable the data to be loaded. It is not intended to provide accurate conversions of any kind.

If the data are known to be in a color space not correctly handled by the foregoing, then an ImageTypeSpecifier should be supplied to the reader and should be derived from a color space which is correct for the data in question.

ICC Profiles

If for some reason the embedded ICC profile is not used automatically, then it may be used manually by following this procedure:

1. Obtain the image metadata from ImageReader.getImageMetadata
2. Extract the ICC profile field and its value.
3. Create an ICC_ColorSpace from an ICC_Profile created from the ICC profile field data using ICC_Profile.getInstance(byte[]).
4. Create an ImageTypeSpecifier from the new color space using one of its factory methods which accepts an ICC_ColorSpace.
5. Create a compatible ImageReadParam and set the ImageTypeSpecifier using ImageReadParam.setDestinationType.
6. Pass the parameter object to the appropriate read method.

If the inferred color space not based on the ICC Profile field is compatible with the ICC profile-based color space, then a second ImageTypeSpecifier derived from this inferred color space will be included in the Iterator returned by ImageReader.getImageTypes. If the iterator contains more than one type, the first one will be based on the ICC profile and the second on the inferred color space.

Metadata Issues

Use of a TIFFDirectory object may simplify gaining access to metadata values. An instance of TIFFDirectory may be created from the IIOMetadata object returned by the TIFF reader using the TIFFDirectory.createFromMetadata method.

Mapping of TIFF Native Image Metadata to the Standard Metadata Format

Reading Exif Images

Reading Uncompressed Exif Images

    ImageInputStream input;
    ImageReader tiffReader;
    ImageReadParam tiffReadParam;

    tiffReader.setInput(input);

    // Read primary image and IFD.
    BufferedImage image = tiffReader.read(0, tiffReadParam);
    IIOMetadata primaryIFD = tiffReader.getImageMetadata(0);

    // Read thumbnail if present.
    BufferedImage thumbnail = null;
    if (tiffReader.getNumImages(true) > 1) {
        thumbnail = tiffReader.read(1, tiffReadParam);
    }

Reading Compressed Exif Images

The parameter content of the APP1 marker segment may be obtained from the user object of the associated Node in a javax_imageio_jpeg_image_1.0 native image metadata tree extracted from the image metadata object returned by the JPEG reader. This APP1 Exif node will be a child of the node named "markerSequence" and will have name unknown and an attribute named MarkerTag with integral value 0xE1 (String value "225"). The user object of this node will be a byte array which starts with the six bytes {'E', 'x', 'i', 'f', '0', '0'}. The primary IFD and the thumbnail IFD and image may be read from the user object by the usual ImageReader methods:

    ImageReader jpegReader;
    ImageReader tiffReader;

    // Obtain the APP1 Exif marker data from the JPEG image metadata.
    IIOMetadata jpegImageMetadata = jpegReader.getImageMetadata(0);
    String nativeFormat = jpegImageMetadata.getNativeMetadataFormatName();
    Node jpegImageMetadataTree = jpegImageMetadata.getAsTree(nativeFormat);

    // getExifMarkerData() returns the byte array which is the user object
    // of the APP1 Exif marker node.
    byte[] app1Params = getExifMarkerData(jpegImageMetadataTree);
    if (app1Params == null) {
        throw new IIOException("APP1 Exif marker not found.");
    }

    // Set up input, skipping Exif ID 6-byte sequence.
    MemoryCacheImageInputStream app1ExifInput
        = new MemoryCacheImageInputStream
            (new ByteArrayInputStream(app1Params, 6, app1Params.length - 6));
    tiffReader.setInput(app1ExifInput);

    // Read primary IFD.
    IIOMetadata primaryIFD = tiffReader.getImageMetadata(0);

    // Read thumbnail if present.
    BufferedImage thumbnail = null;
    if (tiffReader.getNumImages(true) > 1) {
        thumbnail = tiffReader.read(1, tiffReadParam);
    }

    // Read the primary image.
    BufferedImage image = jpegReader.read(0);

Writing Images

If tiles are being written, then each of their dimensions will be rounded to the nearest multiple of 16 per the TIFF specification. If JPEG-in-TIFF compression is being used, and tiles are being written each tile dimension will be rounded to the nearest multiple of 8 times the JPEG minimum coded unit (MCU) in that dimension. If JPEG-in-TIFF compression is being used and strips are being written, the number of rows per strip is rounded to a multiple of 8 times the maximum MCU over both dimensions.

Compression

Old-style JPEG compression as described in section 22 of the TIFF 6.0 Specification is not supported.

The CCITT compression types are applicable to bilevel (1-bit) images only. The JPEG compression type is applicable to byte grayscale (1-band) and RGB (3-band) images only.

ZLib and Deflate compression are identical except for the value of the TIFF Compression field: for ZLib the Compression field has value 8 whereas for Deflate it has value 32946 (0x80b2). In both cases each image segment (strip or tile) is written as a single complete zlib data stream.

"Exif JPEG" is a compression type used when writing the contents of an APP1 Exif marker segment for inclusion in a JPEG native image metadata tree. The contents appended to the output when this compression type is used are a function of whether an empty or non-empty image is written. If the image is empty, then a TIFF IFD adhering to the specification of a compressed Exif primary IFD is appended. If the image is non-empty, then a complete IFD and image adhering to the specification of a compressed Exif thumbnail IFD and image are appended. Note that the data of the empty image may not later be appended using the pixel replacement capability of the TIFF writer.

If ZLib/Deflate or JPEG compression is used, the compression quality may be set. For ZLib/Deflate the supplied floating point quality value is rescaled to the range [1, 9] and truncated to an integer to derive the Deflate compression level. For JPEG the floating point quality value is passed directly to the JPEG writer plug-in which interprets it in the usual way.

Color Conversion

If the source image data color space type is RGB, and the destination photometric type is CIE L*a*b* or YCbCr, then the source image data will be automatically converted from RGB using an internal color converter.

ICC Profiles

• one is present in the native image metadata IIOMetadata instance supplied to the writer, or
• the ColorSpace of the destination ImageTypeSpecifier is an instance of ICC_ColorSpace which is not one of the standard color spaces defined by the CS_* constants in the ColorSpace class. The destination type is set via ImageWriteParam.setDestinationType(ImageTypeSpecifier) and defaults to the ImageTypeSpecifier of the image being written.

Metadata Issues

For bilevel images, the FillOrder, and T4Options fields affect the output data. The data will be filled right-to-left if FillOrder is present with a value of 2 (BaselineTIFFTagSet.FILL_ORDER_RIGHT_TO_LEFT) and will be filled left-to-right otherwise. The value of T4Options specifies whether the data should be 1D- or 2D-encoded and whether EOL padding should be used.

For all images the value of the RowsPerStrip field is used to the set the number of rows per strip if the image is not tiled. The default number of rows per strip is either 8 or the number of rows which would fill no more than 8 kilobytes, whichever is larger.

For all images the tile dimensions may be set using the TileWidth and TileLength field values if the tiling mode is ImageWriteParam.MODE_COPY_FROM_METADATA. If this mode is set but the fields are not, their respective default values are the image width and height.

When using JPEG-in-TIFF compression, a JPEGTables field will be written to the IFD and abbreviated JPEG streams to each strip or tile if and only if a JPEGTables field is contained in the metadata object provided to the writer. If the contents of the JPEGTables field is a valid tables-only JPEG stream, then it will be used; otherwise the contents of the field will be replaced with default visually lossless tables. If no such JPEGTables field is present in the metadata, then no JPEGTables field will be written to the output and each strip or tile will be written as a separate, self-contained JPEG stream.

When using Deflate/ZLib or LZW compression, if the image has 8 bits per sample, a horizontal differencing predictor will be used if the Predictor field is present with a value of 2 (BaselineTIFFTagSet.PREDICTOR_HORIZONTAL_DIFFERENCING). If prediction is so requested but the image does not have 8 bits per sample the field will be reset to have the value 1 (BaselineTIFFTagSet.PREDICTOR_NONE).

Some fields may be added or modified:

• PhotometricInterpretation if not present.
• PlanarConfiguration if this field is present with value Planar is is reset to Chunky.
• Compression always.
• BitsPerSample if the image is not bilevel.
• SamplesPerPixel always.
• ExtraSamples if an alpha channel is present.
• SampleFormat if not present and the data are 16- or 32-bit integers or floating point.
• ColorMap if the PhotometricInterpretation is RGBPalette.
• ImageWidth and ImageLength always.
• TileWidth, TileLength, TileOffsets, and TileByteCounts if a tiled image is being written.
• RowsPerStrip, StripOffsets, and StripByteCounts if a tiled image is not being written.
• XResolution, YResolution, and ResolutionUnit if none of these is present.
• YCbCrSubsampling and YCbCrPositioning if the photometric interpretation is YCbCr and the compression type is not JPEG (only [1, 1] subsampling and cosited positioning are supported for non-JPEG YCbCr output).
• YCbCrSubsampling, YCbCrPositioning, and ReferenceBlackWhite: if the compression type is JPEG and the color space is RGB these will be reset to [2, 2] centered subsampling with no headroom/footroom (0:255,128:255,128:255).

Some fields may be removed:

• BitsPerSample if the image is bilevel.
• ExtraSamples if the image does not have an alpha channel.
• ColorMap if the photometric interpretation is not RGBPalette.
• TileWidth, TileLength, TileOffsets, and TileByteCounts if tiling is not being used.
• RowsPerStrip, StripOffsets, and StripByteCounts if tiling is being used.
• YCbCrSubsampling, YCbCrPositioning, and ReferenceBlackWhite if the compression type is JPEG and the color space is grayscale.
• JPEGProc, JPEGInterchangeFormat, JPEGInterchangeFormatLength, JPEGRestartInterval, JPEGLosslessPredictors, JPEGPointTransforms, JPEGQTables, JPEGDCTables, and JPEGACTables if the compression type is JPEG.

Other fields present in the supplied metadata are uninterpreted and will be written as supplied.

If an Exif image is being written, the set of fields present and their values will be modified such that the result is in accord with the Exif 2.2 specification.

Setting up the image metadata to write to a TIFF stream may be simplified by using the TIFFDirectory class which represents a TIFF IFD. A field in a TIFF IFD is represented by an instance of TIFFField. For each field to be written a TIFFField may be added to the TIFFDirectory and the latter converted to an IIOMetadata object by invoking TIFFDirectory.getAsMetadata. The IIOMetadata object so obtained may then be passed to the TIFF writer.

Mapping of the Standard Metadata Format to TIFF Native Image Metadata

Writing Exif Images

Writing Uncompressed Exif Images

1. Image File Header
2. Primary IFD
3. Primary IFD Value
4. Thumbnail IFD
5. Thumbnail IFD Value
6. Thumbnail Image Data
7. Primary Image Data

    ImageWriter tiffWriter;
    ImageWriteParam tiffWriteParam;
    IIOMetadata tiffStreamMetadata;
    IIOMetadata primaryIFD;
    BufferedImage image;
    BufferedImage thumbnail;

    // Specify uncompressed output.
    tiffWriteParam.setCompressionMode(ImageWriteParam.MODE_DISABLED);

    if (thumbnail != null) {
        // Write the TIFF header.
        tiffWriter.prepareWriteSequence(tiffStreamMetadata);

        // Append the primary IFD.
        tiffWriter.prepareInsertEmpty(-1, // append
                new ImageTypeSpecifier(image),
                image.getWidth(),
                image.getHeight(),
                primaryIFD,
                null, // thumbnails
                tiffWriteParam);
        tiffWriter.endInsertEmpty();

        // Append the thumbnail image data.
        tiffWriter.writeToSequence(new IIOImage(thumbnail, null, null),
                tiffWriteParam);

        // Insert the primary image data.
        tiffWriter.prepareReplacePixels(0, new Rectangle(image.getWidth(),
                image.getHeight()));
        tiffWriter.replacePixels(image, tiffWriteParam);
        tiffWriter.endReplacePixels();

        // End writing.
        tiffWriter.endWriteSequence();
    } else {
        // Write only the primary IFD and image data.
        tiffWriter.write(tiffStreamMetadata,
                new IIOImage(image, null, primaryIFD),
                tiffWriteParam);
    }

Writing Compressed Exif Images

    ImageWriter tiffWriter;
    ImageWriteParam tiffWriteParam;
    IIOMetadata tiffStreamMetadata;
    BufferedImage image;
    BufferedImage thumbnail;
    IIOMetadata primaryIFD;
    ImageOutputStream output;

    // Set up an output to contain the APP1 Exif TIFF stream.
    ByteArrayOutputStream baos = new ByteArrayOutputStream();
    MemoryCacheImageOutputStream app1ExifOutput =
        new MemoryCacheImageOutputStream(baos);
    tiffWriter.setOutput(app1ExifOutput);

    // Set compression for the thumbnail.
    tiffWriteParam.setCompressionMode(ImageWriteParam.MODE_EXPLICIT);
    tiffWriteParam.setCompressionType("Exif JPEG");

    // Write the APP1 Exif TIFF stream.
    if (thumbnail != null) {
        // Write the TIFF header.
        tiffWriter.prepareWriteSequence(tiffStreamMetadata);

        // Append the primary IFD.
        tiffWriter.prepareInsertEmpty(-1, // append
                new ImageTypeSpecifier(image),
                image.getWidth(),
                image.getHeight(),
                primaryIFD,
                null, // thumbnails
                tiffWriteParam);
        tiffWriter.endInsertEmpty();

        // Append the thumbnail IFD and image data.
        tiffWriter.writeToSequence(new IIOImage(thumbnail, null,
                null), tiffWriteParam);

        // End writing.
        tiffWriter.endWriteSequence();
    } else {
        // Write only the primary IFD.
        tiffWriter.prepareWriteEmpty(tiffStreamMetadata,
                new ImageTypeSpecifier(image),
                image.getWidth(),
                image.getHeight(),
                primaryIFD,
                null, // thumbnails
                tiffWriteParam);
        tiffWriter.endWriteEmpty();
    }

    // Flush data into byte stream.
    app1ExifOutput.flush();

    // Create APP1 parameter array.
    byte[] app1Parameters = new byte[6 + baos.size()];

    // Add APP1 Exif ID bytes.
    app1Parameters[0] = (byte) 'E';
    app1Parameters[1] = (byte) 'x';
    app1Parameters[2] = (byte) 'i';
    app1Parameters[3] = (byte) 'f';
    app1Parameters[4] = app1Parameters[5] = (byte) 0;

    // Append TIFF stream to APP1 parameters.
    System.arraycopy(baos.toByteArray(), 0, app1Parameters, 6, baos.size());

    // Create the APP1 Exif node to be added to native JPEG image metadata.
    IIOMetadataNode app1Node = new IIOMetadataNode("unknown");
    app1Node.setAttribute("MarkerTag", String.valueOf(0xE1));
    app1Node.setUserObject(app1Parameters);

    // Append the APP1 Exif marker to the "markerSequence" node.
    IIOMetadata jpegImageMetadata =
        jpegWriter.getDefaultImageMetadata(new ImageTypeSpecifier(image),
            jpegWriteParam);
    String nativeFormat = jpegImageMetadata.getNativeMetadataFormatName();
    Node tree = jpegImageMetadata.getAsTree(nativeFormat);
    NodeList children = tree.getChildNodes();
    int numChildren = children.getLength();
    for (int i = 0; i < numChildren; i++) {
        Node child = children.item(i);
        if (child.getNodeName().equals("markerSequence")) {
            child.appendChild(app1Node);
            break;
        }
    }
    jpegImageMetadata.setFromTree(nativeFormat, tree);

    // Write the JPEG image data including the APP1 Exif marker.
    jpegWriter.setOutput(output);
    jpegWriter.write(new IIOImage(image, null, jpegImageMetadata));

Stream Metadata

<!DOCTYPE "javax_imageio_tiff_stream_1.0" [

  <!ELEMENT "javax_imageio_tiff_stream_1.0" (ByteOrder)>

    <!ELEMENT "ByteOrder" EMPTY>
      <!-- The stream byte order --> 
      <!ATTLIST "ByteOrder" "value" #CDATA #REQUIRED>
        <!-- One of "BIG_ENDIAN" or "LITTLE_ENDIAN" --> 
        <!-- Data type: String -->
]>

Image Metadata

<!DOCTYPE "javax_imageio_tiff_image_1.0" [

  <!ELEMENT "javax_imageio_tiff_image_1.0" (TIFFIFD)*>

    <!ELEMENT "TIFFIFD" (TIFFField | TIFFIFD)*>
      <!-- An IFD (directory) containing fields --> 
      <!ATTLIST "TIFFIFD" "tagSets" #CDATA #REQUIRED>
        <!-- Data type: String -->
      <!ATTLIST "TIFFIFD" "parentTagNumber" #CDATA #IMPLIED>
        <!-- The tag number of the field pointing to this IFD --> 
        <!-- Data type: Integer -->
      <!ATTLIST "TIFFIFD" "parentTagName" #CDATA #IMPLIED>
        <!-- A mnemonic name for the field pointing to this IFD, if known 
             --> 
        <!-- Data type: String -->

      <!ELEMENT "TIFFField" (TIFFBytes | TIFFAsciis |
        TIFFShorts | TIFFSShorts | TIFFLongs | TIFFSLongs |
        TIFFRationals | TIFFSRationals |
        TIFFFloats | TIFFDoubles | TIFFUndefined)>
        <!-- A field containing data --> 
        <!ATTLIST "TIFFField" "number" #CDATA #REQUIRED>
          <!-- The tag number asociated with the field --> 
          <!-- Data type: String -->
        <!ATTLIST "TIFFField" "name" #CDATA #IMPLIED>
          <!-- A mnemonic name associated with the field, if known --> 
          <!-- Data type: String -->

        <!ELEMENT "TIFFBytes" (TIFFByte)*>
          <!-- A sequence of TIFFByte nodes --> 

          <!ELEMENT "TIFFByte" EMPTY>
            <!-- An integral value between 0 and 255 --> 
            <!ATTLIST "TIFFByte" "value" #CDATA #IMPLIED>
              <!-- The value --> 
              <!-- Data type: String -->
            <!ATTLIST "TIFFByte" "description" #CDATA #IMPLIED>
              <!-- A description, if available --> 
              <!-- Data type: String -->

        <!ELEMENT "TIFFAsciis" (TIFFAscii)*>
          <!-- A sequence of TIFFAscii nodes --> 

          <!ELEMENT "TIFFAscii" EMPTY>
            <!-- A String value --> 
            <!ATTLIST "TIFFAscii" "value" #CDATA #IMPLIED>
              <!-- The value --> 
              <!-- Data type: String -->

        <!ELEMENT "TIFFShorts" (TIFFShort)*>
          <!-- A sequence of TIFFShort nodes --> 

          <!ELEMENT "TIFFShort" EMPTY>
            <!-- An integral value between 0 and 65535 --> 
            <!ATTLIST "TIFFShort" "value" #CDATA #IMPLIED>
              <!-- The value --> 
              <!-- Data type: String -->
            <!ATTLIST "TIFFShort" "description" #CDATA #IMPLIED>
              <!-- A description, if available --> 
              <!-- Data type: String -->

        <!ELEMENT "TIFFSShorts" (TIFFSShort)*>
          <!-- A sequence of TIFFSShort nodes --> 

          <!ELEMENT "TIFFSShort" EMPTY>
            <!-- An integral value between -32768 and 32767 --> 
            <!ATTLIST "TIFFSShort" "value" #CDATA #IMPLIED>
              <!-- The value --> 
              <!-- Data type: String -->
            <!ATTLIST "TIFFSShort" "description" #CDATA #IMPLIED>
              <!-- A description, if available --> 
              <!-- Data type: String -->

        <!ELEMENT "TIFFLongs" (TIFFLong)*>
          <!-- A sequence of TIFFLong nodes --> 

          <!ELEMENT "TIFFLong" EMPTY>
            <!-- An integral value between 0 and 4294967295 --> 
            <!ATTLIST "TIFFLong" "value" #CDATA #IMPLIED>
              <!-- The value --> 
              <!-- Data type: String -->
            <!ATTLIST "TIFFLong" "description" #CDATA #IMPLIED>
              <!-- A description, if available --> 
              <!-- Data type: String -->

        <!ELEMENT "TIFFSLongs" (TIFFSLong)*>
          <!-- A sequence of TIFFSLong nodes --> 

          <!ELEMENT "TIFFSLong" EMPTY>
            <!-- An integral value between -2147483648 and 2147482647 --> 
            <!ATTLIST "TIFFSLong" "value" #CDATA #IMPLIED>
              <!-- The value --> 
              <!-- Data type: String -->
            <!ATTLIST "TIFFSLong" "description" #CDATA #IMPLIED>
              <!-- A description, if available --> 
              <!-- Data type: String -->

        <!ELEMENT "TIFFRationals" (TIFFRational)*>
          <!-- A sequence of TIFFRational nodes --> 

          <!ELEMENT "TIFFRational" EMPTY>
            <!-- A rational value consisting of an unsigned numerator and 
                 denominator --> 
            <!ATTLIST "TIFFRational" "value" #CDATA #IMPLIED>
              <!-- The numerator and denominator, separated by a slash --> 
              <!-- Data type: String -->

        <!ELEMENT "TIFFSRationals" (TIFFSRational)*>
          <!-- A sequence of TIFFSRational nodes --> 

          <!ELEMENT "TIFFSRational" EMPTY>
            <!-- A rational value consisting of a signed numerator and 
                 denominator --> 
            <!ATTLIST "TIFFSRational" "value" #CDATA #IMPLIED>
              <!-- The numerator and denominator, separated by a slash --> 
              <!-- Data type: String -->

        <!ELEMENT "TIFFFloats" (TIFFFloat)*>
          <!-- A sequence of TIFFFloat nodes --> 

          <!ELEMENT "TIFFFloat" EMPTY>
            <!-- A single-precision floating-point value --> 
            <!ATTLIST "TIFFFloat" "value" #CDATA #IMPLIED>
              <!-- The value --> 
              <!-- Data type: String -->

        <!ELEMENT "TIFFDoubles" (TIFFDouble)*>
          <!-- A sequence of TIFFDouble nodes --> 

          <!ELEMENT "TIFFDouble" EMPTY>
            <!-- A double-precision floating-point value --> 
            <!ATTLIST "TIFFDouble" "value" #CDATA #IMPLIED>
              <!-- The value --> 
              <!-- Data type: String -->

        <!ELEMENT "TIFFUndefined" EMPTY>
          <!-- Uninterpreted byte data --> 
          <!ATTLIST "TIFFUndefined" "value" #CDATA #IMPLIED>
            <!-- A list of comma-separated byte values --> 
            <!-- Data type: String -->
]>