Module org.opengis.geoapi.conformance
Package org.opengis.test.coverage.image

Class PixelIterator

Object
PixelIterator
public class PixelIterator extends Object
A row-major iterator over sample values in a Raster or RenderedImage. For any image (tiled or not), this class iterates first over the bands, then over the columns and finally over the rows. If the image is tiled, then this iterator will perform the necessary calls to the RenderedImage.getTile(int, int) method for each row in order to perform the iteration as if the image was untiled.

On creation, this iterator is positioned before the first sample value. To use this iterator, invoke the next() method in a while loop as below:

PixelIterator it = new PixelIterator(image);
while (it.next()) {
    float value = it.getSampleFloat();
    // Do some processing with the value here...
}
Since:
3.1
See Also:

  • Constructor Summary

    Constructors
    Constructor
    Description
    PixelIterator(Raster raster)
    Creates an iterator for the whole area of the given raster.
    PixelIterator(Raster raster, Rectangle subArea, int xSubsampling, int ySubsampling, int[] sourceBands)
    Creates an iterator for a sub-area of the given raster.
    PixelIterator(RenderedImage image)
    Creates an iterator for the whole area of the given image.
    PixelIterator(RenderedImage image, Rectangle subArea, int xSubsampling, int ySubsampling, int[] sourceBands)
    Creates an iterator for a sub-area of the given image.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    assertSampleValuesEqual(PixelIterator actual, double tolerance)
    Compares all sample values iterated by this PixelIterator with the sample values iterated by the given iterator.
    int
    getBand()
    Returns the current band index.
    int
    getDataType()
    Returns the type of the sample values, as one of the TYPE_* constants defined in the DataBuffer class.
    int
    getSample()
    Returns the sample value at the current position, as an integer.
    double
    getSampleDouble()
    Returns the sample value at the current position, as a double-precision floating point number.
    float
    getSampleFloat()
    Returns the sample value at the current position, as a floating point number.
    int
    getX()
    Returns the current x coordinate.
    int
    getY()
    Returns the current y coordinate.
    boolean
    next()
    Moves to the next sample values and returns true if the iteration has more pixels.
    String
    toString()
    Returns a string representation of this iterator position for debugging purpose.

    Methods inherited from class Object

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

  • Constructor Details

    • PixelIterator

      public PixelIterator(Raster raster)
      Creates an iterator for the whole area of the given raster.
      Parameters:
      raster - The raster for which to create an iterator.

    • PixelIterator

      public PixelIterator(RenderedImage image)
      Creates an iterator for the whole area of the given image.
      Parameters:
      image - The image for which to create an iterator.

    • PixelIterator

      public PixelIterator(Raster raster, Rectangle subArea, int xSubsampling, int ySubsampling, int[] sourceBands)
      Creates an iterator for a sub-area of the given raster.
      Parameters:
      raster - the raster to iterate over.
      subArea - rectangle which represent raster sub area iteration, or null if none.
      xSubsampling - the iteration step when moving to the next pixel.
      ySubsampling - the iteration step when moving to the next scan line.
      sourceBands - the source bands, or null if none.

    • PixelIterator

      public PixelIterator(RenderedImage image, Rectangle subArea, int xSubsampling, int ySubsampling, int[] sourceBands)
      Creates an iterator for a sub-area of the given image.
      Parameters:
      image - the image to iterate over.
      subArea - rectangle which represent image sub area iteration, or null if none.
      xSubsampling - the iteration step when moving to the next pixel.
      ySubsampling - the iteration step when moving to the next scan line.
      sourceBands - the source bands, or null if none.

  • Method Details

    • next

      public boolean next()
      Moves to the next sample values and returns true if the iteration has more pixels.
      Returns:
      true if the next sample value exist.

    • getX

      public int getX()
      Returns the current x coordinate. The coordinate values range from image X minimum (inclusive) to that minimum plus the image width (exclusive).
      Returns:
      the current x coordinate.
      See Also:

    • getY

      public int getY()
      Returns the current y coordinate. The coordinate values range from image Y minimum (inclusive) to that minimum plus the image height (exclusive).
      Returns:
      the current y coordinate.
      See Also:

    • getBand

      public int getBand()
      Returns the current band index. The index values range from 0 (inclusive) to the number of bands (exclusive), or to the sourceBands array length (exclusive) if the array given to the constructor was non-null.
      Returns:
      the current band index.
      See Also:

    • getDataType

      public int getDataType()
      Returns the type of the sample values, as one of the TYPE_* constants defined in the DataBuffer class.
      Returns:
      the type of the sample values.
      See Also:

    • getSample

      public int getSample()
      Returns the sample value at the current position, as an integer. This method is appropriate for the byte, short, unsigned short and integer datatypes.
      Returns:
      the sample value at the current position.
      See Also:

    • getSampleFloat

      public float getSampleFloat()
      Returns the sample value at the current position, as a floating point number.
      Returns:
      the sample value at the current position.
      See Also:

    • getSampleDouble

      public double getSampleDouble()
      Returns the sample value at the current position, as a double-precision floating point number.
      Returns:
      the sample value at the current position.
      See Also:

    • assertSampleValuesEqual

      public void assertSampleValuesEqual(PixelIterator actual, double tolerance) throws AssertionError
      Compares all sample values iterated by this PixelIterator with the sample values iterated by the given iterator. If a mismatch is found, then an AssertionError is thrown with a detailed error message.

      This method does not verify the image sizes, number of tiles, number of bands, color model or datatype. Consequently, this method is robust to the following differences:

      • Differences in the (x, y) origin;
      • Differences in tile layout (images are compared as if they were untiled);
      • Differences in the datatype (values are compared using the widest of this iterator datatype and the datatype of the given iterator).
      If the images have different sizes, then an "Unexpected end of iteration" exception will be thrown when the first iterator reaches the iteration end.
      Parameters:
      actual - the iterator that contains the actual values to be compared with the "expected" sample values.
      tolerance - the tolerance threshold for floating point comparison. This threshold does not apply to integer types.
      Throws:
      AssertionError - if a value in this iterator is not equals to a value in the given iterator with the given tolerance threshold.

    • toString

      public String toString()
      Returns a string representation of this iterator position for debugging purpose.
      Overrides:
      toString in class Object
      Returns:
      a string representation if this iterator position.