javax.media.jai.iterator
Interface RectIter

All Known Subinterfaces:

RookIter, WritableRectIter, WritableRookIter

public interface RectIter

An iterator for traversing a read-only image in top-to-bottom, left-to-right order. This will generally be the fastest style of iterator, since it does not need to perform bounds checks against the top or left edges of tiles.

The iterator is initialized with a particular rectangle as its bounds, which it is illegal to exceed. This initialization takes place in a factory method and is not a part of the iterator interface itself. Once initialized, the iterator may be reset to its initial state by means of the startLine(), startPixels(), and startBands() methods. Its position may be advanced using the nextLine(), jumpLines(), nextPixel(), jumpPixels(), and nextBand() methods.

The iterator's position may be tested against the bounding rectangle by means of the finishedLines(), finishedPixels(), and finishedBands() methods, as well as the hybrid methods nextLineDone(), nextPixelDone(), and nextBandDone().

The getSample(), getSampleFloat(), and getSampleDouble() methods are provided to allow read-only access to the source data. The various source bands may also be accessed in random fashion using the variants that accept a band index. The getPixel() methods allow retrieval of all bands simultaneously.

An instance of RectIter may be obtained by means of the RectIterFactory.create() method, which returns an opaque object implementing this interface.

See Also:

WritableRectIter, RectIterFactory

Method Summary

boolean	finishedBands() Returns true if the max band in the image has been exceeded.
boolean	finishedLines() Returns true if the bottom row of the bounding rectangle has been passed.
boolean	finishedPixels() Returns true if the right edge of the bounding rectangle has been passed.
double[]	getPixel(double[] dArray) Returns the samples of the current pixel from the image in an array of double.
float[]	getPixel(float[] fArray) Returns the samples of the current pixel from the image in an array of float.
int[]	getPixel(int[] iArray) Returns the samples of the current pixel from the image in an array of int.
int	getSample() Returns the current sample as an integer.
int	getSample(int b) Returns the specified sample of the current pixel as an integer.
double	getSampleDouble() Returns the current sample as a double.
double	getSampleDouble(int b) Returns the specified sample of the current pixel as a double.
float	getSampleFloat() Returns the current sample as a float.
float	getSampleFloat(int b) Returns the specified sample of the current pixel as a float.
void	jumpLines(int num) Jumps downward num lines from the current position.
void	jumpPixels(int num) Jumps rightward num pixels from the current position.
void	nextBand() Sets the iterator to the next band in the image.
boolean	nextBandDone() Sets the iterator to the next band in the image, and returns true if the max band has been exceeded.
void	nextLine() Sets the iterator to the next line of the image.
boolean	nextLineDone() Sets the iterator to the next line in the image, and returns true if the bottom row of the bounding rectangle has been passed.
void	nextPixel() Sets the iterator to the next pixel in image (that is, move rightward).
boolean	nextPixelDone() Sets the iterator to the next pixel in the image (that is, move rightward).
void	startBands() Sets the iterator to the first band of the image.
void	startLines() Sets the iterator to the first line of its bounding rectangle.
void	startPixels() Sets the iterator to the leftmost pixel of its bounding rectangle.

Method Detail

startLines

public void startLines()

Sets the iterator to the first line of its bounding rectangle. The pixel and band offsets are unchanged.

nextLine

public void nextLine()

Sets the iterator to the next line of the image. The pixel and band offsets are unchanged. If the iterator passes the bottom line of the rectangles, calls to get() methods are not valid.

nextLineDone

public boolean nextLineDone()

Sets the iterator to the next line in the image, and returns true if the bottom row of the bounding rectangle has been passed.

jumpLines

public void jumpLines(int num)

Jumps downward num lines from the current position. Num may be negative. The pixel and band offsets are unchanged. If the position after the jump is outside of the iterator's bounding box, an IndexOutOfBoundsException will be thrown and the position will be unchanged.

Throws:

IndexOutOfBoundsException - if the position goes outside of the iterator's bounding box.

finishedLines

public boolean finishedLines()

Returns true if the bottom row of the bounding rectangle has been passed.

startPixels

public void startPixels()

Sets the iterator to the leftmost pixel of its bounding rectangle. The line and band offsets are unchanged.

nextPixel

public void nextPixel()

Sets the iterator to the next pixel in image (that is, move rightward). The line and band offsets are unchanged.

This method may be used in conjunction with the method finishedPixels. Or the method nextPixelDone, which sets the iterator to the next pixel and checks the bound, may be used instead of this method.

nextPixelDone

public boolean nextPixelDone()

Sets the iterator to the next pixel in the image (that is, move rightward). Returns true if the right edge of the bounding rectangle has been passed. The line and band offsets are unchanged.

jumpPixels

public void jumpPixels(int num)

Jumps rightward num pixels from the current position. Num may be negative. The line and band offsets are unchanged. If the position after the jump is outside of the iterator's bounding box, an IndexOutOfBoundsException will be thrown and the position will be unchanged.

Throws:

IndexOutOfBoundsException - if the position goes outside of the iterator's bounding box.

finishedPixels

public boolean finishedPixels()

Returns true if the right edge of the bounding rectangle has been passed.

startBands

public void startBands()

Sets the iterator to the first band of the image. The pixel column and line are unchanged.

nextBand

public void nextBand()

Sets the iterator to the next band in the image. The pixel column and line are unchanged.

nextBandDone

public boolean nextBandDone()

Sets the iterator to the next band in the image, and returns true if the max band has been exceeded. The pixel column and line are unchanged.

finishedBands

public boolean finishedBands()

Returns true if the max band in the image has been exceeded.

getSample

public int getSample()

Returns the current sample as an integer.

getSample

public int getSample(int b)

Returns the specified sample of the current pixel as an integer.

Parameters:

b - the band index of the desired sample.

getSampleFloat

public float getSampleFloat()

Returns the current sample as a float.

getSampleFloat

public float getSampleFloat(int b)

Returns the specified sample of the current pixel as a float.

Parameters:

b - the band index of the desired sample.

getSampleDouble

public double getSampleDouble()

Returns the current sample as a double.

getSampleDouble

public double getSampleDouble(int b)

Returns the specified sample of the current pixel as a double.

Parameters:

b - the band index of the desired sample.

getPixel

public int[] getPixel(int[] iArray)

Returns the samples of the current pixel from the image in an array of int.

Parameters:

iArray - An optionally preallocated int array.

Returns:

the contents of the pixel as an int array.

getPixel

public float[] getPixel(float[] fArray)

Returns the samples of the current pixel from the image in an array of float.

Parameters:

fArray - An optionally preallocated float array.

Returns:

the contents of the pixel as a float array.

getPixel

public double[] getPixel(double[] dArray)

Returns the samples of the current pixel from the image in an array of double.

Parameters:

dArray - An optionally preallocated double array.

Returns:

the contents of the pixel as a double array.