javax.imageio

Class ImageReader

java.lang.Object

javax.imageio.ImageReader

public abstract class ImageReader
extends java.lang.Object

A class for decoding images within the ImageIO framework. An ImageReader for a given format is instantiated by an ImageReaderSpi for that format. ImageReaderSpis are registered with the IIORegistry. The ImageReader API supports reading animated images that may have multiple frames; to support such images many methods take an index parameter. Images may also be read in multiple passes, where each successive pass increases the level of detail in the destination image.

Field Summary

Fields

Modifier and Type	Field and Description
protected java.util.Locale[]	availableLocales All locales available for localization of warning messages, or null if localization is not supported.
protected boolean	ignoreMetadata true if the input source does not require metadata to be read, false otherwise.
protected java.lang.Object	input An ImageInputStream from which image data is read.
protected java.util.Locale	locale The current locale used to localize warning messages, or null if no locale has been set.
protected int	minIndex The minimum index at which data can be read.
protected javax.imageio.spi.ImageReaderSpi	originatingProvider The image reader SPI that instantiated this reader.
protected java.util.List<javax.imageio.event.IIOReadProgressListener>	progressListeners A list of installed progress listeners.
protected boolean	seekForwardOnly true if this reader should only read data further ahead in the stream than its current location.
protected java.util.List<javax.imageio.event.IIOReadUpdateListener>	updateListeners A list of installed update listeners.
protected java.util.List<javax.imageio.event.IIOReadWarningListener>	warningListeners A list of installed warning listeners.
protected java.util.List<java.util.Locale>	warningLocales A list of warning locales corresponding with the list of installed warning listeners.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	ImageReader(javax.imageio.spi.ImageReaderSpi originatingProvider) Construct an image reader.

Method Summary

Methods

