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
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!
- One sample value per band, or (equivalently) only one band.
- Pixel stride equals to 1.
- Bank indices are the 0, 1, 2, … sequence.
- Band offsets are all zero.
- Since:
- 1.1
- Version:
- 1.1
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprivate final class
PixelIterator.Window
implementation backed by an array ofdouble[]
.private final class
PixelIterator.Window
implementation backed by an array offloat[]
.Nested classes/interfaces inherited from class org.apache.sis.image.PixelIterator
PixelIterator.Builder, PixelIterator.Window<T extends Buffer>
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate DataBuffer
The buffer from where to read data.private DataBuffer
The buffer where to write data, ornull
if none.private int
The translation fromSampleModel
coordinates toRaster
coordinates.private int
The translation fromSampleModel
coordinates toRaster
coordinates.private final int
Number of buffer elements between a given sample and the corresponding sample in the same column of the next row.private int
-
Constructor Summary
ConstructorsConstructorDescriptionBandedIterator
(Raster input, WritableRaster output, Rectangle subArea, Dimension window, SequenceType order, int scanlineStride) Creates an iterator for the given region in the given raster.BandedIterator
(RenderedImage input, WritableRenderedImage output, Rectangle subArea, Dimension window, SequenceType order, int scanlineStride) Creates an iterator for the given region in the given image. -
Method Summary
Modifier and TypeMethodDescription(package private) final void
acquiredTile
(Raster tile) Invoked when the iterator fetched a new tile.(package private) final void
RecomputesxToBuffer
for the newPixelIterator.y
value.(package private) PixelIterator.Window<DoubleBuffer>
createWindow
(double[] data, double[] transfer) (package private) PixelIterator.Window<FloatBuffer>
createWindow
(float[] data, float[] transfer) Creates a window for floating point values using the given arrays.double[]
getPixel
(double[] dest) Returns the sample values of current pixel for all bands.float[]
getPixel
(float[] dest) Returns the sample values of current pixel for all bands.int[]
getPixel
(int[] dest) Returns the sample values of current pixel for all bands.int
getSample
(int band) Returns the sample value in the specified band of current pixel.double
getSampleDouble
(int band) Returns the sample value in the specified band of current pixel, without precision lost.float
getSampleFloat
(int band) Returns the sample value in the specified band of current pixel as a single-precision floating point number.void
moveTo
(int px, int py) Moves the pixel iterator to the given column (x) and row (y) indices.(package private) final void
Releases the buffer acquired by this iterator, if any.void
setPixel
(double[] values) Sets the sample values of current pixel for all bands.void
setPixel
(float[] values) Sets the sample values of current pixel for all bands.void
setPixel
(int[] values) Sets the sample values of current pixel for all bands.void
setSample
(int band, double value) Writes a sample value in the specified band of current pixel.void
setSample
(int band, float value) Writes a sample value in the specified band of current pixel.void
setSample
(int band, int value) Writes a sample value in the specified band of current pixel.Methods inherited from class org.apache.sis.image.WritablePixelIterator
close, create, destination, fetchWritableTile, isWritable, setDataElements
Methods inherited from class org.apache.sis.image.PixelIterator
create, createWindow, fetchValues, getDataElements, getDataType, getDomain, getIterationOrder, getNumBands, getPosition, getSampleRanges, getTransferType, isSameRowAndTile, next, rewind
-
Field Details
-
buffer
The buffer from where to read data. This is the buffer backingPixelIterator.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
The buffer where to write data, ornull
if none. May be the same instance thanbuffer
. -
sampleModelTranslateX
private int sampleModelTranslateXThe translation fromSampleModel
coordinates toRaster
coordinates. -
sampleModelTranslateY
private int sampleModelTranslateYThe translation fromSampleModel
coordinates toRaster
coordinates. -
xToBuffer
private int xToBufferThe translation fromRaster
x coordinates tobuffer
indices. This is constant for a row and needs to be updated only whenPixelIterator.y
changed. Given buffer index computed by the following formula:index = (y - sampleModelTranslateY) * scanlineStride + (x - sampleModelTranslateX)
ThenxToBuffer
is above value with x = 0. This value may be negative.- See Also:
-
scanlineStride
private final int scanlineStrideNumber 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, ornull
for read-only iterator.subArea
- the raster region where to perform the iteration, ornull
for iterating over all the raster domain.window
- size of the window to use inPixelIterator.createWindow(TransferType)
method, ornull
if none.order
-null
orSequenceType.LINEAR
. Other values may be added in future versions.scanlineStride
- value ofgetScanlineStride(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, ornull
for read-only iterator.subArea
- the image region where to perform the iteration, ornull
for iterating over all the image domain.window
- size of the window to use inPixelIterator.createWindow(TransferType)
method, ornull
if none.order
-null
orSequenceType.LINEAR
. Other values may be added in future versions.scanlineStride
- value ofgetScanlineStride(input.getSampleModel()
. Shall be greater than zero.
-
-
Method Details
-
changedRowOrTile
final void changedRowOrTile()RecomputesxToBuffer
for the newPixelIterator.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 classPixelIterator
-
moveTo
public void moveTo(int px, int py) Moves the pixel iterator to the given column (x) and row (y) indices.- Overrides:
moveTo
in classPixelIterator
- 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
Invoked when the iterator fetched a new tile. This method updatesBandedIterator
fields with raster properties, exceptxToBuffer
which is not updated here becausePixelIterator.y
is not yet updated to its new value.BandedIterator
must override all methods invokingPixelIterator.fetchTile()
ane ensure thatchangedRowOrTile()
is invoked after (x,y) have been updated.- Overrides:
acquiredTile
in classPixelIterator
- 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 classWritablePixelIterator
-
getSample
public int getSample(int band) Returns the sample value in the specified band of current pixel.- Overrides:
getSample
in classPixelIterator
- 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. ThePixelIterator.next()
method must have returnedtrue
, or thePixelIterator.moveTo(int,int)
method must have been invoked successfully, before thisgetSampleFloat(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 classPixelIterator
- 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. ThePixelIterator.next()
method must have returnedtrue
, or thePixelIterator.moveTo(int,int)
method must have been invoked successfully, before thisgetSampleDouble(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 classPixelIterator
- 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. ThePixelIterator.next()
method must have returnedtrue
, or thePixelIterator.moveTo(int,int)
method must have been invoked successfully, before thissetSample(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 classWritablePixelIterator
- 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. ThePixelIterator.next()
method must have returnedtrue
, or thePixelIterator.moveTo(int,int)
method must have been invoked successfully, before thissetSample(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 classWritablePixelIterator
- 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. ThePixelIterator.next()
method must have returnedtrue
, or thePixelIterator.moveTo(int,int)
method must have been invoked successfully, before thissetSample(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 classWritablePixelIterator
- 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 anArrayIndexOutOfBoundsException
or return a random value.- Overrides:
getPixel
in classPixelIterator
- Parameters:
dest
- a pre-allocated array where to store the sample values, ornull
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 anArrayIndexOutOfBoundsException
or return a random value.- Overrides:
getPixel
in classPixelIterator
- Parameters:
dest
- a pre-allocated array where to store the sample values, ornull
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 anArrayIndexOutOfBoundsException
or return a random value.- Overrides:
getPixel
in classPixelIterator
- Parameters:
dest
- a pre-allocated array where to store the sample values, ornull
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 anArrayIndexOutOfBoundsException
or return a random value.- Overrides:
setPixel
in classWritablePixelIterator
- 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 anArrayIndexOutOfBoundsException
or return a random value.- Overrides:
setPixel
in classWritablePixelIterator
- 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 anArrayIndexOutOfBoundsException
or return a random value.- Overrides:
setPixel
in classWritablePixelIterator
- Parameters:
values
- the new sample values for current pixel.- See Also:
-
createWindow
Creates a window for floating point values using the given arrays.- Overrides:
createWindow
in classPixelIterator
-
createWindow
- Overrides:
createWindow
in classPixelIterator
-