Package org.apache.sis.image

Class BandedIterator

java.lang.Object
org.apache.sis.image.PixelIterator
org.apache.sis.image.WritablePixelIterator
org.apache.sis.image.BandedIterator
All Implemented Interfaces:
Closeable, AutoCloseable
final class BandedIterator extends WritablePixelIterator
A pixel iterator reading values directly from a DataBuffer instead of using Raster API. This iterator has the same behavior than the default implementation and is provided only for performance reasons. It can bring performance benefits when reading values as float or double values, but the benefits are more dubious for int values because Java2D has optimizations for that specific type.

This class assumes a BandedSampleModel or other models having an equivalently simple mapping from pixel coordinates to indices in banks. For other kinds of sample model, the default implementation should be used. More specifically assumptions are!

Since:
1.1
Version:
1.1

  • Field Details

    • buffer

      private DataBuffer buffer
      The buffer from where to read data. This is the buffer backing PixelIterator.currentRaster. It is the lowest-level object we can use before the plain Java array. We do not fetch the Java array because doing so may cause Java2D to disable GPU accelerations.

    • destBuffer

      private DataBuffer destBuffer
      The buffer where to write data, or null if none. May be the same instance than buffer.

    • sampleModelTranslateX

      private int sampleModelTranslateX
      The translation from SampleModel coordinates to Raster coordinates.

    • sampleModelTranslateY

      private int sampleModelTranslateY
      The translation from SampleModel coordinates to Raster coordinates.

    • xToBuffer

      private int xToBuffer
      The translation from Raster x coordinates to buffer indices. This is constant for a row and needs to be updated only when PixelIterator.y changed. Given buffer index computed by the following formula: 
      index = (y - sampleModelTranslateY) * scanlineStride + (x - sampleModelTranslateX)
      Then xToBuffer is above value with x = 0. This value may be negative.
      See Also:

    • scanlineStride

      private final int scanlineStride
      Number of buffer elements between a given sample and the corresponding sample in the same column of the next row. This value shall be the same for all tiles.

  • Constructor Details

    • BandedIterator

      BandedIterator(Raster input, WritableRaster output, Rectangle subArea, Dimension window, SequenceType order, int scanlineStride)
      Creates an iterator for the given region in the given raster.
      Parameters:
      input - the raster which contains the sample values to read.
      output - the raster where to write the sample values, or null for read-only iterator.
      subArea - the raster region where to perform the iteration, or null for iterating over all the raster domain.
      window - size of the window to use in PixelIterator.createWindow(TransferType) method, or null if none.
      order - null or SequenceType.LINEAR. Other values may be added in future versions.
      scanlineStride - value of getScanlineStride(input.getSampleModel(). Shall be greater than zero.

    • BandedIterator

      BandedIterator(RenderedImage input, WritableRenderedImage output, Rectangle subArea, Dimension window, SequenceType order, int scanlineStride)
      Creates an iterator for the given region in the given image.
      Parameters:
      input - the image which contains the sample values to read.
      output - the image where to write the sample values, or null for read-only iterator.
      subArea - the image region where to perform the iteration, or null for iterating over all the image domain.
      window - size of the window to use in PixelIterator.createWindow(TransferType) method, or null if none.
      order - null or SequenceType.LINEAR. Other values may be added in future versions.
      scanlineStride - value of getScanlineStride(input.getSampleModel(). Shall be greater than zero.

  • Method Details

    • changedRowOrTile

      final void changedRowOrTile()
      Recomputes xToBuffer for the new PixelIterator.y value. This method shall be invoked when the iterator moved to a new row, or when the iterator fetched a new tile but only after the (x,y) coordinates have been updated.
      Overrides:
      changedRowOrTile in class PixelIterator

    • moveTo

      public void moveTo(int px, int py)
      Moves the pixel iterator to the given column (x) and row (y) indices.
      Overrides:
      moveTo in class PixelIterator
      Parameters:
      px - the column index of the pixel to make current.
      py - the row index of the pixel to make current.
      Throws:
      IndexOutOfBoundsException - if the given indices are outside the iteration domain.

    • acquiredTile

      final void acquiredTile(Raster tile)
      Invoked when the iterator fetched a new tile. This method updates BandedIterator fields with raster properties, except xToBuffer which is not updated here because PixelIterator.y is not yet updated to its new value. BandedIterator must override all methods invoking PixelIterator.fetchTile() ane ensure that changedRowOrTile() is invoked after (x,y) have been updated.
      Overrides:
      acquiredTile in class PixelIterator
      Parameters:
      tile - the new tile from which to read sample values.

    • releaseTile

      final void releaseTile()
      Releases the buffer acquired by this iterator, if any. This is safety for avoiding accidental usage of wrong buffer. Also avoid to retain large array if the tile is garbage collected.
      Overrides:
      releaseTile in class WritablePixelIterator

    • getSample

      public int getSample(int band)
      Returns the sample value in the specified band of current pixel.
      Overrides:
      getSample in class PixelIterator
      Parameters:
      band - the band for which to get the sample value.
      Returns:
      sample value in specified band of current pixel.
      See Also:

    • getSampleFloat

      public float getSampleFloat(int band)
      Description copied from class: PixelIterator
      Returns the sample value in the specified band of current pixel as a single-precision floating point number. The PixelIterator.next() method must have returned true, or the PixelIterator.moveTo(int,int) method must have been invoked successfully, before this getSampleFloat(int) method is invoked. If above condition is not met, then this method behavior is undefined: it may throw any runtime exception or return a meaningless value (there is no explicit bounds check for performance reasons).
      Overrides:
      getSampleFloat in class PixelIterator
      Parameters:
      band - the band for which to get the sample value.
      Returns:
      sample value in specified band of current pixel.
      See Also:

    • getSampleDouble

      public double getSampleDouble(int band)
      Description copied from class: PixelIterator
      Returns the sample value in the specified band of current pixel, without precision lost. The PixelIterator.next() method must have returned true, or the PixelIterator.moveTo(int,int) method must have been invoked successfully, before this getSampleDouble(int) method is invoked. If above condition is not met, then this method behavior is undefined: it may throw any runtime exception or return a meaningless value (there is no explicit bounds check for performance reasons).
      Overrides:
      getSampleDouble in class PixelIterator
      Parameters:
      band - the band for which to get the sample value.
      Returns:
      sample value in specified band of current pixel.
      See Also:

    • setSample

      public void setSample(int band, int value)
      Description copied from class: WritablePixelIterator
      Writes a sample value in the specified band of current pixel. The PixelIterator.next() method must have returned true, or the PixelIterator.moveTo(int,int) method must have been invoked successfully, before this setSample(int, int) method is invoked. If above condition is not met, then this method behavior is undefined (there is no explicit bounds check for performance reasons).
      Overrides:
      setSample in class WritablePixelIterator
      Parameters:
      band - the band in which to set the sample value.
      value - the sample value to write in the specified band.
      See Also:

    • setSample

      public void setSample(int band, float value)
      Description copied from class: WritablePixelIterator
      Writes a sample value in the specified band of current pixel. The PixelIterator.next() method must have returned true, or the PixelIterator.moveTo(int,int) method must have been invoked successfully, before this setSample(int, float) method is invoked. If above condition is not met, then this method behavior is undefined (there is no explicit bounds check for performance reasons).
      Overrides:
      setSample in class WritablePixelIterator
      Parameters:
      band - the band in which to set the sample value.
      value - the sample value to write in the specified band.
      See Also:

    • setSample

      public void setSample(int band, double value)
      Description copied from class: WritablePixelIterator
      Writes a sample value in the specified band of current pixel. The PixelIterator.next() method must have returned true, or the PixelIterator.moveTo(int,int) method must have been invoked successfully, before this setSample(int, double) method is invoked. If above condition is not met, then this method behavior is undefined (there is no explicit bounds check for performance reasons).
      Overrides:
      setSample in class WritablePixelIterator
      Parameters:
      band - the band in which to set the sample value.
      value - the sample value to write in the specified band.
      See Also:

    • getPixel

      public int[] getPixel(int[] dest)
      Returns the sample values of current pixel for all bands. If the iterator is not in a valid position as documented in parent class, then this method behavior is undetermined: It may either throw an ArrayIndexOutOfBoundsException or return a random value.
      Overrides:
      getPixel in class PixelIterator
      Parameters:
      dest - a pre-allocated array where to store the sample values, or null if none.
      Returns:
      the sample values for current pixel.
      See Also:

    • getPixel

      public float[] getPixel(float[] dest)
      Returns the sample values of current pixel for all bands. If the iterator is not in a valid position as documented in parent class, then this method behavior is undetermined: It may either throw an ArrayIndexOutOfBoundsException or return a random value.
      Overrides:
      getPixel in class PixelIterator
      Parameters:
      dest - a pre-allocated array where to store the sample values, or null if none.
      Returns:
      the sample values for current pixel.
      See Also:

    • getPixel

      public double[] getPixel(double[] dest)
      Returns the sample values of current pixel for all bands. If the iterator is not in a valid position as documented in parent class, then this method behavior is undetermined: It may either throw an ArrayIndexOutOfBoundsException or return a random value.
      Overrides:
      getPixel in class PixelIterator
      Parameters:
      dest - a pre-allocated array where to store the sample values, or null if none.
      Returns:
      the sample values for current pixel.
      See Also:

    • setPixel

      public void setPixel(int[] values)
      Sets the sample values of current pixel for all bands. If the iterator is not in a valid position as documented in parent class, then this method behavior is undetermined: It may either throw an ArrayIndexOutOfBoundsException or return a random value.
      Overrides:
      setPixel in class WritablePixelIterator
      Parameters:
      values - the new sample values for current pixel.
      See Also:

    • setPixel

      public void setPixel(float[] values)
      Sets the sample values of current pixel for all bands. If the iterator is not in a valid position as documented in parent class, then this method behavior is undetermined: It may either throw an ArrayIndexOutOfBoundsException or return a random value.
      Overrides:
      setPixel in class WritablePixelIterator
      Parameters:
      values - the new sample values for current pixel.
      See Also:

    • setPixel

      public void setPixel(double[] values)
      Sets the sample values of current pixel for all bands. If the iterator is not in a valid position as documented in parent class, then this method behavior is undetermined: It may either throw an ArrayIndexOutOfBoundsException or return a random value.
      Overrides:
      setPixel in class WritablePixelIterator
      Parameters:
      values - the new sample values for current pixel.
      See Also:

    • createWindow

      PixelIterator.Window<FloatBuffer> createWindow(float[] data, float[] transfer)
      Creates a window for floating point values using the given arrays.
      Overrides:
      createWindow in class PixelIterator

    • createWindow

      PixelIterator.Window<DoubleBuffer> createWindow(double[] data, double[] transfer)
      Overrides:
      createWindow in class PixelIterator