org.jaitools.imageutils.iterator
Class WindowIterator

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

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


Copyright © 2009-2013. All Rights Reserved.