Package com.sun.media.imageio.plugins.tiff

Package containing the public classes used by the Sun TIFF plug-in for the Image I/O Framework.

See:
          Description

Class Summary
BaselineTIFFTagSet A class representing the set of tags found in the baseline TIFF specification as well as some common additional tags.
EXIFParentTIFFTagSet A class containing the TIFF tag used to reference an EXIF IFD.
EXIFTIFFTagSet A class representing the tags found in an EXIF IFD.
FaxTIFFTagSet A class representing the extra tags found in a TIFF-F (RFC 2036) file.
GeoTIFFTagSet A class representing the tags found in a GeoTIFF IFD.
TIFFColorConverter An abstract class that performs simple color conversion on 3-banded source images, for use with the TIFF ImageIO plug-in.
TIFFCompressor An abstract superclass for pluggable TIFF compressors.
TIFFDecompressor A class defining a pluggable TIFF decompressor.
TIFFImageReadParam A subclass of ImageReadParam allowing control over the TIFF reading process.
TIFFImageWriteParam A subclass of ImageWriteParam allowing control over the standard TIFF compression types.
TIFFTag A class defining the notion of a TIFF tag.
TIFFTagSet A class representing a set of TIFF tags.
 

Package com.sun.media.imageio.plugins.tiff Description

Package containing the public classes used by the Sun TIFF plug-in for the Image I/O Framework.

Reading Images

TIFF images are read by an ImageReader which may be controlled by its public interface as well as via a supplied TIFFImageReadParam.

Decompression

A TIFFDecompressor object may be supplied via TIFFImageReadParam.setTIFFDecompressor(TIFFDecompressor). If a TIFFDecompressor is specified in this manner it will be used and will supersede any internal decompressor which might otherwise have been used for a known compression type. This mechanism allows for compression types to be handled by user-defined decompressors whether or not that compression type is known to the plug-in.

Color Conversion

A TIFFColorConverter object may be supplied via TIFFImageReadParam.setColorConverter(TIFFColorConverter). If a TIFFColorConverter is specified in this manner it will be used and will supersede any internal color converter which might otherwise have been used. This color converter will be used to convert the source image data to an RGB color space.

If no user-supplied color converter is available, 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

The raw color space assigned by default, i.e., in the absence of a user-supplied ImageTypeSpecifier, will be the first among the following which applies:

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

R = 1.0 - (C - K)
G = 1.0 - (M - K)
B = 1.0 - (Y - K)

C = 1.0 - R
M = 1.0 - G
Y = 1.0 - B
K = min{C,M,Y}

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 an ICC profile is contained in the image metadata (BaselineTIFFTagSet.TAG_ICC_PROFILE, tag number 34675), it will not automatically be used to create the color space of the loaded image. If it is desired that the embedded ICC profile be used then the following procedure is recommended:
  1. Obtain the image metadata from ImageReader.getImageMetadata(int)
  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(javax.imageio.ImageTypeSpecifier).
  6. Pass the parameter object to the appropriate read method.

Metadata Issues

By default all fields in the TIFF image file directory (IFD) are loaded into the native image metadata object. In cases where the IFD includes fields which contain large amounts of data this could be very inefficient. Which fields are loaded may be controlled by setting which TIFF tags the reader is allowed to recognize and whether it is ignoring metadata. The reader is informed to disregard metadata as usual via the ignoreMetadata parameter of ImageReader.setInput(Object,boolean,boolean). It is informed of which TIFFTags to recognize or not to recognize via TIFFImageReadParam.addAllowedTagSet(TIFFTagSet) and TIFFImageReadParam.removeAllowedTagSet(TIFFTagSet). If ignoreMetadata is true, then the reader will load into the native image metadata object only those fields which have a TIFFTag contained in the one of the allowed TIFFTagSets.
Mapping of TIFF Native Image Metadata to the Standard Metadata Format
The derivation of standard metadata format javax_imageio_1.0 elements from TIFF native image metadata is given in the following table.

