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

protected static interface	AbstractSimpleIterator.DelegateHelper This is implemented by sub-classes to pass a method back to this class to create the delegate iterator.
static class	AbstractSimpleIterator.Order Constants defining the visiting order that the iterator will follow when moved with the next() method.

Field Summary

protected javax.media.jai.iterator.RectIter	delegateIter The delegate iterator.
protected int	imageDataType The data type of the target image (value of a DataBuffer constant).
protected WeakReference<RenderedImage>	imageRef A weak reference to the target image.
protected Rectangle	iterBounds The bounds of this iterator

Constructor Summary

AbstractSimpleIterator(AbstractSimpleIterator.DelegateHelper helper, RenderedImage image, Rectangle bounds, Number outsideValue, AbstractSimpleIterator.Order order)
Creates a new instance.

Method Summary

protected void	checkBandArg(int band) Helper method to check that a band value is valid.
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.
protected boolean	isInsideDelegateBounds() Tests if the iterator is currently positioned inside the delegate iterator's area (which must lie within the image bounds).
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.
protected void	setDelegatePosition() Sets the delegate iterator 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

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

Field Detail

imageRef

protected final WeakReference<RenderedImage> imageRef

A weak reference to the target image.

imageDataType

protected final int imageDataType

The data type of the target image (value of a DataBuffer constant).

iterBounds

protected final Rectangle iterBounds

The bounds of this iterator

delegateIter

protected final javax.media.jai.iterator.RectIter delegateIter

The delegate iterator.

Constructor Detail

AbstractSimpleIterator

public AbstractSimpleIterator(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.

setDelegatePosition

protected void setDelegatePosition()

Sets the delegate iterator position. If newPos is outside the target image bounds, the delegate iterator does not move.

isInsideDelegateBounds

protected boolean isInsideDelegateBounds()

Tests if the iterator is currently positioned inside the delegate iterator's area (which must lie within the image bounds).

Returns:

true if the current position is inside the delegate's bounds; false otherwise

checkBandArg

protected void checkBandArg(int band)

Helper method to check that a band value is valid.

Parameters:

band - band value