Modifier and Type	Method and Description
void	abort() Request that reading be aborted.
protected boolean	abortRequested() Check if the abort flag is set.
void	addIIOReadProgressListener(javax.imageio.event.IIOReadProgressListener listener) Install a read progress listener.
void	addIIOReadUpdateListener(javax.imageio.event.IIOReadUpdateListener listener) Install a read update listener.
void	addIIOReadWarningListener(javax.imageio.event.IIOReadWarningListener listener) Install a read warning listener.
boolean	canReadRaster() Check if this reader can handle raster data.
protected static void	checkReadParamBandSettings(ImageReadParam param, int numSrcBands, int numDstBands) Check that the given read parameters have valid source and destination band settings.
protected void	clearAbortRequest() Clear the abort flag.
protected static void	computeRegions(ImageReadParam param, int srcWidth, int srcHeight, java.awt.image.BufferedImage image, java.awt.Rectangle srcRegion, java.awt.Rectangle destRegion) Calcluate the source and destination regions that will be read from and written to, given image parameters and/or a destination buffered image.
void	dispose() Releases any resources allocated to this object.
float	getAspectRatio(int imageIndex) Returns the aspect ratio of this image, the ration of its width to its height.
java.util.Locale[]	getAvailableLocales() Retrieve the available locales.
ImageReadParam	getDefaultReadParam() Retrieve the default read parameters for this reader's image format.
protected static java.awt.image.BufferedImage	getDestination(ImageReadParam param, java.util.Iterator<ImageTypeSpecifier> imageTypes, int width, int height) Return a suitable destination buffered image.
java.lang.String	getFormatName() Retrieve the format of the input source.
abstract int	getHeight(int imageIndex) Get the height of the input image in pixels.
abstract javax.imageio.metadata.IIOMetadata	getImageMetadata(int imageIndex) Get the metadata associated with this image.
javax.imageio.metadata.IIOMetadata	getImageMetadata(int imageIndex, java.lang.String formatName, java.util.Set<java.lang.String> nodeNames) Get the metadata associated with this image.
abstract java.util.Iterator<ImageTypeSpecifier>	getImageTypes(int imageIndex) Get an iterator over the collection of image types into which this reader can decode image data.
java.lang.Object	getInput() Get this reader's image input source.
java.util.Locale	getLocale() Get this reader's locale.
int	getMinIndex() Get the index at which the next image will be read.
abstract int	getNumImages(boolean allowSearch) Return the number of images available from the image input source, not including thumbnails.
int	getNumThumbnails(int imageIndex) Get the number of thumbnails associated with an image.
javax.imageio.spi.ImageReaderSpi	getOriginatingProvider() Get the ImageReaderSpi that created this reader or null.
ImageTypeSpecifier	getRawImageType(int imageIndex) Get the image type specifier that most closely represents the internal data representation used by this reader.
protected static java.awt.Rectangle	getSourceRegion(ImageReadParam param, int srcWidth, int srcHeight) Calculate a source region based on the given source image dimensions and parameters.
abstract javax.imageio.metadata.IIOMetadata	getStreamMetadata() Get the metadata associated with the image being read.
javax.imageio.metadata.IIOMetadata	getStreamMetadata(java.lang.String formatName, java.util.Set<java.lang.String> nodeNames) Get the metadata associated with the image being read.
int	getThumbnailHeight(int imageIndex, int thumbnailIndex) Get the height of a thumbnail image.
int	getThumbnailWidth(int imageIndex, int thumbnailIndex) Get the width of a thumbnail image.
int	getTileGridXOffset(int imageIndex) Get the X coordinate in pixels of the top-left corner of the first tile in this image.
int	getTileGridYOffset(int imageIndex) Get the Y coordinate in pixels of the top-left corner of the first tile in this image.
int	getTileHeight(int imageIndex) Get the height of an image tile.
int	getTileWidth(int imageIndex) Get the width of an image tile.
abstract int	getWidth(int imageIndex) Get the width of the input image in pixels.
boolean	hasThumbnails(int imageIndex) Check whether or not the given image has thumbnails associated with it.
boolean	isIgnoringMetadata() Check if this image reader ignores metadata.
boolean	isImageTiled(int imageIndex) Check if the given image is sub-divided into equal-sized non-overlapping pixel rectangles.
boolean	isRandomAccessEasy(int imageIndex) Check if all pixels in this image are readily accessible.
boolean	isSeekForwardOnly() Check if this image reader may only seek forward within the input stream.
protected void	processImageComplete() Notifies all installed read progress listeners that image loading has completed by calling their imageComplete methods.
protected void	processImageProgress(float percentageDone) Notifies all installed read progress listeners that a certain percentage of the image has been loaded, by calling their imageProgress methods.
protected void	processImageStarted(int imageIndex) Notifies all installed read progress listeners, by calling their imageStarted methods, that image loading has started on the given image.
protected void	processImageUpdate(java.awt.image.BufferedImage image, int minX, int minY, int width, int height, int periodX, int periodY, int[] bands) Notifies all installed read update listeners, by calling their imageUpdate methods, that the set of samples has changed.
protected void	processPassComplete(java.awt.image.BufferedImage image) Notifies all installed update progress listeners, by calling their passComplete methods, that a progressive pass has completed.
protected void	processPassStarted(java.awt.image.BufferedImage image, int pass, int minPass, int maxPass, int minX, int minY, int periodX, int periodY, int[] bands) Notifies all installed read update listeners, by calling their passStarted methods, that a new pass has begun.
protected void	processReadAborted() Notifies all installed read progress listeners that image loading has been aborted by calling their readAborted methods.
protected void	processSequenceComplete() Notifies all installed read progress listeners, by calling their sequenceComplete methods, that a sequence of images has completed loading.
protected void	processSequenceStarted(int minIndex) Notifies all installed read progress listeners, by calling their sequenceStarted methods, a sequence of images has started loading.
protected void	processThumbnailComplete() Notifies all installed read progress listeners, by calling their thumbnailComplete methods, that a thumbnail has completed loading.
protected void	processThumbnailPassComplete(java.awt.image.BufferedImage thumbnail) Notifies all installed update progress listeners, by calling their thumbnailPassComplete methods, that a progressive pass has completed on a thumbnail.
protected void	processThumbnailPassStarted(java.awt.image.BufferedImage thumbnail, int pass, int minPass, int maxPass, int minX, int minY, int periodX, int periodY, int[] bands) Notifies all installed read update listeners, by calling their thumbnailPassStarted methods, that a new pass has begun.
protected void	processThumbnailProgress(float percentageDone) Notifies all installed read progress listeners that a certain percentage of a thumbnail has been loaded, by calling their thumbnailProgress methods.
protected void	processThumbnailStarted(int imageIndex, int thumbnailIndex) Notifies all installed read progress listeners, by calling their imageStarted methods, that thumbnail loading has started on the given thumbnail of the given image.
protected void	processThumbnailUpdate(java.awt.image.BufferedImage image, int minX, int minY, int width, int height, int periodX, int periodY, int[] bands) Notifies all installed read update listeners, by calling their thumbnailUpdate methods, that the set of samples has changed.
protected void	processWarningOccurred(java.lang.String warning) Notifies all installed warning listeners, by calling their warningOccurred methods, that a warning message has been raised.
protected void	processWarningOccurred(java.lang.String baseName, java.lang.String keyword) Notify all installed warning listeners, by calling their warningOccurred methods, that a warning message has been raised.
java.awt.image.BufferedImage	read(int imageIndex) Read the given frame all at once, using default image read parameters, and return a buffered image.
abstract java.awt.image.BufferedImage	read(int imageIndex, ImageReadParam param) Read the given frame into a buffered image using the given read parameters.
IIOImage	readAll(int imageIndex, ImageReadParam param) Read the given frame all at once, using the given image read parameters, and return an IIOImage.
java.util.Iterator<IIOImage>	readAll(java.util.Iterator<? extends ImageReadParam> params) Read all image frames all at once, using the given image read parameters iterator, and return an iterator over a collection of IIOImages.
java.awt.image.RenderedImage	readAsRenderedImage(int imageIndex, ImageReadParam param) Read a rendered image.
boolean	readerSupportsThumbnails() Check if this reader supports reading thumbnails.
java.awt.image.Raster	readRaster(int imageIndex, ImageReadParam param) Read raw raster data.
java.awt.image.BufferedImage	readThumbnail(int imageIndex, int thumbnailIndex) Read a thumbnail.
java.awt.image.BufferedImage	readTile(int imageIndex, int tileX, int tileY) Read the given tile into a buffered image.
java.awt.image.Raster	readTileRaster(int imageIndex, int tileX, int tileY) Read the given tile into a raster containing the raw image data.
void	removeAllIIOReadProgressListeners() Uninstall all read progress listeners.
void	removeAllIIOReadUpdateListeners() Uninstall all read update listeners.
void	removeAllIIOReadWarningListeners() Uninstall all read warning listeners.
void	removeIIOReadProgressListener(javax.imageio.event.IIOReadProgressListener listener) Uninstall the given read progress listener.
void	removeIIOReadUpdateListener(javax.imageio.event.IIOReadUpdateListener listener) Uninstall the given read update listener.
void	removeIIOReadWarningListener(javax.imageio.event.IIOReadWarningListener listener) Uninstall the given read warning listener.
void	reset() Reset this reader's internal state.
void	setInput(java.lang.Object input) Set the input source to the given object.
void	setInput(java.lang.Object in, boolean seekForwardOnly) Set the input source to the given object and specify whether this reader should be allowed to read input from the data stream more than once.
void	setInput(java.lang.Object input, boolean seekForwardOnly, boolean ignoreMetadata) Set the input source to the given object, specify whether this reader should be allowed to read input from the data stream more than once, and specify whether this reader should ignore metadata in the input stream.
void	setLocale(java.util.Locale locale) Set the current locale or use the default locale.

