Module java.desktop
Package javax.imageio

Class ImageReader

java.lang.Object
javax.imageio.ImageReader
public abstract class ImageReader extends Object
An abstract superclass for parsing and decoding of images. This class must be subclassed by classes that read in images in the context of the Java Image I/O framework.

ImageReader objects are normally instantiated by the service provider interface (SPI) class for the specific format. Service provider classes (e.g., instances of ImageReaderSpi) are registered with the IIORegistry, which uses them for format recognition and presentation of available format readers and writers.

When an input source is set (using the setInput method), it may be marked as "seek forward only". This setting means that images contained within the input source will only be read in order, possibly allowing the reader to avoid caching portions of the input containing data associated with images that have been read previously.

See Also:
ImageWriter, IIORegistry, ImageReaderSpi

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected Locale[]
    availableLocales
    An array of Locales which may be used to localize warning messages, or null if localization is not supported.
    protected boolean
    ignoreMetadata
    true if the current input source has been marked as allowing metadata to be ignored by setInput.
    protected Object
    input
    The ImageInputStream or other Object by setInput and retrieved by getInput.
    protected Locale
    locale
    The current Locale to be used for localization, or null if none has been set.
    protected int
    minIndex
    The smallest valid index for reading, initially 0.
    protected ImageReaderSpi
    originatingProvider
    The ImageReaderSpi that instantiated this object, or null if its identity is not known or none exists.
    protected List<IIOReadProgressListener>
    progressListeners
    A List of currently registered IIOReadProgressListeners, initialized by default to null, which is synonymous with an empty List.
    protected boolean
    seekForwardOnly
    true if the current input source has been marked as allowing only forward seeking by setInput.
    protected List<IIOReadUpdateListener>
    updateListeners
    A List of currently registered IIOReadUpdateListeners, initialized by default to null, which is synonymous with an empty List.
    protected List<IIOReadWarningListener>
    warningListeners
    A List of currently registered IIOReadWarningListeners, initialized by default to null, which is synonymous with an empty List.
    protected List<Locale>
    warningLocales
    A List of the Locales associated with each currently registered IIOReadWarningListener, initialized by default to null, which is synonymous with an empty List.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    ImageReader​(ImageReaderSpi originatingProvider)
    Constructs an ImageReader and sets its originatingProvider field to the supplied value.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    abort()
    Requests that any current read operation be aborted.
    protected boolean
    abortRequested()
    Returns true if a request to abort the current read operation has been made since the reader was instantiated or clearAbortRequest was called.
    void
    addIIOReadProgressListener​(IIOReadProgressListener listener)
    Adds an IIOReadProgressListener to the list of registered progress listeners.
    void
    addIIOReadUpdateListener​(IIOReadUpdateListener listener)
    Adds an IIOReadUpdateListener to the list of registered update listeners.
    void
    addIIOReadWarningListener​(IIOReadWarningListener listener)
    Adds an IIOReadWarningListener to the list of registered warning listeners.
    boolean
    canReadRaster()
    Returns true if this plug-in supports reading just a Raster of pixel data.
    protected static void
    checkReadParamBandSettings​(ImageReadParam param, int numSrcBands, int numDstBands)
    A utility method that may be used by readers to test the validity of the source and destination band settings of an ImageReadParam.
    protected void
    clearAbortRequest()
    Clears any previous abort request.
    protected static void
    computeRegions​(ImageReadParam param, int srcWidth, int srcHeight, BufferedImage image, Rectangle srcRegion, Rectangle destRegion)
    Computes the source region of interest and the destination region of interest, taking the width and height of the source image, an optional destination image, and an optional ImageReadParam into account.
    void
    dispose()
    Allows any resources held by this object to be released.
    float
    getAspectRatio​(int imageIndex)
    Returns the aspect ratio of the given image (that is, its width divided by its height) as a float.
    Locale[]
    getAvailableLocales()
    Returns an array of Locales that may be used to localize warning listeners and compression settings.
    ImageReadParam
    getDefaultReadParam()
    Returns a default ImageReadParam object appropriate for this format.
    protected static BufferedImage
    getDestination​(ImageReadParam param, Iterator<ImageTypeSpecifier> imageTypes, int width, int height)
    Returns the BufferedImage to which decoded pixel data should be written.
    String
    getFormatName()
    Returns a String identifying the format of the input source.
    abstract int
    getHeight​(int imageIndex)
    Returns the height in pixels of the given image within the input source.
    abstract IIOMetadata
    getImageMetadata​(int imageIndex)
    Returns an IIOMetadata object containing metadata associated with the given image, or null if the reader does not support reading metadata, is set to ignore metadata, or if no metadata is available.
    IIOMetadata
    getImageMetadata​(int imageIndex, String formatName, Set<String> nodeNames)
    Returns an IIOMetadata object representing the metadata associated with the given image, or null if the reader does not support reading metadata or none is available.
    abstract Iterator<ImageTypeSpecifier>
    getImageTypes​(int imageIndex)
    Returns an Iterator containing possible image types to which the given image may be decoded, in the form of ImageTypeSpecifierss.
    Object
    getInput()
    Returns the ImageInputStream or other Object previously set as the input source.
    Locale
    getLocale()
    Returns the currently set Locale, or null if none has been set.
    int
    getMinIndex()
    Returns the lowest valid index for reading an image, thumbnail, or image metadata.
    abstract int
    getNumImages​(boolean allowSearch)
    Returns the number of images, not including thumbnails, available from the current input source.
    int
    getNumThumbnails​(int imageIndex)
    Returns the number of thumbnail preview images associated with the given image.
    ImageReaderSpi
    getOriginatingProvider()
    Returns the ImageReaderSpi that was passed in on the constructor.
    ImageTypeSpecifier
    getRawImageType​(int imageIndex)
    Returns an ImageTypeSpecifier indicating the SampleModel and ColorModel which most closely represents the "raw" internal format of the image.
    protected static Rectangle
    getSourceRegion​(ImageReadParam param, int srcWidth, int srcHeight)
    A utility method that may be used by readers to compute the region of the source image that should be read, taking into account any source region and subsampling offset settings in the supplied ImageReadParam.
    abstract IIOMetadata
    getStreamMetadata()
    Returns an IIOMetadata object representing the metadata associated with the input source as a whole (i.e., not associated with any particular image), or null if the reader does not support reading metadata, is set to ignore metadata, or if no metadata is available.
    IIOMetadata
    getStreamMetadata​(String formatName, Set<String> nodeNames)
    Returns an IIOMetadata object representing the metadata associated with the input source as a whole (i.e., not associated with any particular image).
    int
    getThumbnailHeight​(int imageIndex, int thumbnailIndex)
    Returns the height of the thumbnail preview image indexed by thumbnailIndex, associated with the image indexed by ImageIndex.
    int
    getThumbnailWidth​(int imageIndex, int thumbnailIndex)
    Returns the width of the thumbnail preview image indexed by thumbnailIndex, associated with the image indexed by ImageIndex.
    int
    getTileGridXOffset​(int imageIndex)
    Returns the X coordinate of the upper-left corner of tile (0, 0) in the given image.
    int
    getTileGridYOffset​(int imageIndex)
    Returns the Y coordinate of the upper-left corner of tile (0, 0) in the given image.
    int
    getTileHeight​(int imageIndex)
    Returns the height of a tile in the given image.
    int
    getTileWidth​(int imageIndex)
    Returns the width of a tile in the given image.
    abstract int
    getWidth​(int imageIndex)
    Returns the width in pixels of the given image within the input source.
    boolean
    hasThumbnails​(int imageIndex)
    Returns true if the given image has thumbnail preview images associated with it.
    boolean
    isIgnoringMetadata()
    Returns true if the current input source has been marked as allowing metadata to be ignored by passing true as the ignoreMetadata argument to the setInput method.
    boolean
    isImageTiled​(int imageIndex)
    Returns true if the image is organized into tiles, that is, equal-sized non-overlapping rectangles.
    boolean
    isRandomAccessEasy​(int imageIndex)
    Returns true if the storage format of the given image places no inherent impediment on random access to pixels.
    boolean
    isSeekForwardOnly()
    Returns true if the current input source has been marked as seek forward only by passing true as the seekForwardOnly argument to the setInput method.
    protected void
    processImageComplete()
    Broadcasts the completion of an image read to all registered IIOReadProgressListeners by calling their imageComplete method.
    protected void
    processImageProgress​(float percentageDone)
    Broadcasts the current percentage of image completion to all registered IIOReadProgressListeners by calling their imageProgress method.
    protected void
    processImageStarted​(int imageIndex)
    Broadcasts the start of an image read to all registered IIOReadProgressListeners by calling their imageStarted method.
    protected void
    processImageUpdate​(BufferedImage theImage, int minX, int minY, int width, int height, int periodX, int periodY, int[] bands)
    Broadcasts the update of a set of samples to all registered IIOReadUpdateListeners by calling their imageUpdate method.
    protected void
    processPassComplete​(BufferedImage theImage)
    Broadcasts the end of a progressive pass to all registered IIOReadUpdateListeners by calling their passComplete method.
    protected void
    processPassStarted​(BufferedImage theImage, int pass, int minPass, int maxPass, int minX, int minY, int periodX, int periodY, int[] bands)
    Broadcasts the beginning of a progressive pass to all registered IIOReadUpdateListeners by calling their passStarted method.
    protected void
    processReadAborted()
    Broadcasts that the read has been aborted to all registered IIOReadProgressListeners by calling their readAborted method.
    protected void
    processSequenceComplete()
    Broadcasts the completion of an sequence of image reads to all registered IIOReadProgressListeners by calling their sequenceComplete method.
    protected void
    processSequenceStarted​(int minIndex)
    Broadcasts the start of an sequence of image reads to all registered IIOReadProgressListeners by calling their sequenceStarted method.
    protected void
    processThumbnailComplete()
    Broadcasts the completion of a thumbnail read to all registered IIOReadProgressListeners by calling their thumbnailComplete method.
    protected void
    processThumbnailPassComplete​(BufferedImage theThumbnail)
    Broadcasts the end of a thumbnail progressive pass to all registered IIOReadUpdateListeners by calling their thumbnailPassComplete method.
    protected void
    processThumbnailPassStarted​(BufferedImage theThumbnail, int pass, int minPass, int maxPass, int minX, int minY, int periodX, int periodY, int[] bands)
    Broadcasts the beginning of a thumbnail progressive pass to all registered IIOReadUpdateListeners by calling their thumbnailPassStarted method.
    protected void
    processThumbnailProgress​(float percentageDone)
    Broadcasts the current percentage of thumbnail completion to all registered IIOReadProgressListeners by calling their thumbnailProgress method.
    protected void
    processThumbnailStarted​(int imageIndex, int thumbnailIndex)
    Broadcasts the start of a thumbnail read to all registered IIOReadProgressListeners by calling their thumbnailStarted method.
    protected void
    processThumbnailUpdate​(BufferedImage theThumbnail, int minX, int minY, int width, int height, int periodX, int periodY, int[] bands)
    Broadcasts the update of a set of samples in a thumbnail image to all registered IIOReadUpdateListeners by calling their thumbnailUpdate method.
    protected void
    processWarningOccurred​(String warning)
    Broadcasts a warning message to all registered IIOReadWarningListeners by calling their warningOccurred method.
    protected void
    processWarningOccurred​(String baseName, String keyword)
    Broadcasts a localized warning message to all registered IIOReadWarningListeners by calling their warningOccurred method with a string taken from a ResourceBundle.
    BufferedImage
    read​(int imageIndex)
    Reads the image indexed by imageIndex and returns it as a complete BufferedImage, using a default ImageReadParam.
    abstract BufferedImage
    read​(int imageIndex, ImageReadParam param)
    Reads the image indexed by imageIndex and returns it as a complete BufferedImage, using a supplied ImageReadParam.
    IIOImage
    readAll​(int imageIndex, ImageReadParam param)
    Reads the image indexed by imageIndex and returns an IIOImage containing the image, thumbnails, and associated image metadata, using a supplied ImageReadParam.
    Iterator<IIOImage>
    readAll​(Iterator<? extends ImageReadParam> params)
    Returns an Iterator containing all the images, thumbnails, and metadata, starting at the index given by getMinIndex, from the input source in the form of IIOImage objects.
    RenderedImage
    readAsRenderedImage​(int imageIndex, ImageReadParam param)
    Returns a RenderedImage object that contains the contents of the image indexed by imageIndex.
    boolean
    readerSupportsThumbnails()
    Returns true if the image format understood by this reader supports thumbnail preview images associated with it.
    Raster
    readRaster​(int imageIndex, ImageReadParam param)
    Returns a new Raster object containing the raw pixel data from the image stream, without any color conversion applied.
    BufferedImage
    readThumbnail​(int imageIndex, int thumbnailIndex)
    Returns the thumbnail preview image indexed by thumbnailIndex, associated with the image indexed by ImageIndex as a BufferedImage.
    BufferedImage
    readTile​(int imageIndex, int tileX, int tileY)
    Reads the tile indicated by the tileX and tileY arguments, returning it as a BufferedImage.
    Raster
    readTileRaster​(int imageIndex, int tileX, int tileY)
    Returns a new Raster object containing the raw pixel data from the tile, without any color conversion applied.
    void
    removeAllIIOReadProgressListeners()
    Removes all currently registered IIOReadProgressListener objects.
    void
    removeAllIIOReadUpdateListeners()
    Removes all currently registered IIOReadUpdateListener objects.
    void
    removeAllIIOReadWarningListeners()
    Removes all currently registered IIOReadWarningListener objects.
    void
    removeIIOReadProgressListener​(IIOReadProgressListener listener)
    Removes an IIOReadProgressListener from the list of registered progress listeners.
    void
    removeIIOReadUpdateListener​(IIOReadUpdateListener listener)
    Removes an IIOReadUpdateListener from the list of registered update listeners.
    void
    removeIIOReadWarningListener​(IIOReadWarningListener listener)
    Removes an IIOReadWarningListener from the list of registered error listeners.
    void
    reset()
    Restores the ImageReader to its initial state.
    void
    setInput​(Object input)
    Sets the input source to use to the given ImageInputStream or other Object.
    void
    setInput​(Object input, boolean seekForwardOnly)
    Sets the input source to use to the given ImageInputStream or other Object.
    void
    setInput​(Object input, boolean seekForwardOnly, boolean ignoreMetadata)
    Sets the input source to use to the given ImageInputStream or other Object.
    void
    setLocale​(Locale locale)
    Sets the current Locale of this ImageReader to the given value.

    Methods declared in class java.lang.Object

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

  • Field Details

    • originatingProvider

      protected ImageReaderSpi originatingProvider
      The ImageReaderSpi that instantiated this object, or null if its identity is not known or none exists. By default it is initialized to null.

    • input

      protected Object input
      The ImageInputStream or other Object by setInput and retrieved by getInput. By default it is initialized to null.

    • seekForwardOnly

      protected boolean seekForwardOnly
      true if the current input source has been marked as allowing only forward seeking by setInput. By default, the value is false.
      See Also:
      minIndex, setInput(java.lang.Object, boolean, boolean)

    • ignoreMetadata

      protected boolean ignoreMetadata
      true if the current input source has been marked as allowing metadata to be ignored by setInput. By default, the value is false.
      See Also:
      setInput(java.lang.Object, boolean, boolean)

    • minIndex

      protected int minIndex
      The smallest valid index for reading, initially 0. When seekForwardOnly is true, various methods may throw an IndexOutOfBoundsException on an attempt to access data associate with an image having a lower index.
      See Also:
      seekForwardOnly, setInput(java.lang.Object, boolean, boolean)

    • availableLocales

      protected Locale[] availableLocales
      An array of Locales which may be used to localize warning messages, or null if localization is not supported.

    • locale

      protected Locale locale
      The current Locale to be used for localization, or null if none has been set.

    • warningListeners

      protected List<IIOReadWarningListener> warningListeners
      A List of currently registered IIOReadWarningListeners, initialized by default to null, which is synonymous with an empty List.

    • warningLocales

      protected List<Locale> warningLocales
      A List of the Locales associated with each currently registered IIOReadWarningListener, initialized by default to null, which is synonymous with an empty List.

    • progressListeners

      protected List<IIOReadProgressListener> progressListeners
      A List of currently registered IIOReadProgressListeners, initialized by default to null, which is synonymous with an empty List.

    • updateListeners

      protected List<IIOReadUpdateListener> updateListeners
      A List of currently registered IIOReadUpdateListeners, initialized by default to null, which is synonymous with an empty List.

  • Constructor Details

    • ImageReader

      protected ImageReader​(ImageReaderSpi originatingProvider)
      Constructs an ImageReader and sets its originatingProvider field to the supplied value.

      Subclasses that make use of extensions should provide a constructor with signature (ImageReaderSpi,Object) in order to retrieve the extension object. If the extension object is unsuitable, an IllegalArgumentException should be thrown.

      Parameters:
      originatingProvider - the ImageReaderSpi that is invoking this constructor, or null.

  • Method Details

    • getFormatName

      public String getFormatName() throws IOException
      Returns a String identifying the format of the input source.

      The default implementation returns originatingProvider.getFormatNames()[0]. Implementations that may not have an originating service provider, or which desire a different naming policy should override this method.

      Returns:
      the format name, as a String.
      Throws:
      IOException - if an error occurs reading the information from the input source.

    • getOriginatingProvider

      public ImageReaderSpi getOriginatingProvider()
      Returns the ImageReaderSpi that was passed in on the constructor. Note that this value may be null.
      Returns:
      an ImageReaderSpi, or null.
      See Also:
      ImageReaderSpi

    • setInput

      public void setInput​(Object input, boolean seekForwardOnly, boolean ignoreMetadata)
      Sets the input source to use to the given ImageInputStream or other Object. The input source must be set before any of the query or read methods are used. If input is null, any currently set input source will be removed. In any case, the value of minIndex will be initialized to 0.

      The seekForwardOnly parameter controls whether the value returned by getMinIndex will be increased as each image (or thumbnail, or image metadata) is read. If seekForwardOnly is true, then a call to read(index) will throw an IndexOutOfBoundsException if index < this.minIndex; otherwise, the value of minIndex will be set to index. If seekForwardOnly is false, the value of minIndex will remain 0 regardless of any read operations.

      The ignoreMetadata parameter, if set to true, allows the reader to disregard any metadata encountered during the read. Subsequent calls to the getStreamMetadata and getImageMetadata methods may return null, and an IIOImage returned from readAll may return null from their getMetadata method. Setting this parameter may allow the reader to work more efficiently. The reader may choose to disregard this setting and return metadata normally.

      Subclasses should take care to remove any cached information based on the previous stream, such as header information or partially decoded image data.

      Use of a general Object other than an ImageInputStream is intended for readers that interact directly with a capture device or imaging protocol. The set of legal classes is advertised by the reader's service provider's getInputTypes method; most readers will return a single-element array containing only ImageInputStream.class to indicate that they accept only an ImageInputStream.

      The default implementation checks the input argument against the list returned by originatingProvider.getInputTypes() and fails if the argument is not an instance of one of the classes in the list. If the originating provider is set to null, the input is accepted only if it is an ImageInputStream.

      Parameters:
      input - the ImageInputStream or other Object to use for future decoding.
      seekForwardOnly - if true, images and metadata may only be read in ascending order from this input source.
      ignoreMetadata - if true, metadata may be ignored during reads.
      Throws:
      IllegalArgumentException - if input is not an instance of one of the classes returned by the originating service provider's getInputTypes method, or is not an ImageInputStream.
      See Also:
      ImageInputStream, getInput(), ImageReaderSpi.getInputTypes()

    • setInput

      public void setInput​(Object input, boolean seekForwardOnly)
      Sets the input source to use to the given ImageInputStream or other Object. The input source must be set before any of the query or read methods are used. If input is null, any currently set input source will be removed. In any case, the value of minIndex will be initialized to 0.

      The seekForwardOnly parameter controls whether the value returned by getMinIndex will be increased as each image (or thumbnail, or image metadata) is read. If seekForwardOnly is true, then a call to read(index) will throw an IndexOutOfBoundsException if index < this.minIndex; otherwise, the value of minIndex will be set to index. If seekForwardOnly is false, the value of minIndex will remain 0 regardless of any read operations.

      This method is equivalent to setInput(input, seekForwardOnly, false).

      Parameters:
      input - the ImageInputStream or other Object to use for future decoding.
      seekForwardOnly - if true, images and metadata may only be read in ascending order from this input source.
      Throws:
      IllegalArgumentException - if input is not an instance of one of the classes returned by the originating service provider's getInputTypes method, or is not an ImageInputStream.
      See Also:
      getInput()

    • setInput

      public void setInput​(Object input)
      Sets the input source to use to the given ImageInputStream or other Object. The input source must be set before any of the query or read methods are used. If input is null, any currently set input source will be removed. In any case, the value of minIndex will be initialized to 0.

      This method is equivalent to setInput(input, false, false).

      Parameters:
      input - the ImageInputStream or other Object to use for future decoding.
      Throws:
      IllegalArgumentException - if input is not an instance of one of the classes returned by the originating service provider's getInputTypes method, or is not an ImageInputStream.
      See Also:
      getInput()

    • getInput

      public Object getInput()
      Returns the ImageInputStream or other Object previously set as the input source. If the input source has not been set, null is returned.
      Returns:
      the Object that will be used for future decoding, or null.
      See Also:
      ImageInputStream, setInput(java.lang.Object, boolean, boolean)

    • isSeekForwardOnly

      public boolean isSeekForwardOnly()
      Returns true if the current input source has been marked as seek forward only by passing true as the seekForwardOnly argument to the setInput method.
      Returns:
      true if the input source is seek forward only.
      See Also:
      setInput(java.lang.Object, boolean, boolean)

    • isIgnoringMetadata

      public boolean isIgnoringMetadata()
      Returns true if the current input source has been marked as allowing metadata to be ignored by passing true as the ignoreMetadata argument to the setInput method.
      Returns:
      true if the metadata may be ignored.
      See Also:
      setInput(java.lang.Object, boolean, boolean)

    • getMinIndex

      public int getMinIndex()
      Returns the lowest valid index for reading an image, thumbnail, or image metadata. If seekForwardOnly() is false, this value will typically remain 0, indicating that random access is possible. Otherwise, it will contain the value of the most recently accessed index, and increase in a monotonic fashion.
      Returns:
      the minimum legal index for reading.

    • getAvailableLocales

      public Locale[] getAvailableLocales()
      Returns an array of Locales that may be used to localize warning listeners and compression settings. A return value of null indicates that localization is not supported.

      The default implementation returns a clone of the availableLocales instance variable if it is non-null, or else returns null.

      Returns:
      an array of Locales that may be used as arguments to setLocale, or null.

    • setLocale

      public void setLocale​(Locale locale)
      Sets the current Locale of this ImageReader to the given value. A value of null removes any previous setting, and indicates that the reader should localize as it sees fit.
      Parameters:
      locale - the desired Locale, or null.
      Throws:
      IllegalArgumentException - if locale is non-null but is not one of the values returned by getAvailableLocales.
      See Also:
      getLocale()

    • getLocale

      public Locale getLocale()
      Returns the currently set Locale, or null if none has been set.
      Returns:
      the current Locale, or null.
      See Also:
      setLocale(java.util.Locale)

    • getNumImages

      public abstract int getNumImages​(boolean allowSearch) throws IOException
      Returns the number of images, not including thumbnails, available from the current input source.

      Note that some image formats (such as animated GIF) do not specify how many images are present in the stream. Thus determining the number of images will require the entire stream to be scanned and may require memory for buffering. If images are to be processed in order, it may be more efficient to simply call read with increasing indices until an IndexOutOfBoundsException is thrown to indicate that no more images are available. The allowSearch parameter may be set to false to indicate that an exhaustive search is not desired; the return value will be -1 to indicate that a search is necessary. If the input has been specified with seekForwardOnly set to true, this method throws an IllegalStateException if allowSearch is set to true.

      Parameters:
      allowSearch - if true, the true number of images will be returned even if a search is required. If false, the reader may return -1 without performing the search.
      Returns:
      the number of images, as an int, or -1 if allowSearch is false and a search would be required.
      Throws:
      IllegalStateException - if the input source has not been set, or if the input has been specified with seekForwardOnly set to true.
      IOException - if an error occurs reading the information from the input source.
      See Also:
      setInput(java.lang.Object, boolean, boolean)

    • getWidth

      public abstract int getWidth​(int imageIndex) throws IOException
      Returns the width in pixels of the given image within the input source.

      If the image can be rendered to a user-specified size, then this method returns the default width.

      Parameters:
      imageIndex - the index of the image to be queried.
      Returns:
      the width of the image, as an int.
      Throws:
      IllegalStateException - if the input source has not been set.
      IndexOutOfBoundsException - if the supplied index is out of bounds.
      IOException - if an error occurs reading the width information from the input source.

    • getHeight

      public abstract int getHeight​(int imageIndex) throws IOException
      Returns the height in pixels of the given image within the input source.

      If the image can be rendered to a user-specified size, then this method returns the default height.

      Parameters:
      imageIndex - the index of the image to be queried.
      Returns:
      the height of the image, as an int.
      Throws:
      IllegalStateException - if the input source has not been set.
      IndexOutOfBoundsException - if the supplied index is out of bounds.
      IOException - if an error occurs reading the height information from the input source.

    • isRandomAccessEasy

      public boolean isRandomAccessEasy​(int imageIndex) throws IOException
      Returns true if the storage format of the given image places no inherent impediment on random access to pixels. For most compressed formats, such as JPEG, this method should return false, as a large section of the image in addition to the region of interest may need to be decoded.

      This is merely a hint for programs that wish to be efficient; all readers must be able to read arbitrary regions as specified in an ImageReadParam.

      Note that formats that return false from this method may nonetheless allow tiling (e.g. Restart Markers in JPEG), and random access will likely be reasonably efficient on tiles. See isImageTiled.

      A reader for which all images are guaranteed to support easy random access, or are guaranteed not to support easy random access, may return true or false respectively without accessing any image data. In such cases, it is not necessary to throw an exception even if no input source has been set or the image index is out of bounds.

      The default implementation returns false.

      Parameters:
      imageIndex - the index of the image to be queried.
      Returns:
      true if reading a region of interest of the given image is likely to be efficient.
      Throws:
      IllegalStateException - if an input source is required to determine the return value, but none has been set.
      IndexOutOfBoundsException - if an image must be accessed to determine the return value, but the supplied index is out of bounds.
      IOException - if an error occurs during reading.

    • getAspectRatio

      public float getAspectRatio​(int imageIndex) throws IOException
      Returns the aspect ratio of the given image (that is, its width divided by its height) as a float. For images that are inherently resizable, this method provides a way to determine the appropriate width given a desired height, or vice versa. For non-resizable images, the true width and height are used.

      The default implementation simply returns (float)getWidth(imageIndex)/getHeight(imageIndex).

      Parameters:
      imageIndex - the index of the image to be queried.
      Returns:
      a float indicating the aspect ratio of the given image.
      Throws:
      IllegalStateException - if the input source has not been set.
      IndexOutOfBoundsException - if the supplied index is out of bounds.
      IOException - if an error occurs during reading.

    • getRawImageType

      public ImageTypeSpecifier getRawImageType​(int imageIndex) throws IOException
      Returns an ImageTypeSpecifier indicating the SampleModel and ColorModel which most closely represents the "raw" internal format of the image. If there is no close match then a type which preserves the most information from the image should be returned. The returned value should also be included in the list of values returned by getImageTypes.

      The default implementation simply returns the first entry from the list provided by getImageType.

      Parameters:
      imageIndex - the index of the image to be queried.
      Returns:
      an ImageTypeSpecifier.
      Throws:
      IllegalStateException - if the input source has not been set.
      IndexOutOfBoundsException - if the supplied index is out of bounds.
      IOException - if an error occurs reading the format information from the input source.

    • getImageTypes

      public abstract Iterator<ImageTypeSpecifier> getImageTypes​(int imageIndex) throws IOException
      Returns an Iterator containing possible image types to which the given image may be decoded, in the form of ImageTypeSpecifierss. At least one legal image type will be returned.

      The first element of the iterator should be the most "natural" type for decoding the image with as little loss as possible. For example, for a JPEG image the first entry should be an RGB image, even though the image data is stored internally in a YCbCr color space.

      Parameters:
      imageIndex - the index of the image to be retrieved.
      Returns:
      an Iterator containing at least one ImageTypeSpecifier representing suggested image types for decoding the current given image.
      Throws:
      IllegalStateException - if the input source has not been set.
      IndexOutOfBoundsException - if the supplied index is out of bounds.
      IOException - if an error occurs reading the format information from the input source.
      See Also:
      ImageReadParam.setDestination(BufferedImage), IIOParam.setDestinationType(ImageTypeSpecifier)

    • getDefaultReadParam

      public ImageReadParam getDefaultReadParam()
      Returns a default ImageReadParam object appropriate for this format. All subclasses should define a set of default values for all parameters and return them with this call. This method may be called before the input source is set.

      The default implementation constructs and returns a new ImageReadParam object that does not allow source scaling (i.e., it returns new ImageReadParam().

      Returns:
      an ImageReadParam object which may be used to control the decoding process using a set of default settings.

    • getStreamMetadata

      public abstract IIOMetadata getStreamMetadata() throws IOException
      Returns an IIOMetadata object representing the metadata associated with the input source as a whole (i.e., not associated with any particular image), or null if the reader does not support reading metadata, is set to ignore metadata, or if no metadata is available.
      Returns:
      an IIOMetadata object, or null.
      Throws:
      IOException - if an error occurs during reading.

    • getStreamMetadata

      public IIOMetadata getStreamMetadata​(String formatName, Set<String> nodeNames) throws IOException
      Returns an IIOMetadata object representing the metadata associated with the input source as a whole (i.e., not associated with any particular image). If no such data exists, null is returned.

      The resulting metadata object is only responsible for returning documents in the format named by formatName. Within any documents that are returned, only nodes whose names are members of nodeNames are required to be returned. In this way, the amount of metadata processing done by the reader may be kept to a minimum, based on what information is actually needed.

      If formatName is not the name of a supported metadata format, null is returned.

      In all cases, it is legal to return a more capable metadata object than strictly necessary. The format name and node names are merely hints that may be used to reduce the reader's workload.

      The default implementation simply returns the result of calling getStreamMetadata(), after checking that the format name is supported. If it is not, null is returned.

      Parameters:
      formatName - a metadata format name that may be used to retrieve a document from the returned IIOMetadata object.
      nodeNames - a Set containing the names of nodes that may be contained in a retrieved document.
      Returns:
      an IIOMetadata object, or null.
      Throws:
      IllegalArgumentException - if formatName is null.
      IllegalArgumentException - if nodeNames is null.
      IOException - if an error occurs during reading.

    • getImageMetadata

      public abstract IIOMetadata getImageMetadata​(int imageIndex) throws IOException
      Returns an IIOMetadata object containing metadata associated with the given image, or null if the reader does not support reading metadata, is set to ignore metadata, or if no metadata is available.
      Parameters:
      imageIndex - the index of the image whose metadata is to be retrieved.
      Returns:
      an IIOMetadata object, or null.
      Throws:
      IllegalStateException - if the input source has not been set.
      IndexOutOfBoundsException - if the supplied index is out of bounds.
      IOException - if an error occurs during reading.

    • getImageMetadata

      public IIOMetadata getImageMetadata​(int imageIndex, String formatName, Set<String> nodeNames) throws IOException
      Returns an IIOMetadata object representing the metadata associated with the given image, or null if the reader does not support reading metadata or none is available.

      The resulting metadata object is only responsible for returning documents in the format named by formatName. Within any documents that are returned, only nodes whose names are members of nodeNames are required to be returned. In this way, the amount of metadata processing done by the reader may be kept to a minimum, based on what information is actually needed.

      If formatName is not the name of a supported metadata format, null may be returned.

      In all cases, it is legal to return a more capable metadata object than strictly necessary. The format name and node names are merely hints that may be used to reduce the reader's workload.

      The default implementation simply returns the result of calling getImageMetadata(imageIndex), after checking that the format name is supported. If it is not, null is returned.

      Parameters:
      imageIndex - the index of the image whose metadata is to be retrieved.
      formatName - a metadata format name that may be used to retrieve a document from the returned IIOMetadata object.
      nodeNames - a Set containing the names of nodes that may be contained in a retrieved document.
      Returns:
      an IIOMetadata object, or null.
      Throws:
      IllegalStateException - if the input source has not been set.
      IndexOutOfBoundsException - if the supplied index is out of bounds.
      IllegalArgumentException - if formatName is null.
      IllegalArgumentException - if nodeNames is null.
      IOException - if an error occurs during reading.

    • read

      public BufferedImage read​(int imageIndex) throws IOException
      Reads the image indexed by imageIndex and returns it as a complete BufferedImage, using a default ImageReadParam. This is a convenience method that calls read(imageIndex, null).

      The image returned will be formatted according to the first ImageTypeSpecifier returned from getImageTypes.

      Any registered IIOReadProgressListener objects will be notified by calling their imageStarted method, followed by calls to their imageProgress method as the read progresses. Finally their imageComplete method will be called. IIOReadUpdateListener objects may be updated at other times during the read as pixels are decoded. Finally, IIOReadWarningListener objects will receive notification of any non-fatal warnings that occur during decoding.

      Parameters:
      imageIndex - the index of the image to be retrieved.
      Returns:
      the desired portion of the image as a BufferedImage.
      Throws: