Package org.apache.commons.imaging.formats.tiff

## Class TiffDirectory

- java.lang.Object
- - org.apache.commons.imaging.formats.tiff.TiffElement
  - - org.apache.commons.imaging.formats.tiff.TiffDirectory

-     public class TiffDirectory
      extends TiffElement

  Provides methods and elements for accessing an Image File Directory (IFD) from a TIFF file. In the TIFF specification, the IFD is the main container for individual images or sets of metadata. While not all Directories contain images, images are always stored in a Directory.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `TiffDirectory.ImageDataElement` |

    - ### Nested classes/interfaces inherited from class org.apache.commons.imaging.formats.tiff.TiffElement

      `TiffElement.DataElement, TiffElement.Stub`

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `List<TiffField>` | `entries` |
    `long` | `nextDirectoryOffset` |
    `int` | `type` |

    - ### Fields inherited from class org.apache.commons.imaging.formats.tiff.TiffElement

      `COMPARATOR, length, offset`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `TiffDirectory​(int type, List<TiffField> entries, long offset, long nextDirectoryOffset, ByteOrder byteOrder)` |

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `String` | `description()` |
    `static String` | `description​(int type)` |
    `void` | `dump()` |
    `TiffField` | `findField​(TagInfo tag)` |
    `TiffField` | `findField​(TagInfo tag, boolean failIfMissing)` |
    `ByteOrder` | `getByteOrder()` | Gets the byte order used by the source file for storing this directory and its content.
    `List<TiffField>` | `getDirectoryEntries()` |
    `String` | `getElementDescription()` |
    `Object` | `getFieldValue​(TagInfo tag)` |
    `String[]` | `getFieldValue​(TagInfoAscii tag, boolean mustExist)` |
    `byte` | `getFieldValue​(TagInfoByte tag)` |
    `byte[]` | `getFieldValue​(TagInfoBytes tag, boolean mustExist)` |
    `double` | `getFieldValue​(TagInfoDouble tag)` |
    `double[]` | `getFieldValue​(TagInfoDoubles tag, boolean mustExist)` |
    `float` | `getFieldValue​(TagInfoFloat tag)` |
    `float[]` | `getFieldValue​(TagInfoFloats tag, boolean mustExist)` |
    `String` | `getFieldValue​(TagInfoGpsText tag, boolean mustExist)` |
    `int` | `getFieldValue​(TagInfoLong tag)` |
    `int[]` | `getFieldValue​(TagInfoLongs tag, boolean mustExist)` |
    `RationalNumber` | `getFieldValue​(TagInfoRational tag)` |
    `RationalNumber[]` | `getFieldValue​(TagInfoRationals tag, boolean mustExist)` |
    `byte` | `getFieldValue​(TagInfoSByte tag)` |
    `byte[]` | `getFieldValue​(TagInfoSBytes tag, boolean mustExist)` |
    `short` | `getFieldValue​(TagInfoShort tag)` |
    `int[]` | `getFieldValue​(TagInfoShortOrLong tag, boolean mustExist)` |
    `short[]` | `getFieldValue​(TagInfoShorts tag, boolean mustExist)` |
    `int` | `getFieldValue​(TagInfoSLong tag)` |
    `int[]` | `getFieldValue​(TagInfoSLongs tag, boolean mustExist)` |
    `RationalNumber` | `getFieldValue​(TagInfoSRational tag)` |
    `RationalNumber[]` | `getFieldValue​(TagInfoSRationals tag, boolean mustExist)` |
    `short` | `getFieldValue​(TagInfoSShort tag)` |
    `short[]` | `getFieldValue​(TagInfoSShorts tag, boolean mustExist)` |
    `String` | `getFieldValue​(TagInfoXpString tag, boolean mustExist)` |
    `JpegImageData` | `getJpegImageData()` |
    `TiffDirectory.ImageDataElement` | `getJpegRawImageDataElement()` |
    `TiffRasterData` | `getRasterData​(TiffImagingParameters params)` | Reads the numerical data stored in this TIFF directory, if available.
    `String` | `getSingleFieldValue​(TagInfoAscii tag)` |
    `int` | `getSingleFieldValue​(TagInfoShortOrLong tag)` |
    `BufferedImage` | `getTiffImage()` | Gets the image associated with the directory, if any.
    `BufferedImage` | `getTiffImage​(ByteOrder byteOrder)` | Gets the image associated with the directory, if any.
    `BufferedImage` | `getTiffImage​(ByteOrder byteOrder, TiffImagingParameters params)` | Gets the image associated with the directory, if any.
    `BufferedImage` | `getTiffImage​(TiffImagingParameters params)` | Gets the image associated with the directory, if any.
    `TiffImageData` | `getTiffImageData()` |
    `List<TiffDirectory.ImageDataElement>` | `getTiffRawImageDataElements()` |
    `boolean` | `hasJpegImageData()` |
    `boolean` | `hasTiffFloatingPointRasterData()` | Indicates whether the directory definition specifies a float-point data format.
    `boolean` | `hasTiffImageData()` |
    `boolean` | `hasTiffRasterData()` | Indicates whether the content associated with the directory is given in a supported numerical-data format.
    `boolean` | `imageDataInStrips()` |
    `void` | `setJpegImageData​(JpegImageData value)` |
    `void` | `setTiffImageData​(TiffImageData rawImageData)` |

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### type

          public final int type

    - #### entries

          public final List<TiffField> entries

    - #### nextDirectoryOffset

          public final long nextDirectoryOffset

  - ### Constructor Detail

    - #### TiffDirectory

          public TiffDirectory​(int type,
                               List<TiffField> entries,
                               long offset,
                               long nextDirectoryOffset,
                               ByteOrder byteOrder)

  - ### Method Detail

    - #### getByteOrder

          public ByteOrder getByteOrder()

      Gets the byte order used by the source file for storing this directory and its content.
      Returns:
        A valid byte order instance.

    - #### description

          public String description()

    - #### getElementDescription

          public String getElementDescription()

      Specified by:
        `getElementDescription` in class `TiffElement`

    - #### description

          public static String description​(int type)

    - #### getDirectoryEntries

          public List<TiffField> getDirectoryEntries()

    - #### dump

          public void dump()

    - #### hasJpegImageData

          public boolean hasJpegImageData()
                                   throws ImageReadException

      Throws:
        `ImageReadException`

    - #### hasTiffImageData

          public boolean hasTiffImageData()
                                   throws ImageReadException

      Throws:
        `ImageReadException`

    - #### getTiffImage

          public BufferedImage getTiffImage()
                                     throws ImageReadException,
                                            IOException

      Gets the image associated with the directory, if any. Note that not all directories contain images.
      Returns:
        if successful, a valid BufferedImage instance.
      Throws:
        `ImageReadException` - in the event of an invalid or incompatible data format.
        `IOException` - in the event of an I/O error.

    - #### getTiffImage

          public BufferedImage getTiffImage​(TiffImagingParameters params)
                                     throws ImageReadException,
                                            IOException

      Gets the image associated with the directory, if any. Note that not all directories contain images.

      The optional parameters object can be used to specify image access or rendering options such as reading only a part of the overall image (i.e. reading a sub-image) or applying a custom photometric interpreter.

      Parameters:
        `params` - an object containing optional parameters to be applied to the read operation.
      Returns:
        if successful, a valid BufferedImage instance.
      Throws:
        `ImageReadException` - in the event of an invalid or incompatible data format.
        `IOException` - in the event of an I/O error.

    - #### getTiffImage

          public BufferedImage getTiffImage​(ByteOrder byteOrder)
                                     throws ImageReadException,
                                            IOException

      Gets the image associated with the directory, if any. Note that not all directories contain images.

      This method comes from an older version of this class in which byte order was required from an external source. Developers are encouraged to use the simpler version of getTiffImage that does not require the byte-order argument.

      Parameters:
        `byteOrder` - byte-order obtained from the containing TIFF file
      Returns:
        if successful, a valid BufferedImage instance.
      Throws:
        `ImageReadException` - in the event of an invalid or incompatible data format.
        `IOException` - in the event of an I/O error.

    - #### getTiffImage

          public BufferedImage getTiffImage​(ByteOrder byteOrder,
                                            TiffImagingParameters params)
                                     throws ImageReadException,
                                            IOException

      Gets the image associated with the directory, if any. Note that not all directories contain images.

      This method comes from an older version of this class in which byte order was required from an external source. Developers are encouraged to use the simpler version of getTiffImage that does not require the byte-order argument.

      Parameters:
        `byteOrder` - byte-order obtained from the containing TIFF file
        `params` - an object containing optional parameters to be applied to the read operation.
      Returns:
        if successful, a valid BufferedImage instance.
      Throws:
        `ImageReadException` - in the event of an invalid or incompatible data format.
        `IOException` - in the event of an I/O error.

    - #### findField

          public TiffField findField​(TagInfo tag)
                              throws ImageReadException

      Throws:
        `ImageReadException`

    - #### findField

          public TiffField findField​(TagInfo tag,
                                     boolean failIfMissing)
                              throws ImageReadException

      Throws:
        `ImageReadException`

    - #### getFieldValue

          public Object getFieldValue​(TagInfo tag)
                               throws ImageReadException

      Throws:
        `ImageReadException`

    - #### getSingleFieldValue

          public String getSingleFieldValue​(TagInfoAscii tag)
                                     throws ImageReadException

      Throws:
        `ImageReadException`

    - #### getSingleFieldValue

          public int getSingleFieldValue​(TagInfoShortOrLong tag)
                                  throws ImageReadException

      Throws:
        `ImageReadException`

    - #### getFieldValue

          public byte getFieldValue​(TagInfoByte tag)
                             throws ImageReadException

      Throws:
        `ImageReadException`

    - #### getFieldValue

          public byte[] getFieldValue​(TagInfoBytes tag,
                                      boolean mustExist)
                               throws ImageReadException

      Throws:
        `ImageReadException`

    - #### getFieldValue

          public String[] getFieldValue​(TagInfoAscii tag,
                                        boolean mustExist)
                                 throws ImageReadException

      Throws:
        `ImageReadException`

    - #### getFieldValue

          public short getFieldValue​(TagInfoShort tag)
                              throws ImageReadException

      Throws:
        `ImageReadException`

    - #### getFieldValue

          public short[] getFieldValue​(TagInfoShorts tag,
                                       boolean mustExist)
                                throws ImageReadException

      Throws:
        `ImageReadException`

    - #### getFieldValue

          public int getFieldValue​(TagInfoLong tag)
                            throws ImageReadException

      Throws:
        `ImageReadException`

    - #### getFieldValue

          public int[] getFieldValue​(TagInfoLongs tag,
                                     boolean mustExist)
                              throws ImageReadException

      Throws:
        `ImageReadException`

    - #### getFieldValue

          public int[] getFieldValue​(TagInfoShortOrLong tag,
                                     boolean mustExist)
                              throws ImageReadException

      Throws:
        `ImageReadException`

    - #### getFieldValue

          public RationalNumber getFieldValue​(TagInfoRational tag)
                                       throws ImageReadException

      Throws:
        `ImageReadException`

    - #### getFieldValue

          public RationalNumber[] getFieldValue​(TagInfoRationals tag,
                                                boolean mustExist)
                                         throws ImageReadException

      Throws:
        `ImageReadException`

    - #### getFieldValue

          public byte getFieldValue​(TagInfoSByte tag)
                             throws ImageReadException

      Throws:
        `ImageReadException`

    - #### getFieldValue

          public byte[] getFieldValue​(TagInfoSBytes tag,
                                      boolean mustExist)
                               throws ImageReadException

      Throws:
        `ImageReadException`

    - #### getFieldValue

          public short getFieldValue​(TagInfoSShort tag)
                              throws ImageReadException

      Throws:
        `ImageReadException`

    - #### getFieldValue

          public short[] getFieldValue​(TagInfoSShorts tag,
                                       boolean mustExist)
                                throws ImageReadException

      Throws:
        `ImageReadException`

    - #### getFieldValue

          public int getFieldValue​(TagInfoSLong tag)
                            throws ImageReadException

      Throws:
        `ImageReadException`

    - #### getFieldValue

          public int[] getFieldValue​(TagInfoSLongs tag,
                                     boolean mustExist)
                              throws ImageReadException

      Throws:
        `ImageReadException`

    - #### getFieldValue

          public RationalNumber getFieldValue​(TagInfoSRational tag)
                                       throws ImageReadException

      Throws:
        `ImageReadException`

    - #### getFieldValue

          public RationalNumber[] getFieldValue​(TagInfoSRationals tag,
                                                boolean mustExist)
                                         throws ImageReadException

      Throws:
        `ImageReadException`

    - #### getFieldValue

          public float getFieldValue​(TagInfoFloat tag)
                              throws ImageReadException

      Throws:
        `ImageReadException`

    - #### getFieldValue

          public float[] getFieldValue​(TagInfoFloats tag,
                                       boolean mustExist)
                                throws ImageReadException

      Throws:
        `ImageReadException`

    - #### getFieldValue

          public double getFieldValue​(TagInfoDouble tag)
                               throws ImageReadException

      Throws:
        `ImageReadException`

    - #### getFieldValue

          public double[] getFieldValue​(TagInfoDoubles tag,
                                        boolean mustExist)
                                 throws ImageReadException

      Throws:
        `ImageReadException`

    - #### getFieldValue

          public String getFieldValue​(TagInfoGpsText tag,
                                      boolean mustExist)
                               throws ImageReadException

      Throws:
        `ImageReadException`

    - #### getFieldValue

          public String getFieldValue​(TagInfoXpString tag,
                                      boolean mustExist)
                               throws ImageReadException

      Throws:
        `ImageReadException`

    - #### getTiffRawImageDataElements

          public List<TiffDirectory.ImageDataElement> getTiffRawImageDataElements()
                                                                           throws ImageReadException

      Throws:
        `ImageReadException`

    - #### imageDataInStrips

          public boolean imageDataInStrips()
                                    throws ImageReadException

      Throws:
        `ImageReadException`

    - #### getJpegRawImageDataElement

          public TiffDirectory.ImageDataElement getJpegRawImageDataElement()
                                                                    throws ImageReadException

      Throws:
        `ImageReadException`

    - #### setTiffImageData

          public void setTiffImageData​(TiffImageData rawImageData)

    - #### getTiffImageData

          public TiffImageData getTiffImageData()

    - #### setJpegImageData

          public void setJpegImageData​(JpegImageData value)

    - #### getJpegImageData

          public JpegImageData getJpegImageData()

    - #### getRasterData

          public TiffRasterData getRasterData​(TiffImagingParameters params)
                                       throws ImageReadException,
                                              IOException

      Reads the numerical data stored in this TIFF directory, if available. Note that this method is defined only for TIFF directories that contain floating-point data or two-byte signed integer data.

      TIFF directories that provide numerical data do not directly specify images, though it is possible to interpret the data as an image using this library. TIFF files may contain multiple directories which are allowed to have different formats. Thus it is possible for a TIFF file to contain a mix of image and floating-point raster data.

      If desired, sub-image data can be read from the file by using a Java Map instance to specify the subsection of the image that is required. The following code illustrates the approach:

             int x; // coordinate (column) of corner of sub-image
             int y; // coordinate (row) of corner of sub-image
             int width; // width of sub-image
             int height; // height of sub-image

             Map<String, Object>params = new HashMap<>();
             params.put(TiffConstants.PARAM_KEY_SUBIMAGE_X, x);
             params.put(TiffConstants.PARAM_KEY_SUBIMAGE_Y, y);
             params.put(TiffConstants.PARAM_KEY_SUBIMAGE_WIDTH, width);
             params.put(TiffConstants.PARAM_KEY_SUBIMAGE_HEIGHT, height);
             TiffRasterData raster =
                  directory.readFloatingPointRasterData(params);

      Parameters:
        `params` - an optional parameter map instance
      Returns:
        a valid instance
      Throws:
        `ImageReadException` - in the event of incompatible or malformed data
        `IOException` - in the event of an I/O error

    - #### hasTiffFloatingPointRasterData

          public boolean hasTiffFloatingPointRasterData()
                                                 throws ImageReadException

      Indicates whether the directory definition specifies a float-point data format.
      Returns:
        `true` if the directory contains floating point data; otherwise, `false`
      Throws:
        `ImageReadException` - in the event of an invalid or malformed specification.

    - #### hasTiffRasterData

          public boolean hasTiffRasterData()
                                    throws ImageReadException

      Indicates whether the content associated with the directory is given in a supported numerical-data format. If this method returns `true`, the Imaging API will be able to extract a TiffRasterData instance from the associated TIFF file using this directory.
      Returns:
        `true` if the directory contains a supported raster data format; otherwise, `false`.
      Throws:
        `ImageReadException` - in the event of an invalid or malformed specification.