Methods inherited from class java.lang.Object

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

Field Detail

availableLocales

protected java.util.Locale[] availableLocales

All locales available for localization of warning messages, or null if localization is not supported.

ignoreMetadata

protected boolean ignoreMetadata

true if the input source does not require metadata to be read, false otherwise.

input

protected java.lang.Object input

An ImageInputStream from which image data is read.

locale

protected java.util.Locale locale

The current locale used to localize warning messages, or null if no locale has been set.

minIndex

protected int minIndex

The minimum index at which data can be read. Constantly 0 if seekForwardOnly is false, always increasing if seekForwardOnly is true.

originatingProvider

protected javax.imageio.spi.ImageReaderSpi originatingProvider

The image reader SPI that instantiated this reader.

progressListeners

protected java.util.List<javax.imageio.event.IIOReadProgressListener> progressListeners

A list of installed progress listeners. Initially null, meaning no installed listeners.

seekForwardOnly

protected boolean seekForwardOnly

true if this reader should only read data further ahead in the stream than its current location. false if it can read backwards in the stream. If this is true then caching can be avoided.

updateListeners

protected java.util.List<javax.imageio.event.IIOReadUpdateListener> updateListeners

A list of installed update listeners. Initially null, meaning no installed listeners.

warningListeners

protected java.util.List<javax.imageio.event.IIOReadWarningListener> warningListeners

A list of installed warning listeners. Initially null, meaning no installed listeners.

warningLocales

protected java.util.List<java.util.Locale> warningLocales

A list of warning locales corresponding with the list of installed warning listeners. Initially null, meaning no locales.

Constructor Detail

ImageReader

protected ImageReader(javax.imageio.spi.ImageReaderSpi originatingProvider)

Construct an image reader.

Parameters:

originatingProvider - the provider that is constructing this image reader, or null

Method Detail

abort

public void abort()

Request that reading be aborted. The unread contents of the image will be undefined. Readers should clear the abort flag before starting a read operation, then poll it periodically during the read operation.

abortRequested

protected boolean abortRequested()

Check if the abort flag is set.

Returns:

true if the current read operation should be aborted, false otherwise

addIIOReadProgressListener

public void addIIOReadProgressListener(javax.imageio.event.IIOReadProgressListener listener)

Install a read progress listener. This method will return immediately if listener is null.

Parameters:

listener - a read progress listener or null

addIIOReadUpdateListener

public void addIIOReadUpdateListener(javax.imageio.event.IIOReadUpdateListener listener)

Install a read update listener. This method will return immediately if listener is null.

Parameters:

listener - a read update listener

addIIOReadWarningListener

public void addIIOReadWarningListener(javax.imageio.event.IIOReadWarningListener listener)

Install a read warning listener. This method will return immediately if listener is null. Warning messages sent to this listener will be localized using the current locale. If the current locale is null then this reader will select a sensible default.

Parameters:

listener - a read warning listener

canReadRaster

public boolean canReadRaster()

Check if this reader can handle raster data. Determines whether or not readRaster and readTileRaster throw UnsupportedOperationException.

Returns:

true if this reader supports raster data, false if not

clearAbortRequest

protected void clearAbortRequest()

Clear the abort flag.

dispose

public void dispose()

Releases any resources allocated to this object. Subsequent calls to methods on this object will produce undefined results. The default implementation does nothing; subclasses should use this method ensure that native resources are released.

getAspectRatio

public float getAspectRatio(int imageIndex)
                     throws java.io.IOException

Returns the aspect ratio of this image, the ration of its width to its height. The aspect ratio is useful when resizing an image while keeping its proportions constant.

Parameters:

imageIndex - the frame index

Returns:

the image's aspect ratio

Throws:

java.lang.IllegalStateException - if input is null

java.lang.IndexOutOfBoundsException - if the frame index is out-of-bounds

java.io.IOException - if a read error occurs

getAvailableLocales

public java.util.Locale[] getAvailableLocales()

Retrieve the available locales. Return null if no locales are available or a clone of availableLocales.

Returns:

an array of locales or null

getDefaultReadParam

public ImageReadParam getDefaultReadParam()

Retrieve the default read parameters for this reader's image format. The default implementation returns new ImageReadParam().

Returns:

image reading parameters

getFormatName

public java.lang.String getFormatName()
                               throws java.io.IOException

Retrieve the format of the input source.

Returns:

the input source format name

Throws:

java.io.IOException - if a read error occurs

getHeight

public abstract int getHeight(int imageIndex)
                       throws java.io.IOException

Get the height of the input image in pixels. If the input image is resizable then a default height is returned.

Parameters:

imageIndex - the frame index

Returns:

the height of the input image

Throws:

java.lang.IllegalStateException - if input has not been set

java.lang.IndexOutOfBoundsException - if the frame index is out-of-bounds

java.io.IOException - if a read error occurs

getImageMetadata

public abstract javax.imageio.metadata.IIOMetadata getImageMetadata(int imageIndex)
                                                             throws java.io.IOException

Get the metadata associated with this image. If the reader is set to ignore metadata or does not support reading metadata, or if no metadata is available then null is returned.

Parameters:

imageIndex - the frame index

Returns:

a metadata object, or null

Throws:

java.lang.IllegalStateException - if input has not been set

java.lang.IndexOutOfBoundsException - if the frame index is out-of-bounds

java.io.IOException - if a read error occurs

getImageTypes

public abstract java.util.Iterator<ImageTypeSpecifier> getImageTypes(int imageIndex)
                                                              throws java.io.IOException

Get an iterator over the collection of image types into which this reader can decode image data. This method is guaranteed to return at least one valid image type specifier. The elements of the iterator should be ordered; the first element should be the most appropriate image type for this decoder, followed by the second-most appropriate, and so on.

Parameters:

imageIndex - the frame index

Returns:

an iterator over a collection of image type specifiers

Throws:

java.lang.IllegalStateException - if input has not been set

java.lang.IndexOutOfBoundsException - if the frame index is out-of-bounds

java.io.IOException - if a read error occurs

setInput

public void setInput(java.lang.Object input,
            boolean seekForwardOnly,
            boolean ignoreMetadata)

Set the input source to the given object, specify whether this reader should be allowed to read input from the data stream more than once, and specify whether this reader should ignore metadata in the input stream. The input source must be set before many methods can be called on this reader. (see all ImageReader methods that throw IllegalStateException). If input is null then the current input source will be removed. Unless this reader has direct access with imaging hardware, input should be an ImageInputStream.

Parameters:

input - the input source object

seekForwardOnly - true if this reader should be allowed to read input from the data stream more than once, false otherwise

ignoreMetadata - true if this reader should ignore metadata associated with the input source, false otherwise

Throws:

java.lang.IllegalArgumentException - if input is not a valid input source for this reader and is not an ImageInputStream

setInput

public void setInput(java.lang.Object in,
            boolean seekForwardOnly)

Set the input source to the given object and specify whether this reader should be allowed to read input from the data stream more than once. The input source must be set before many methods can be called on this reader. (see all ImageReader methods that throw IllegalStateException). If input is null then the current input source will be removed.

Parameters:

in - the input source object

seekForwardOnly - true if this reader should be allowed to read input from the data stream more than once, false otherwise

Throws:

java.lang.IllegalArgumentException - if input is not a valid input source for this reader and is not an ImageInputStream

setInput

public void setInput(java.lang.Object input)

Set the input source to the given object. The input source must be set before many methods can be called on this reader. (see all ImageReader methods that throw IllegalStateException). If input is null then the current input source will be removed.

Parameters:

input - the input source object

Throws:

java.lang.IllegalArgumentException - if input is not a valid input source for this reader and is not an ImageInputStream

getInput

public java.lang.Object getInput()

Get this reader's image input source. null is returned if the image source has not been set.

Returns:

an image input source object, or null

getLocale

public java.util.Locale getLocale()

Get this reader's locale. null is returned if the locale has not been set.

Returns:

this reader's locale, or null

getNumImages

public abstract int getNumImages(boolean allowSearch)
                          throws java.io.IOException

Return the number of images available from the image input source, not including thumbnails. This method will return 1 unless this reader is reading an animated image. Certain multi-image formats do not encode the total number of images. When reading images in those formats it may be necessary to repeatedly call read, incrementing the image index at each call, until an IndexOutOfBoundsException is thrown. The allowSearch parameter determines whether all images must be available at all times. When allowSearch is false, getNumImages will return -1 if the total number of images is unknown. Otherwise this method returns the number of images.

Parameters:

allowSearch - true if all images should be available at once, false otherwise

Returns:

-1 if allowSearch is false and the total number of images is currently unknown, or the number of images

Throws:

java.lang.IllegalStateException - if input has not been set, or if seekForwardOnly is true

java.io.IOException - if a read error occurs

getNumThumbnails

public int getNumThumbnails(int imageIndex)
                     throws java.io.IOException

Get the number of thumbnails associated with an image.

Parameters:

imageIndex - the frame index

Returns:

the number of thumbnails associated with this image

Throws:

java.io.IOException

getOriginatingProvider

public javax.imageio.spi.ImageReaderSpi getOriginatingProvider()

Get the ImageReaderSpi that created this reader or null.

Returns:

an ImageReaderSpi, or null

getStreamMetadata

public abstract javax.imageio.metadata.IIOMetadata getStreamMetadata()
                                                              throws java.io.IOException

Get the metadata associated with the image being read. If the reader is set to ignore metadata or does not support reading metadata, or if no metadata is available then null is returned. This method returns metadata associated with the entirety of the image data, whereas getImageMetadata(int) returns metadata associated with a frame within a multi-image data stream.

Returns:

metadata associated with the image being read, or null

Throws:

java.io.IOException - if a read error occurs

getThumbnailHeight

public int getThumbnailHeight(int imageIndex,
                     int thumbnailIndex)
                       throws java.io.IOException

Get the height of a thumbnail image.

Parameters:

imageIndex - the frame index

thumbnailIndex - the thumbnail index

Returns:

the height of the thumbnail image

Throws:

java.lang.UnsupportedOperationException - if this reader does not support thumbnails

java.lang.IllegalStateException - if input is null

java.lang.IndexOutOfBoundsException - if either index is out-of-bounds

java.io.IOException - if a read error occurs

getThumbnailWidth

public int getThumbnailWidth(int imageIndex,
                    int thumbnailIndex)
                      throws java.io.IOException

Get the width of a thumbnail image.

Parameters:

imageIndex - the frame index

thumbnailIndex - the thumbnail index

Returns:

the width of the thumbnail image

Throws:

java.lang.UnsupportedOperationException - if this reader does not support thumbnails

java.lang.IllegalStateException - if input is null

java.lang.IndexOutOfBoundsException - if either index is out-of-bounds

java.io.IOException - if a read error occurs

getTileGridXOffset

public int getTileGridXOffset(int imageIndex)
                       throws java.io.IOException

Get the X coordinate in pixels of the top-left corner of the first tile in this image.

Parameters:

imageIndex - the frame index

Returns:

the X coordinate of this image's first tile

Throws:

java.lang.IllegalStateException - if input is needed but the input source is not set

java.lang.IndexOutOfBoundsException - if the frame index is out-of-bounds

java.io.IOException - if a read error occurs

getTileGridYOffset

public int getTileGridYOffset(int imageIndex)
                       throws java.io.IOException

Get the Y coordinate in pixels of the top-left corner of the first tile in this image.

Parameters:

imageIndex - the frame index

Returns:

the Y coordinate of this image's first tile

Throws:

java.lang.IllegalStateException - if input is needed but the input source is not set

java.lang.IndexOutOfBoundsException - if the frame index is out-of-bounds

java.io.IOException - if a read error occurs

getTileHeight

public int getTileHeight(int imageIndex)
                  throws java.io.IOException

Get the height of an image tile.

Parameters:

imageIndex - the frame index

Returns:

the tile height for the given image

Throws:

java.lang.IllegalStateException - if input is null

java.lang.IndexOutOfBoundsException - if the frame index is out-of-bounds

java.io.IOException - if a read error occurs

getTileWidth

public int getTileWidth(int imageIndex)
                 throws java.io.IOException

Get the width of an image tile.

Parameters:

imageIndex - the frame index

Returns:

the tile width for the given image

Throws:

java.lang.IllegalStateException - if input is null

java.lang.IndexOutOfBoundsException - if the frame index is out-of-bounds

java.io.IOException - if a read error occurs

getWidth

public abstract int getWidth(int imageIndex)
                      throws java.io.IOException

Get the width of the input image in pixels. If the input image is resizable then a default width is returned.

Parameters:

imageIndex - the image's index

Returns:

the width of the input image

Throws:

java.lang.IllegalStateException - if input has not been set

java.lang.IndexOutOfBoundsException - if the frame index is out-of-bounds

java.io.IOException - if a read error occurs

hasThumbnails

public boolean hasThumbnails(int imageIndex)
                      throws java.io.IOException

Check whether or not the given image has thumbnails associated with it.

Returns:

true if the given image has thumbnails, false otherwise

Throws:

java.lang.IllegalStateException - if input is null

java.lang.IndexOutOfBoundsException - if the frame index is out-of-bounds

java.io.IOException - if a read error occurs

isIgnoringMetadata

public boolean isIgnoringMetadata()

Check if this image reader ignores metadata. This method simply returns the value of ignoreMetadata.

Returns:

true if metadata is being ignored, false otherwise

isImageTiled

public boolean isImageTiled(int imageIndex)
                     throws java.io.IOException

Check if the given image is sub-divided into equal-sized non-overlapping pixel rectangles. A reader may expose tiling in the underlying format, hide it, or simulate tiling even if the underlying format is not tiled.

Returns:

true if the given image is tiled, false otherwise

Throws:

java.lang.IllegalStateException - if input is null

java.lang.IndexOutOfBoundsException - if the frame index is out-of-bounds

java.io.IOException - if a read error occurs

isRandomAccessEasy

public boolean isRandomAccessEasy(int imageIndex)
                           throws java.io.IOException

Check if all pixels in this image are readily accessible. This method should return false for compressed formats. The return value is a hint as to the efficiency of certain image reader operations.

Parameters:

imageIndex - the frame index

Returns:

true if random pixel access is fast, false otherwise

Throws:

java.lang.IllegalStateException - if input is null and it is needed to determine the return value

java.lang.IndexOutOfBoundsException - if the frame index is out-of-bounds but the frame data must be accessed to determine the return value

java.io.IOException - if a read error occurs

isSeekForwardOnly

public boolean isSeekForwardOnly()

Check if this image reader may only seek forward within the input stream.

Returns:

true if this reader may only seek forward, false otherwise

processImageComplete

protected void processImageComplete()

Notifies all installed read progress listeners that image loading has completed by calling their imageComplete methods.

processImageProgress

protected void processImageProgress(float percentageDone)

Notifies all installed read progress listeners that a certain percentage of the image has been loaded, by calling their imageProgress methods.

Parameters:

percentageDone - the percentage of image data that has been loaded

processImageStarted

protected void processImageStarted(int imageIndex)

Notifies all installed read progress listeners, by calling their imageStarted methods, that image loading has started on the given image.

Parameters:

imageIndex - the frame index of the image that has started loading

processImageUpdate

protected void processImageUpdate(java.awt.image.BufferedImage image,
                      int minX,
                      int minY,
                      int width,
                      int height,
                      int periodX,
                      int periodY,
                      int[] bands)

Notifies all installed read update listeners, by calling their imageUpdate methods, that the set of samples has changed.

Parameters:

image - the buffered image that is being updated

minX - the X coordinate of the top-left pixel in this pass

minY - the Y coordinate of the top-left pixel in this pass

width - the total width of the rectangle covered by this pass, including skipped pixels

height - the total height of the rectangle covered by this pass, including skipped pixels

periodX - the horizontal sample interval

periodY - the vertical sample interval

bands - the affected bands in the destination

processPassComplete

protected void processPassComplete(java.awt.image.BufferedImage image)

Notifies all installed update progress listeners, by calling their passComplete methods, that a progressive pass has completed.

Parameters:

image - the image that has being updated

processPassStarted

protected void processPassStarted(java.awt.image.BufferedImage image,
                      int pass,
                      int minPass,
                      int maxPass,
                      int minX,
                      int minY,
                      int periodX,
                      int periodY,
                      int[] bands)

Notifies all installed read update listeners, by calling their passStarted methods, that a new pass has begun.

Parameters:

image - the buffered image that is being updated

pass - the current pass number

minPass - the pass at which decoding will begin

maxPass - the pass at which decoding will end

minX - the X coordinate of the top-left pixel in this pass

minY - the Y coordinate of the top-left pixel in this pass

width - the total width of the rectangle covered by this pass, including skipped pixels

height - the total height of the rectangle covered by this pass, including skipped pixels

periodX - the horizontal sample interval

periodY - the vertical sample interval

bands - the affected bands in the destination

processReadAborted

protected void processReadAborted()

Notifies all installed read progress listeners that image loading has been aborted by calling their readAborted methods.

processSequenceComplete

protected void processSequenceComplete()

Notifies all installed read progress listeners, by calling their sequenceComplete methods, that a sequence of images has completed loading.

processSequenceStarted

protected void processSequenceStarted(int minIndex)

Notifies all installed read progress listeners, by calling their sequenceStarted methods, a sequence of images has started loading.

Parameters:

minIndex - the index of the first image in the sequence

processThumbnailComplete

protected void processThumbnailComplete()

Notifies all installed read progress listeners, by calling their thumbnailComplete methods, that a thumbnail has completed loading.

processThumbnailPassComplete

protected void processThumbnailPassComplete(java.awt.image.BufferedImage thumbnail)

Notifies all installed update progress listeners, by calling their thumbnailPassComplete methods, that a progressive pass has completed on a thumbnail.

Parameters:

thumbnail - the thumbnail that has being updated

processThumbnailPassStarted

protected void processThumbnailPassStarted(java.awt.image.BufferedImage thumbnail,
                               int pass,
                               int minPass,
                               int maxPass,
                               int minX,
                               int minY,
                               int periodX,
                               int periodY,
                               int[] bands)

Notifies all installed read update listeners, by calling their thumbnailPassStarted methods, that a new pass has begun.

Parameters:

thumbnail - the thumbnail that is being updated

pass - the current pass number

minPass - the pass at which decoding will begin

maxPass - the pass at which decoding will end

minX - the X coordinate of the top-left pixel in this pass

minY - the Y coordinate of the top-left pixel in this pass

width - the total width of the rectangle covered by this pass, including skipped pixels

height - the total height of the rectangle covered by this pass, including skipped pixels

periodX - the horizontal sample interval

periodY - the vertical sample interval

bands - the affected bands in the destination

processThumbnailProgress

protected void processThumbnailProgress(float percentageDone)

Notifies all installed read progress listeners that a certain percentage of a thumbnail has been loaded, by calling their thumbnailProgress methods.

Parameters:

percentageDone - the percentage of thumbnail data that has been loaded

processThumbnailStarted

protected void processThumbnailStarted(int imageIndex,
                           int thumbnailIndex)

Notifies all installed read progress listeners, by calling their imageStarted methods, that thumbnail loading has started on the given thumbnail of the given image.

Parameters:

imageIndex - the frame index of the image one of who's thumbnails has started loading

thumbnailIndex - the index of the thumbnail that has started loading

processThumbnailUpdate

protected void processThumbnailUpdate(java.awt.image.BufferedImage image,
                          int minX,
                          int minY,
                          int width,
                          int height,
                          int periodX,
                          int periodY,
                          int[] bands)

Notifies all installed read update listeners, by calling their thumbnailUpdate methods, that the set of samples has changed.

Parameters:

image - the buffered image that is being updated

minX - the X coordinate of the top-left pixel in this pass

minY - the Y coordinate of the top-left pixel in this pass

width - the total width of the rectangle covered by this pass, including skipped pixels

height - the total height of the rectangle covered by this pass, including skipped pixels

periodX - the horizontal sample interval

periodY - the vertical sample interval

bands - the affected bands in the destination

processWarningOccurred

protected void processWarningOccurred(java.lang.String warning)

Notifies all installed warning listeners, by calling their warningOccurred methods, that a warning message has been raised.

Parameters:

warning - the warning message

Throws:

java.lang.IllegalArgumentException - if warning is null

processWarningOccurred

protected void processWarningOccurred(java.lang.String baseName,
                          java.lang.String keyword)

Notify all installed warning listeners, by calling their warningOccurred methods, that a warning message has been raised. The warning message is retrieved from a resource bundle, using the given basename and keyword.

Parameters:

baseName - the basename of the resource from which to retrieve the warning message

keyword - the keyword used to retrieve the warning from the resource bundle

Throws:

java.lang.IllegalArgumentException - if either baseName or keyword is null

java.lang.IllegalArgumentException - if no resource bundle is found using baseName

java.lang.IllegalArgumentException - if the given keyword produces no results from the resource bundle

java.lang.IllegalArgumentException - if the retrieved object is not a String

read

public abstract java.awt.image.BufferedImage read(int imageIndex,
                                ImageReadParam param)
                                           throws java.io.IOException

Read the given frame into a buffered image using the given read parameters. Listeners will be notified of image loading progress and warnings.

Parameters:

imageIndex - the index of the frame to read

param - the image read parameters to use when reading

Returns:

a buffered image

Throws:

java.lang.IllegalStateException - if input is null

java.lang.IndexOutOfBoundsException - if the frame index is out-of-bounds

java.io.IOException - if a read error occurs

readerSupportsThumbnails

public boolean readerSupportsThumbnails()

Check if this reader supports reading thumbnails.

Returns:

true if this reader supports reading thumbnails, false otherwise

readRaster

public java.awt.image.Raster readRaster(int imageIndex,
                               ImageReadParam param)
                                 throws java.io.IOException

Read raw raster data. The image type specifier in param is ignored but all other parameters are used. Offset parameters are translated into the raster's coordinate space. This method may be implemented by image readers that want to provide direct access to raw image data.

Parameters:

imageIndex - the frame index

param - the image read parameters

Returns:

a raster containing the read image data

Throws:

java.lang.UnsupportedOperationException - if this reader doesn't support rasters

java.lang.IllegalStateException - if input is null

java.lang.IndexOutOfBoundsException - if the frame index is out-of-bounds

java.io.IOException - if a read error occurs

readThumbnail

public java.awt.image.BufferedImage readThumbnail(int imageIndex,
                                         int thumbnailIndex)
                                           throws java.io.IOException

Read a thumbnail.

Parameters:

imageIndex - the frame index

thumbnailIndex - the thumbnail index

Returns:

a buffered image of the thumbnail

Throws:

java.lang.UnsupportedOperationException - if this reader doesn't support thumbnails

java.lang.IllegalStateException - if input is null

java.lang.IndexOutOfBoundsException - if either the frame index or the thumbnail index is out-of-bounds

java.io.IOException - if a read error occurs

removeAllIIOReadProgressListeners

public void removeAllIIOReadProgressListeners()

Uninstall all read progress listeners.

