javax.imageio

Class ImageReader

public abstract class ImageReader extends 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
protected 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 Object	input An ImageInputStream from which image data is read.
protected 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 ImageReaderSpi	originatingProvider The image reader SPI that instantiated this reader.
protected List<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. false if it can read backwards in the stream.
protected List<IIOReadUpdateListener>	updateListeners A list of installed update listeners.
protected List<IIOReadWarningListener>	warningListeners A list of installed warning listeners.
protected List<Locale>	warningLocales A list of warning locales corresponding with the list of installed warning listeners.

Constructor Summary
protected	ImageReader(ImageReaderSpi originatingProvider) Construct an image reader.

Method Summary
void	abort() Request that reading be aborted.
protected boolean	abortRequested() Check if the abort flag is set.
void	addIIOReadProgressListener(IIOReadProgressListener listener) Install a read progress listener.
void	addIIOReadUpdateListener(IIOReadUpdateListener listener) Install a read update listener.
void	addIIOReadWarningListener(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, BufferedImage image, Rectangle srcRegion, 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.
Locale[]	getAvailableLocales() Retrieve the available locales.
ImageReadParam	getDefaultReadParam() Retrieve the default read parameters for this reader's image format.
protected static BufferedImage	getDestination(ImageReadParam param, Iterator<ImageTypeSpecifier> imageTypes, int width, int height) Return a suitable destination buffered image.
String	getFormatName() Retrieve the format of the input source.
abstract int	getHeight(int imageIndex) Get the height of the input image in pixels.
abstract IIOMetadata	getImageMetadata(int imageIndex) Get the metadata associated with this image.
IIOMetadata	getImageMetadata(int imageIndex, String formatName, Set<String> nodeNames) Get the metadata associated with this image.
abstract Iterator<ImageTypeSpecifier>	getImageTypes(int imageIndex) Get an iterator over the collection of image types into which this reader can decode image data.
Object	getInput() Get this reader's image input source. null is returned if the image source has not been set.
Locale	getLocale() Get this reader's locale. null is returned if the locale has not been set.
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.
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 Rectangle	getSourceRegion(ImageReadParam param, int srcWidth, int srcHeight) Calculate a source region based on the given source image dimensions and parameters.
abstract IIOMetadata	getStreamMetadata() Get the metadata associated with the image being read.
IIOMetadata	getStreamMetadata(String formatName, Set<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(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(BufferedImage image) Notifies all installed update progress listeners, by calling their passComplete methods, that a progressive pass has completed.
protected void	processPassStarted(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(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(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(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(String warning) Notifies all installed warning listeners, by calling their warningOccurred methods, that a warning message has been raised.
protected void	processWarningOccurred(String baseName, String keyword) Notify all installed warning listeners, by calling their warningOccurred methods, that a warning message has been raised.
abstract BufferedImage	read(int imageIndex, ImageReadParam param) Read the given frame into a buffered image using the given read parameters.
BufferedImage	read(int imageIndex) Read the given frame all at once, using default image read parameters, and return a buffered image.
IIOImage	readAll(int imageIndex, ImageReadParam param) Read the given frame all at once, using the given image read parameters, and return an IIOImage.
Iterator<IIOImage>	readAll(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.
RenderedImage	readAsRenderedImage(int imageIndex, ImageReadParam param) Read a rendered image.
boolean	readerSupportsThumbnails() Check if this reader supports reading thumbnails.
Raster	readRaster(int imageIndex, ImageReadParam param) Read raw raster data.
BufferedImage	readThumbnail(int imageIndex, int thumbnailIndex) Read a thumbnail.
BufferedImage	readTile(int imageIndex, int tileX, int tileY) Read the given tile into a buffered 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(IIOReadProgressListener listener) Uninstall the given read progress listener.
void	removeIIOReadUpdateListener(IIOReadUpdateListener listener) Uninstall the given read update listener.
void	removeIIOReadWarningListener(IIOReadWarningListener listener) Uninstall the given read warning listener.
void	reset() Reset this reader's internal state.
void	setInput(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	setInput(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(Object input) Set the input source to the given object.
void	setLocale(Locale locale) Set the current locale or use the default locale.

Field Detail

availableLocales

protected 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 Object input

An ImageInputStream from which image data is read.

locale

protected 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 ImageReaderSpi originatingProvider

The image reader SPI that instantiated this reader.

progressListeners

protected List<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 List<IIOReadUpdateListener> updateListeners

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

warningListeners

protected List<IIOReadWarningListener> warningListeners

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

warningLocales

protected List<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(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(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(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(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

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: IllegalArgumentException if either the given source or destination band indices are invalid

clearAbortRequest

protected void clearAbortRequest()

Clear the abort flag.

computeRegions

protected static void computeRegions(ImageReadParam param, int srcWidth, int srcHeight, BufferedImage image, Rectangle srcRegion, 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: image 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: IllegalArgumentException if either srcRegion or destRegion is null IllegalArgumentException if either of the calculated regions is empty

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)

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: IllegalStateException if input is null IndexOutOfBoundsException if the frame index is out-of-bounds IOException if a read error occurs

getAvailableLocales

public 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

getDestination

protected static BufferedImage getDestination(ImageReadParam param, Iterator<ImageTypeSpecifier> imageTypes, int width, int height)

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 IllegalArgumentException if imageTypes is null or empty, or if a non-ImageTypeSpecifier object is retrieved from imageTypes IllegalArgumentException if the resulting destination region is empty IllegalArgumentException if the product of width and height is greater than Integer.MAX_VALUE

getFormatName

public String getFormatName()

Retrieve the format of the input source.

Returns: the input source format name

Throws: IOException if a read error occurs

getHeight

public abstract int getHeight(int imageIndex)

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: IllegalStateException if input has not been set IndexOutOfBoundsException if the frame index is out-of-bounds IOException if a read error occurs

getImageMetadata

public abstract IIOMetadata getImageMetadata(int imageIndex)

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: IllegalStateException if input has not been set IndexOutOfBoundsException if the frame index is out-of-bounds IOException if a read error occurs

getImageMetadata

public IIOMetadata getImageMetadata(int imageIndex, String formatName, Set<String> nodeNames)

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: IllegalStateException if input has not been set IndexOutOfBoundsException if the frame index is out-of-bounds IllegalArgumentException if formatName is null IllegalArgumentException if nodeNames is null IOException if a read error occurs

getImageTypes

public abstract Iterator<ImageTypeSpecifier> getImageTypes(int imageIndex)

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: IllegalStateException if input has not been set IndexOutOfBoundsException if the frame index is out-of-bounds IOException if a read error occurs

getInput

public 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 Locale getLocale()

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

Returns: this reader's locale, or null

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

getNumImages

public abstract int getNumImages(boolean allowSearch)

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: IllegalStateException if input has not been set, or if seekForwardOnly is true IOException if a read error occurs

getNumThumbnails

public int getNumThumbnails(int imageIndex)

Get the number of thumbnails associated with an image.

Parameters: imageIndex the frame index

Returns: the number of thumbnails associated with this image

getOriginatingProvider

public ImageReaderSpi getOriginatingProvider()

Get the ImageReaderSpi that created this reader or null.

Returns: an ImageReaderSpi, or null

getRawImageType

public ImageTypeSpecifier getRawImageType(int imageIndex)

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: IllegalStateException if input has not been set IndexOutOfBoundsException if the frame index is out-of-bounds IOException if a read error occurs

getSourceRegion

protected static 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 abstract IIOMetadata getStreamMetadata()

Returns: metadata associated with the image being read, or null

Throws: IOException if a read error occurs

getStreamMetadata

public IIOMetadata getStreamMetadata(String formatName, Set<String> nodeNames)

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: IllegalArgumentException if formatName is null IllegalArgumentException if nodeNames is null IOException if a read error occurs

getThumbnailHeight

public int getThumbnailHeight(int imageIndex, int thumbnailIndex)

Get the height of a thumbnail image.

Parameters: imageIndex the frame index thumbnailIndex the thumbnail index

Returns: the height of the thumbnail image

Throws: UnsupportedOperationException if this reader does not support thumbnails IllegalStateException if input is null IndexOutOfBoundsException if either index is out-of-bounds IOException if a read error occurs

getThumbnailWidth

public int getThumbnailWidth(int imageIndex, int thumbnailIndex)

Get the width of a thumbnail image.

Parameters: imageIndex the frame index thumbnailIndex the thumbnail index

Returns: the width of the thumbnail image

getTileGridXOffset

public int getTileGridXOffset(int imageIndex)

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: IllegalStateException if input is needed but the input source is not set IndexOutOfBoundsException if the frame index is out-of-bounds IOException if a read error occurs

getTileGridYOffset

public int getTileGridYOffset(int imageIndex)

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: IllegalStateException if input is needed but the input source is not set IndexOutOfBoundsException if the frame index is out-of-bounds IOException if a read error occurs

getTileHeight

public int getTileHeight(int imageIndex)

Get the height of an image tile.

Parameters: imageIndex the frame index

Returns: the tile height for the given image

Throws: IllegalStateException if input is null IndexOutOfBoundsException if the frame index is out-of-bounds IOException if a read error occurs

getTileWidth

public int getTileWidth(int imageIndex)

Get the width of an image tile.

Parameters: imageIndex the frame index

Returns: the tile width for the given image

Throws: IllegalStateException if input is null IndexOutOfBoundsException if the frame index is out-of-bounds IOException if a read error occurs

getWidth

public abstract int getWidth(int imageIndex)

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: IllegalStateException if input has not been set IndexOutOfBoundsException if the frame index is out-of-bounds IOException if a read error occurs

hasThumbnails

public boolean hasThumbnails(int imageIndex)

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

Returns: true if the given image has thumbnails, false otherwise

Throws: IllegalStateException if input is null IndexOutOfBoundsException if the frame index is out-of-bounds 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)

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: IllegalStateException if input is null IndexOutOfBoundsException if the frame index is out-of-bounds IOException if a read error occurs

isRandomAccessEasy

public boolean isRandomAccessEasy(int imageIndex)

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: IllegalStateException if input is null and it is needed to determine the return value IndexOutOfBoundsException if the frame index is out-of-bounds but the frame data must be accessed to determine the return value 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(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(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(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(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(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(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.

processWarningOccurred

protected void processWarningOccurred(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: IllegalArgumentException if warning is null

processWarningOccurred

protected void processWarningOccurred(String baseName, 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: IllegalArgumentException if either baseName or keyword is null IllegalArgumentException if no resource bundle is found using baseName IllegalArgumentException if the given keyword produces no results from the resource bundle IllegalArgumentException if the retrieved object is not a String

read

public abstract BufferedImage read(int imageIndex, ImageReadParam param)

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: IllegalStateException if input is null IndexOutOfBoundsException if the frame index is out-of-bounds IOException if a read error occurs

read

public BufferedImage read(int imageIndex)

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: the index of the image frame to read

Returns: a buffered image

Throws: IllegalStateException if input has not been set IndexOutOfBoundsException if the frame index is out-of-bounds IOException if a read error occurs

readAll

public IIOImage readAll(int imageIndex, ImageReadParam param)

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: the index of the image frame to read the image read parameters

Returns: an IIOImage

Throws: IllegalStateException if input has not been set IndexOutOfBoundsException if the frame index is out-of-bounds IllegalArgumentException if param.getSourceBands() and param.getDestinationBands() are incompatible IllegalArgumentException if either the source or destination image regions are empty IOException if a read error occurs

readAll

public Iterator<IIOImage> readAll(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. 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: an iterator over the image read parameters

Returns: an IIOImage

Throws: IllegalStateException if input has not been set IllegalArgumentException if a non-ImageReadParam is found in params IllegalArgumentException if param.getSourceBands() and param.getDestinationBands() are incompatible IllegalArgumentException if either the source or destination image regions are empty IOException if a read error occurs

readAsRenderedImage

public RenderedImage readAsRenderedImage(int imageIndex, ImageReadParam param)

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: the index of the image frame to read the image read parameters

Returns: a rendered image

Throws: IllegalStateException if input is null IndexOutOfBoundsException if the frame index is out-of-bounds IllegalArgumentException if param.getSourceBands() and param.getDestinationBands() are incompatible IllegalArgumentException if either the source or destination image regions are empty 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 Raster readRaster(int imageIndex, ImageReadParam param)

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: UnsupportedOperationException if this reader doesn't support rasters IllegalStateException if input is null IndexOutOfBoundsException if the frame index is out-of-bounds IOException if a read error occurs

readThumbnail

public BufferedImage readThumbnail(int imageIndex, int thumbnailIndex)

Read a thumbnail.

Parameters: imageIndex the frame index thumbnailIndex the thumbnail index

Returns: a buffered image of the thumbnail

Throws: UnsupportedOperationException if this reader doesn't support thumbnails IllegalStateException if input is null IndexOutOfBoundsException if either the frame index or the thumbnail index is out-of-bounds IOException if a read error occurs

readTile

public BufferedImage readTile(int imageIndex, int tileX, int tileY)

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: IllegalStateException if input is null IndexOutOfBoundsException if the frame index is out-of-bounds IllegalArgumentException if the tile coordinates are out-of-bounds IOException if a read error occurs

readTileRaster

public Raster readTileRaster(int imageIndex, int tileX, int tileY)

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: UnsupportedOperationException if rasters are not supported IllegalStateException if input is null IndexOutOfBoundsException if the frame index is out-of-bounds IllegalArgumentException if the tile coordinates are out-of-bounds 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(IIOReadProgressListener listener)

Uninstall the given read progress listener.

Parameters: listener the listener to remove

removeIIOReadUpdateListener

public void removeIIOReadUpdateListener(IIOReadUpdateListener listener)

Uninstall the given read update listener.

Parameters: listener the listener to remove

removeIIOReadWarningListener

public void removeIIOReadWarningListener(IIOReadWarningListener listener)

Uninstall the given read warning listener.

Parameters: listener the listener to remove

reset

public void reset()

Reset this reader's internal state.

setInput

public void setInput(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: IllegalArgumentException if input is not a valid input source for this reader and is not an ImageInputStream

setInput

public void setInput(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: 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

Throws: IllegalArgumentException if input is not a valid input source for this reader and is not an ImageInputStream

setInput

public void setInput(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: IllegalArgumentException if input is not a valid input source for this reader and is not an ImageInputStream

setLocale

public void setLocale(Locale locale)

Set the current locale or use the default locale.

Parameters: locale the locale to set, or null