org.jaitools.imageutils.iterator
Class AbstractSimpleIterator

java.lang.Object
  extended by 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


Copyright © 2009-2013. All Rights Reserved.