removeAllIIOReadUpdateListeners

public void removeAllIIOReadUpdateListeners()

Uninstall all read update listeners.

removeAllIIOReadWarningListeners

public void removeAllIIOReadWarningListeners()

Uninstall all read warning listeners.

removeIIOReadProgressListener

public void removeIIOReadProgressListener(javax.imageio.event.IIOReadProgressListener listener)

Uninstall the given read progress listener.

Parameters:

listener - the listener to remove

removeIIOReadUpdateListener

public void removeIIOReadUpdateListener(javax.imageio.event.IIOReadUpdateListener listener)

Uninstall the given read update listener.

Parameters:

listener - the listener to remove

removeIIOReadWarningListener

public void removeIIOReadWarningListener(javax.imageio.event.IIOReadWarningListener listener)

Uninstall the given read warning listener.

Parameters:

listener - the listener to remove

setLocale

public void setLocale(java.util.Locale locale)

Set the current locale or use the default locale.

Parameters:

locale - the locale to set, or null

checkReadParamBandSettings

protected static void checkReadParamBandSettings(ImageReadParam param,
                              int numSrcBands,
                              int numDstBands)

Check that the given read parameters have valid source and destination band settings. If the param.getSourceBands() returns null, the array is assumed to include all band indices, 0 to numSrcBands - 1; likewise if param.getDestinationBands() returns null, it is assumed to be an array containing indices 0 to numDstBands - 1. A failure will cause this method to throw IllegalArgumentException.

Parameters:

param - the image parameters to check

numSrcBands - the number of input source bands

numDstBands - the number of ouput destination bands

Throws:

java.lang.IllegalArgumentException - if either the given source or destination band indices are invalid

computeRegions

protected static void computeRegions(ImageReadParam param,
                  int srcWidth,
                  int srcHeight,
                  java.awt.image.BufferedImage image,
                  java.awt.Rectangle srcRegion,
                  java.awt.Rectangle destRegion)

Calcluate the source and destination regions that will be read from and written to, given image parameters and/or a destination buffered image. The source region will be clipped if any of its bounds are outside the destination region. Clipping will account for subsampling and destination offsets. Likewise, the destination region is clipped to the given destination image, if it is not null, using the given image parameters, if they are not null. IllegalArgumentException is thrown if either region will contain 0 pixels after clipping.

Parameters:

param - read parameters, or null

srcWidth - the width of the source image

srcHeight - the height of the source image

image - the destination image, or null

srcRegion - a rectangle whose values will be set to the clipped source region

destRegion - a rectangle whose values will be set to the clipped destination region

Throws:

java.lang.IllegalArgumentException - if either srcRegion or destRegion is null

java.lang.IllegalArgumentException - if either of the calculated regions is empty

getDestination

protected static java.awt.image.BufferedImage getDestination(ImageReadParam param,
                                          java.util.Iterator<ImageTypeSpecifier> imageTypes,
                                          int width,
                                          int height)
                                                      throws IIOException

Return a suitable destination buffered image. If param.getDestination() is non-null, then it is returned, otherwise a buffered image is created using param.getDestinationType() if it is non-null and also in the given imageTypes collection, or the first element of imageTypes otherwise.

Parameters:

param - image read parameters from which a destination image or image type is retrieved, or null

imageTypes - a collection of legal image types

width - the width of the source image

height - the height of the source image

Returns:

a suitable destination buffered image

Throws:

IIOException - if param.getDestinationType() does not return an image type in imageTypes

java.lang.IllegalArgumentException - if imageTypes is null or empty, or if a non-ImageTypeSpecifier object is retrieved from imageTypes

java.lang.IllegalArgumentException - if the resulting destination region is empty

java.lang.IllegalArgumentException - if the product of width and height is greater than Integer.MAX_VALUE

getImageMetadata

public javax.imageio.metadata.IIOMetadata getImageMetadata(int imageIndex,
                                                  java.lang.String formatName,
                                                  java.util.Set<java.lang.String> nodeNames)
                                                    throws java.io.IOException

Get the metadata associated with this image. If the reader is set to ignore metadata or does not support reading metadata, or if no metadata is available then null is returned. This more specific version of getImageMetadata(int) can be used to restrict metadata retrieval to specific formats and node names, which can limit the amount of data that needs to be processed.

Parameters:

imageIndex - the frame index

formatName - the format of metadata requested

nodeNames - a set of Strings specifiying node names to be retrieved

Returns:

a metadata object, or null

Throws:

java.lang.IllegalStateException - if input has not been set

java.lang.IndexOutOfBoundsException - if the frame index is out-of-bounds

java.lang.IllegalArgumentException - if formatName is null

java.lang.IllegalArgumentException - if nodeNames is null

java.io.IOException - if a read error occurs

getMinIndex

public int getMinIndex()

Get the index at which the next image will be read. If seekForwardOnly is true then the returned value will increase monotonically each time an image frame is read. If seekForwardOnly is false then the returned value will always be 0.

Returns:

the current frame index

getRawImageType

public ImageTypeSpecifier getRawImageType(int imageIndex)
                                   throws java.io.IOException

Get the image type specifier that most closely represents the internal data representation used by this reader. This value should be included in the return value of getImageTypes.

Parameters:

imageIndex - the frame index

Returns:

an image type specifier

Throws:

java.lang.IllegalStateException - if input has not been set

java.lang.IndexOutOfBoundsException - if the frame index is out-of-bounds

java.io.IOException - if a read error occurs

getSourceRegion

protected static java.awt.Rectangle getSourceRegion(ImageReadParam param,
                                 int srcWidth,
                                 int srcHeight)

Calculate a source region based on the given source image dimensions and parameters. Subsampling offsets and a source region are taken from the given image read parameters and used to clip the given image dimensions, returning a new rectangular region as a result.

Parameters:

param - image parameters, or null

srcWidth - the width of the source image