Standard Metadata Element Derivation from TIFF Fields
/Chroma/ColorSpaceType@name PhotometricInterpretation: WhiteIsZero, BlackIsZero, TransparencyMask = "GRAY"; RGB, PaletteColor => "RGB"; CMYK => "CMYK"; YCbCr => "YCbCr"; CIELab, ICCLab => "Lab".
/Chroma/NumChannels@value SamplesPerPixel
/Chroma/BlackIsZero@value "TRUE" <=> PhotometricInterpretation => WhiteIsZero
/Chroma/Palette ColorMap
/Compression/CompressionTypeName@value Compression: Uncompressed => "none"; CCITT 1D => "CCITT RLE"; Group 3 Fax => "CCITT T.4"; Group 4 Fax => "CCITT T.6"; LZW => "LZW"; JPEG => "Old JPEG"; New JPEG => "JPEG"; Zlib =>> "ZLib"; PackBits => "PackBits"; Deflate => "Deflate".
/Compression/Lossless@value Compression: JPEG or New JPEG => "FALSE"; otherwise "TRUE".
/Data/PlanarConfiguration@value Chunky => "PixelInterleaved"; Planar => "PlaneInterleaved".
/Data/SampleFormat@value PhotometricInterpretation PaletteColor => "Index"; SampleFormat unsigned integer data => "UnsignedIntegral"; SampleFormat two's complement signed integer data => "SignedIntegral"; SampleFormat IEEE floating point data => "Real"; otherwise element not emitted.
/Data/BitsPerSample@value BitsPerSample as a space-separated list.
/Data/SampleMSB@value FillOrder: left-to-right => space-separated list of BitsPerSample-1; right-to-left => space-separated list of 0s.
/Dimension/PixelAspectRatio@value (1/XResolution)/(1/YResolution)
/Dimension/ImageOrientation@value Orientation
/Dimension/HorizontalPixelSize@value 1/XResolution in millimeters if ResolutionUnit is not None.
/Dimension/VerticalPixelSize@value 1/YResolution in millimeters if ResolutionUnit is not None.
/Dimension/HorizontalPosition@value XPosition in millimeters if ResolutionUnit is not None.
/Dimension/VerticalPosition@value YPosition in millimeters if ResolutionUnit is not None.
/Document/FormatVersion@value 6.0
/Document/SubimageInterpretation@value NewSubFileType: transparency => "TransparencyMask"; reduced-resolution => "ReducedResolution"; single page => "SinglePage".
/Document/ImageCreationTime@value DateTime
/Text/TextEntry DocumentName, ImageDescription, Make, Model, PageName, Software, Artist, HostComputer, InkNames, Copyright: /Text/TextEntry@keyword = field name, /Text/TextEntry@value = field value.
Example: TIFF Software field => /Text/TextEntry@keyword = "Software", /Text/TextEntry@value = Name and version number of the software package(s) used to create the image.
/Transparency/Alpha@value ExtraSamples: associated alpha => "premultiplied"; unassociated alpha => "nonpremultiplied".

Writing Images

TIFF images are written by an ImageWriter which may be controlled by its public interface as well as via a supplied TIFFImageWriteParam.

Compression

A TIFFCompressor object may be supplied via TIFFImageWriteParam.setTIFFCompressor(TIFFCompressor). If a TIFFCompressor is specified in this manner it will be used and will supersede any internal compressor which might otherwise have been used for a known compression type. This mechanism allows for compression types to be handled by user-defined compressors whether or not that compression type is known to the plug-in.

Color Conversion

A TIFFColorConverter object may be supplied via TIFFImageWriteParam.setColorConverter(TIFFColorConverter, int). If a TIFFColorConverter is specified in this manner it will be used and will supersede any internal color converter which might otherwise have been used. This color converter will be used to convert from RGB to the color space of the output image.

If no user-supplied color converter is available, 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.

Metadata Issues

Some behavior of the writer is affected by or may affect the contents of the image metadata which may be supplied by the user.

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:

Some fields may be removed:

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

As for reading, the ICC profile field is not handled automatically. If an ICC profile field is desired in the output metadata then it should be be set in the metadata object supplied to the writer.

Mapping of the Standard Metadata Format to TIFF Native Image Metadata
The derivation of TIFF native image metadata elements from the standard metadata format javax_imageio_1.0 is given in the following table.

TIFF Field Derivation from Standard Metadata Elements
PhotometricInterpretation /Chroma/ColorSpaceType@name: "GRAY" and /Chroma/BlackIsZero@value = "FALSE" => WhiteIsZero; "GRAY" and /Document/SubimageInterpretation@value = "TransparencyMask" => TransparencyMask; "RGB" and /Chroma/Palette present => PaletteColor; "GRAY" => BlackIsZero; "RGB" => RGB; "YCbCr" => YCbCr; "CMYK" => CMYK; "Lab" => CIELab.
SamplesPerPixel /Chroma/NumChannels@value
ColorMap /Chroma/Palette
Compression /Compression/CompressionTypeName@value: "none" => Uncompressed; "CCITT RLE" => CCITT 1D; "CCITT T.4" => Group 3 Fax; "CCITT T.6" => Group 4 Fax; "LZW" => LZW; "Old JPEG" => JPEG; "JPEG" => New JPEG; "ZLib" => ZLib; "PackBits" => PackBits; "Deflate" => Deflate.
PlanarConfiguration /Data/PlanarConfiguration@value: "PixelInterleaved" => Chunky; "PlaneInterleaved" => Planar.
SampleFormat /Data/SampleFormat@value: "SignedIntegral" => two's complement signed integer data; "UnsignedIntegral" => unsigned integer data; "Real" => IEEE floating point data; "Index" => unsigned integer data.
BitsPerSample /Data/BitsPerSample@value: space-separated list parsed to char array.
FillOrder /Data/SampleMSB@value: if all values in space-separated list are 0s => right-to-left; otherwise => left-to-right.
XResolution (10 / /Dimension/HorizontalPixelSize@value) or (10 / (/Dimension/VerticalPixelSize@value * /Dimension/PixelAspectRatio@value))
YResolution (10 / /Dimension/VerticalPixelSize@value) or (10 / (/Dimension/HorizontalPixelSize@value / /Dimension/PixelAspectRatio@value))
ResolutionUnit Centimeter if XResolution or YResolution set; otherwise None.
Orientation /Dimension/ImageOrientation@value
XPosition /Dimension/HorizontalPosition@value / 10
YPosition /Dimension/VerticalPosition@value / 10
NewSubFileType /Document/SubimageInterpretation@value: "TransparencyMask" => transparency mask; "ReducedResolution" => reduced-resolution; "SinglePage" => single page.
DateTime /Document/ImageCreationTime@value
DocumentName, ImageDescription, Make, Model, PageName, Software, Artist, HostComputer, InkNames, Copyright /Text/TextEntry: if /Text/TextEntry@keyword is the name of any of the TIFF Fields, e.g., "Software", then the field is added with content /Text/TextEntry@value and count 1.
ExtraSamples /Transparency/Alpha@value: "premultiplied" => associated alpha, count 1; "nonpremultiplied" => unassociated alpha, count 1.

Stream Metadata

The DTD for the stream metadata format is as follows:
<!DOCTYPE "com_sun_media_imageio_plugins_tiff_stream_1.0" [

  <!ELEMENT "com_sun_media_imageio_plugins_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

The DTD for the native image metadata format is as follows:
<!DOCTYPE "com_sun_media_imageio_plugins_tiff_image_1.0" [

  <!ELEMENT "com_sun_media_imageio_plugins_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 -->
]>

Since:
1.0