org.jaitools.imageutils.iterator
Class WindowIterator

java.lang.Object
  org.jaitools.imageutils.iterator.WindowIterator

public class WindowIterator
extends Object

An image iterator that passes a moving window over an image.

Example of use:

 RenderedImage myImage = ...
 // Pass a 3x3 window, with the key element at pos (1,1), over band 0
 // of the image
 WindowIter iter = new WindowIter(myImage(myImage, null, new Dimension(3,3), new Point(1,1));
 int[][] dataWindow = new int[3][3];
 do {
     iter.getWindow(dataWindow);
     // do something with data
 } while (iter.next());
 

As with the JAI RectIter.getSample methods, alternative getWindow methods are provided to return values as either integers, floats or doubles, optionally for a specified image band.

Note that control of the iterator position is different to the RectIter class which has separate methods to advance and reset pixel, line and band position:

• The iterator is advanced with the next() method which handles movement in both X and Y directions.
• The iterator can be configured to move more than a single pixel / line via the xstep and ystep arguments to the full constructor. If the step distance is larger than the corresponding window dimension then some target image pixels will be absent from the data windows returned by the iterator.
• It is always safe to call the next method speculatively, although the hasNext() method is also provided for convenience.
• The iterator's position is defined as the coordinates of the target image pixel at the data window's key element. The current position can be retrieved using the getPos() method.

When the moving window is positioned over an edge of the image, those data window cells beyond the image will be filled with a specified outside value. By default this is zero but an alternative value can be provided via the outsideValue argument to the full constructor.

Since:

1.2

Version:

$Id$

Author:

Michael Bedward

Constructor Summary

WindowIterator(RenderedImage image, Rectangle bounds, Dimension windowDim, Point keyElement)
Creates a new iterator.

WindowIterator(RenderedImage image, Rectangle bounds, Dimension windowDim, Point keyElement, int xstep, int ystep, Number outsideValue)
Creates a new iterator.

WindowIterator(RenderedImage image, Rectangle bounds, Dimension windowDim, Point keyElement, Number outsideValue)
Creates a new iterator.

Method Summary

Point	getPos() Gets the target image coordinates of the pixel currently at the window key element position.
Number[][]	getWindow(Number[][] dest) Gets the data window at the current iterator position in image band 0 as Number values.
Number[][]	getWindow(Number[][] dest, int band) Gets the data window at the current iterator position and specified image band as Number values.
double[][]	getWindowDouble(double[][] dest) Gets the data window at the current iterator position in image band 0 as double values.
double[][]	getWindowDouble(double[][] dest, int band) Gets the data window at the current iterator position and specified image band as double values.
float[][]	getWindowFloat(float[][] dest) Gets the data window at the current iterator position in image band 0 as float values.
float[][]	getWindowFloat(float[][] dest, int band) Gets the data window at the current iterator position and specified image band as float values.
int[][]	getWindowInt(int[][] dest) Gets the data window at the current iterator position in image band 0 as integer values.
int[][]	getWindowInt(int[][] dest, int band) Gets the data window at the current iterator position and specified image band as integer values.
boolean	hasNext() Tests if this iterator has more data.
boolean	next() Advances the iterator using the specified X and Y step distances.

Methods inherited from class java.lang.Object

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

Constructor Detail

WindowIterator

public WindowIterator(RenderedImage image,
                      Rectangle bounds,
                      Dimension windowDim,
                      Point keyElement)

Creates a new iterator. The iterator will advance one pixel at each step and parts of the data window which are outside the image bounds will be filled with zeroes.

Parameters:

image - the target image

bounds - the bounds for this iterator or null for the whole image

windowDim - the dimensions of the data window

keyElement - the position of the key element in the data window

Throws:

IllegalArgumentException - if any arguments other than bounds are null; or if keyElement does not lie within windowDim

WindowIterator

public WindowIterator(RenderedImage image,
                      Rectangle bounds,
                      Dimension windowDim,
                      Point keyElement,
                      Number outsideValue)

Creates a new iterator. The iterator will advance one pixel at each step and parts of the data window which are outside the image bounds will be filled with the specified outside value.

Parameters:

image - the target image

bounds - the bounds for this iterator or null for the whole image

windowDim - the dimensions of the data window

keyElement - the position of the key element in the data window

outsideValue - value to return for any parts of the data window that are beyond the bounds of the image

Throws:

IllegalArgumentException - if any arguments other than bounds are null; or if keyElement does not lie within windowDim

WindowIterator

public WindowIterator(RenderedImage image,
                      Rectangle bounds,
                      Dimension windowDim,
                      Point keyElement,
                      int xstep,
                      int ystep,
                      Number outsideValue)

Creates a new iterator.

Parameters:

image - the target image

bounds - the bounds for this iterator or null for the whole image

windowDim - the dimensions of the data window

keyElement - the position of the key element in the data window

xstep - step distance in X-direction (pixels)

ystep - step distance in Y-direction (lines)

outsideValue - value to return for any parts of the data window that are beyond the bounds of the image

Throws:

IllegalArgumentException - if any arguments other than bounds are null; or if keyElement does not lie within windowDim; or if either step distance is less than 1

Method Detail

getPos

public Point getPos()

Gets the target image coordinates of the pixel currently at the window key element position. Note that when the iterator has finished this method returns null.

Returns:

the pixel coordinates

hasNext

public boolean hasNext()

Tests if this iterator has more data.

Returns:

true if more data are available; false otherwise

next

public boolean next()

Advances the iterator using the specified X and Y step distances. When the right-hand edge of bound rectangle is reached the iterator automatically increments its Y (line) position. If the iterator is already at the end of bounding rectangle this method safely returns false.

Returns:

true if the iterator was advanced; false if it was already finished

getWindow

public Number[][] getWindow(Number[][] dest)

Gets the data window at the current iterator position in image band 0 as Number values. If dest is null or not equal in size to the data window dimensions a new array will be allocated, otherwise the provided array is filled. In either case, the destination array is returned for convenience.

Parameters:

dest - destination array or null

Returns:

the filled destination array

getWindow

public Number[][] getWindow(Number[][] dest,
                            int band)

Gets the data window at the current iterator position and specified image band as Number values. If dest is null or not equal in size to the data window dimensions a new array will be allocated, otherwise the provided array is filled. In either case, the destination array is returned for convenience.

Parameters:

dest - destination array or null

band - the image band from which to retrieve data

Returns:

the filled destination array

getWindowInt

public int[][] getWindowInt(int[][] dest)

Gets the data window at the current iterator position in image band 0 as integer values. If dest is null or not equal in size to the data window dimensions a new array will be allocated, otherwise the provided array is filled. In either case, the destination array is returned for convenience.

Parameters:

dest - destination array or null

Returns:

the filled destination array

getWindowInt

public int[][] getWindowInt(int[][] dest,
                            int band)

Gets the data window at the current iterator position and specified image band as integer values. If dest is null or not equal in size to the data window dimensions a new array will be allocated, otherwise the provided array is filled. In either case, the destination array is returned for convenience.

Parameters:

dest - destination array or null

band - the image band from which to retrieve data

Returns:

the filled destination array

getWindowFloat

public float[][] getWindowFloat(float[][] dest)

Gets the data window at the current iterator position in image band 0 as float values. If dest is null or not equal in size to the data window dimensions a new array will be allocated, otherwise the provided array is filled. In either case, the destination array is returned for convenience.

Parameters:

dest - destination array or null

Returns:

the filled destination array

getWindowFloat

public float[][] getWindowFloat(float[][] dest,
                                int band)

Gets the data window at the current iterator position and specified image band as float values. If dest is null or not equal in size to the data window dimensions a new array will be allocated, otherwise the provided array is filled. In either case, the destination array is returned for convenience.

Parameters:

dest - destination array or null

band - the image band from which to retrieve data

Returns:

the filled destination array

getWindowDouble

public double[][] getWindowDouble(double[][] dest)

Gets the data window at the current iterator position in image band 0 as double values. If dest is null or not equal in size to the data window dimensions a new array will be allocated, otherwise the provided array is filled. In either case, the destination array is returned for convenience.

Parameters:

dest - destination array or null

Returns:

the filled destination array

getWindowDouble

public double[][] getWindowDouble(double[][] dest,
                                  int band)

Gets the data window at the current iterator position and specified image band as double values. If dest is null or not equal in size to the data window dimensions a new array will be allocated, otherwise the provided array is filled. In either case, the destination array is returned for convenience.

Parameters:

dest - destination array or null

band - the image band from which to retrieve data

Returns:

the filled destination array