srcHeight - the height of the source image

Returns:

a clipped rectangle

getStreamMetadata

public javax.imageio.metadata.IIOMetadata getStreamMetadata(java.lang.String formatName,
                                                   java.util.Set<java.lang.String> nodeNames)
                                                     throws java.io.IOException

Get the metadata associated with the image being read. If the reader is set to ignore metadata or does not support reading metadata, or if no metadata is available then null is returned. This method returns metadata associated with the entirety of the image data, whereas getStreamMetadata() returns metadata associated with a frame within a multi-image data stream. This more specific version of getStreamMetadata() can be used to restrict metadata retrieval to specific formats and node names, which can limit the amount of data that needs to be processed.

Parameters:

formatName - the format of metadata requested

nodeNames - a set of Strings specifiying node names to be retrieved

Returns:

metadata associated with the image being read, or null

Throws:

java.lang.IllegalArgumentException - if formatName is null

java.lang.IllegalArgumentException - if nodeNames is null

java.io.IOException - if a read error occurs

read

public java.awt.image.BufferedImage read(int imageIndex)
                                  throws java.io.IOException

Read the given frame all at once, using default image read parameters, and return a buffered image. The returned image will be formatted according to the currently-preferred image type specifier. Installed read progress listeners, update progress listeners and warning listeners will be notified of read progress, changes in sample sets and warnings respectively.

Parameters:

imageIndex - the index of the image frame to read

Returns:

a buffered image

Throws:

java.lang.IllegalStateException - if input has not been set

java.lang.IndexOutOfBoundsException - if the frame index is out-of-bounds

java.io.IOException - if a read error occurs

readAll

public IIOImage readAll(int imageIndex,
               ImageReadParam param)
                 throws java.io.IOException

Read the given frame all at once, using the given image read parameters, and return an IIOImage. The IIOImage will contain a buffered image as returned by getDestination. Installed read progress listeners, update progress listeners and warning listeners will be notified of read progress, changes in sample sets and warnings respectively. The source and destination band settings are checked with a call to checkReadParamBandSettings.

Parameters:

imageIndex - the index of the image frame to read

param - the image read parameters

Returns:

an IIOImage

Throws:

java.lang.IllegalStateException - if input has not been set

java.lang.IndexOutOfBoundsException - if the frame index is out-of-bounds

java.lang.IllegalArgumentException - if param.getSourceBands() and param.getDestinationBands() are incompatible

java.lang.IllegalArgumentException - if either the source or destination image regions are empty

java.io.IOException - if a read error occurs

readAll

public java.util.Iterator<IIOImage> readAll(java.util.Iterator<? extends ImageReadParam> params)
                                     throws java.io.IOException

Read all image frames all at once, using the given image read parameters iterator, and return an iterator over a collection of IIOImages. Each IIOImage in the collection will contain a buffered image as returned by getDestination. Installed read progress listeners, update progress listeners and warning listeners will be notified of read progress, changes in sample sets and warnings respectively. Each set of source and destination band settings are checked with a call to checkReadParamBandSettings.

Parameters:

params - iterator over the image read parameters

Returns:

an IIOImage

Throws:

java.lang.IllegalStateException - if input has not been set

java.lang.IllegalArgumentException - if a non-ImageReadParam is found in params

java.lang.IllegalArgumentException - if param.getSourceBands() and param.getDestinationBands() are incompatible

java.lang.IllegalArgumentException - if either the source or destination image regions are empty

java.io.IOException - if a read error occurs

readAsRenderedImage

public java.awt.image.RenderedImage readAsRenderedImage(int imageIndex,
                                               ImageReadParam param)
                                                 throws java.io.IOException

Read a rendered image. This is a more general counterpart to read (int, ImageReadParam). All image data may not be read before this method returns and so listeners will not necessarily be notified.

Parameters:

imageIndex - the index of the image frame to read

param - the image read parameters

Returns:

a rendered image

Throws:

java.lang.IllegalStateException - if input is null

java.lang.IndexOutOfBoundsException - if the frame index is out-of-bounds

java.lang.IllegalArgumentException - if param.getSourceBands() and param.getDestinationBands() are incompatible

java.lang.IllegalArgumentException - if either the source or destination image regions are empty

java.io.IOException - if a read error occurs

readTile

public java.awt.image.BufferedImage readTile(int imageIndex,
                                    int tileX,
                                    int tileY)
                                      throws java.io.IOException

Read the given tile into a buffered image. If the tile coordinates are out-of-bounds an exception is thrown. If the image is not tiled then the coordinates 0, 0 are expected and the entire image will be read.

Parameters:

imageIndex - the frame index

tileX - the horizontal tile coordinate

tileY - the vertical tile coordinate

Returns:

the contents of the tile as a buffered image

Throws:

java.lang.IllegalStateException - if input is null

java.lang.IndexOutOfBoundsException - if the frame index is out-of-bounds

java.lang.IllegalArgumentException - if the tile coordinates are out-of-bounds

java.io.IOException - if a read error occurs

readTileRaster

public java.awt.image.Raster readTileRaster(int imageIndex,
                                   int tileX,
                                   int tileY)
                                     throws java.io.IOException

Read the given tile into a raster containing the raw image data. If the tile coordinates are out-of-bounds an exception is thrown. If the image is not tiled then the coordinates 0, 0 are expected and the entire image will be read.

Parameters:

imageIndex - the frame index

tileX - the horizontal tile coordinate

tileY - the vertical tile coordinate

Returns:

the contents of the tile as a raster

Throws:

java.lang.UnsupportedOperationException - if rasters are not supported

java.lang.IllegalStateException - if input is null

java.lang.IndexOutOfBoundsException - if the frame index is out-of-bounds

java.lang.IllegalArgumentException - if the tile coordinates are out-of-bounds

java.io.IOException - if a read error occurs

reset

public void reset()

Reset this reader's internal state.