org.jaitools.imageutils.iterator

Class AbstractSimpleIterator

java.lang.Object

org.jaitools.imageutils.iterator.AbstractSimpleIterator

Direct Known Subclasses:

SimpleIterator, WritableSimpleIterator

public abstract class AbstractSimpleIterator
extends Object

Base class for image iterators with row-column (line-pixel) movement.

Author:

michael

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	AbstractSimpleIterator.Order Constants defining the visiting order that the iterator will follow when moved with the next() method.

Constructor Summary

Constructors

Constructor and Description
AbstractSimpleIterator(org.jaitools.imageutils.iterator.AbstractSimpleIterator.DelegateHelper helper, RenderedImage image, Rectangle bounds, Number outsideValue, AbstractSimpleIterator.Order order) Creates a new instance.

Method Summary

Modifier and Type	Method and Description
void	done() Closes this iterator and frees resources including the iterator's reference to the source image.
Rectangle	getBounds() Gets the bounds of this iterator.
Point	getEndPos() Gets the final position for this iterator.
RenderedImage	getImage() Returns the image that this iterator is working with.
Point	getPos() Gets the current iterator position.
Point	getPos(Point dest) Gets the current iterator position.
Number	getSample() Returns the value from the first band of the image at the current position, or the outside value if the iterator is positioned beyond the image bounds.
Number	getSample(int band) Returns the value from the specified band of the image at the current position, or the outside value if the iterator is positioned beyond the image bounds.
Number	getSample(int x, int y) Returns the value from the first band of the image at the specified position, If the position is within the iterator's bounds, but outside the target image bounds, the outside value is returned.
Number	getSample(int x, int y, int band) Returns the value from the specified band of the image at the specified position, If the position is within the iterator's bounds, but outside the target image bounds, the outside value is returned.
Number	getSample(Point pos) Returns the value from the first band of the image at the specified position, If the position is within the iterator's bounds, but outside the target image bounds, the outside value is returned.
Number	getSample(Point pos, int band) Returns the value from the specified band of the image at the specified position, If the position is within the iterator's bounds, but outside the target image bounds, the outside value is returned.
Point	getStartPos() Gets the starting position for this iterator.
List<Rectangle>	getSubBounds() Gets the list of sub-bounds for this iterator.
boolean	hasNext() Tests if this iterator can be advanced further, ie.
boolean	isWithinImage() Tests whether the iterator is currently positioned within the bounds of the target image.
boolean	next() Advances the iterator to the next position.
void	reset() Resets the iterator to its first position.
boolean	setPos(int x, int y) Sets the iterator to a new position.
boolean	setPos(Point pos) Sets the iterator to a new position.

Methods inherited from class java.lang.Object

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

Constructor Detail

AbstractSimpleIterator

public AbstractSimpleIterator(org.jaitools.imageutils.iterator.AbstractSimpleIterator.DelegateHelper helper,
                              RenderedImage image,
                              Rectangle bounds,
                              Number outsideValue,
                              AbstractSimpleIterator.Order order)

Creates a new instance. The helper object is provided by a sub-class to create the delegate iterator that will then be held by this class as a final field. The iterator bounds are allowed to extend beyond the target image bounds. When the iterator is positioned outside the target image area it returns the specified outside value.

Parameters:

helper - a helper provided by sub-class to create the delegate iterator

image - the target image

bounds - the bounds for this iterator; null means to use the target image bounds

outsideValue - value to return when positioned outside the bounds of the target image

order - order of movement for this iterator

Throws:

IllegalArgumentException - if the image argument is null

Method Detail

getImage

public RenderedImage getImage()

Returns the image that this iterator is working with. Note that the iterator only maintains a WeakReference to the image so it is possible for this method to return null.

Returns:

the image that this iterator is working with

getBounds

public Rectangle getBounds()

Gets the bounds of this iterator. Note that these may extend beyond the bounds of the target image.

Returns:

the iterator bounds

getSubBounds

public List<Rectangle> getSubBounds()

Gets the list of sub-bounds for this iterator. When the iterator is working in AbstractSimpleIterator.Order.TILE_X_Y processing order it creates a list of sub-bound rectangles by intersecting the iterator's overall bounds with the bounds of the image tiles. The sub-bounds are held in the list in the order in which they will be visited by the iterator (if advanced with the next() method).

When working in the default AbstractSimpleIterator.Order.IMAGE_X_Y processing order, this method will return a list containing a single rectangle, identical to that returned by getBounds().

The returned List and the Rectangles within it are copies, so the iterator will not be affected by subsequent modifications to them.

Returns:

list of sub-bounds in visiting order

getStartPos

public Point getStartPos()

Gets the starting position for this iterator. This is the upper-left point of the iterator's bounding rectangle. Note that it may lie outside the target image.

Returns:

the starting position

getEndPos

public Point getEndPos()

Gets the final position for this iterator. This is the lower-right point of the iterator's bounding rectangle. Note that it may lie outside the target image.

Returns:

the end position

isWithinImage

public boolean isWithinImage()

Tests whether the iterator is currently positioned within the bounds of the target image.

Returns:

true if within the target image; false otherwise

hasNext

public boolean hasNext()

Tests if this iterator can be advanced further, ie. if a call to next() would return true.

Returns:

true if the iterator can be advanced; false if it is at the end of its bounds

next

public boolean next()

Advances the iterator to the next position. The iterator moves by column (pixel), then row (line). It is always safe to call this method speculatively.

Returns:

true if the iterator was successfully advanced; false if it was already at the end of its bounds

reset

public void reset()

Resets the iterator to its first position.

getPos

public Point getPos()

Gets the current iterator position. It is always safe to call this method.

Returns:

current position

getPos

public Point getPos(Point dest)

Gets the current iterator position. If dest is not null it will be set to the current position and returned, otherwise a new Point instance is returned. It is always safe to call this method.

Returns:

current position

setPos

public boolean setPos(Point pos)

Sets the iterator to a new position. Note that a return value of true indicates that the new position was valid. If the new position is equal to the iterator's current position this method will still return true even though the iterator has not moved.

If the new position is outside this iterator's bounds, the position remains unchanged and false is returned.

Parameters:

pos - the new position

Returns:

true if the new position was valid; false otherwise

Throws:

IllegalArgumentException - if pos is null

setPos

public boolean setPos(int x,
                      int y)

Sets the iterator to a new position. Note that a return value of true indicates that the new position was valid. If the new position is equal to the iterator's current position this method will still return true even though the iterator has not moved.

If the new position is outside this iterator's bounds, the position remains unchanged and false is returned.

Parameters:

x - image X position

y - image Y position

Returns:

true if the new position was valid; false otherwise

getSample

public Number getSample()

Returns the value from the first band of the image at the current position, or the outside value if the iterator is positioned beyond the image bounds.

Returns:

image or outside value

getSample

public Number getSample(Point pos)

Returns the value from the first band of the image at the specified position, If the position is within the iterator's bounds, but outside the target image bounds, the outside value is returned. After calling this method, the iterator will be set to the specified position.

If the position is outside the iterator's bounds, null is returned and the iterator's position will remain unchanged.

Parameters:

pos - the position to sample

Returns:

image, outside value or null

Throws:

IllegalArgumentException - if pos is null

getSample

public Number getSample(int x,
                        int y)

Returns the value from the first band of the image at the specified position, If the position is within the iterator's bounds, but outside the target image bounds, the outside value is returned. After calling this method, the iterator will be set to the specified position.

If the position is outside the iterator's bounds, null is returned and the iterator's position will remain unchanged.

Parameters:

x - sampling position X-ordinate

y - sampling position Y-ordinate

Returns:

image, outside value or null

getSample

public Number getSample(int band)

Returns the value from the specified band of the image at the current position, or the outside value if the iterator is positioned beyond the image bounds.

Parameters:

band - image band

Returns:

image or outside value

Throws:

IllegalArgumentException - if band is out of range for the the target image

getSample

public Number getSample(Point pos,
                        int band)

Returns the value from the specified band of the image at the specified position, If the position is within the iterator's bounds, but outside the target image bounds, the outside value is returned. After calling this method, the iterator will be set to the specified position.

If the position is outside the iterator's bounds, null is returned and the iterator's position will remain unchanged.

Parameters:

pos - the position to sample

band - image band

Returns:

image, outside value or null

Throws:

IllegalArgumentException - if pos is null or band is out of range

getSample

public Number getSample(int x,
                        int y,
                        int band)

Returns the value from the specified band of the image at the specified position, If the position is within the iterator's bounds, but outside the target image bounds, the outside value is returned. After calling this method, the iterator will be set to the specified position.

If the position is outside the iterator's bounds, null is returned and the iterator's position will remain unchanged.

Parameters:

x - sampling position X-ordinate

y - sampling position Y-ordinate

band - image band

Returns:

image, outside value or null

Throws:

IllegalArgumentException - if band is out of range

done

public void done()

Closes this iterator and frees resources including the iterator's reference to the source image. Attempting to use the iterator after calling this method will result in an exception being thrown.