Package org.apache.sis.image

Class WritablePixelIterator

java.lang.Object

org.apache.sis.image.PixelIterator

org.apache.sis.image.WritablePixelIterator

All Implemented Interfaces:

Closeable, AutoCloseable

Direct Known Subclasses:

BandedIterator

public class WritablePixelIterator
extends PixelIterator
implements Closeable

A pixel iterator capable to write sample values. This iterator can edit pixel values in place, or write values in a different destination image than the source image. Source and destination images must use the same sample model and the same coordinates (both for pixels and tiles).

Contrarily to PixelIterator, WritablePixelIterator needs to be closed after iteration in order to release tiles. Example:

Casting a PixelIterator

To check if a PixelIterator can be used for writing pixels, a … instanceof WritablePixelIterator check is not sufficient. The PixelIterator.isWritable() method should be invoked instead.

Since:

1.0

Version:

1.1

Nested Class Summary

Nested classes/interfaces inherited from class org.apache.sis.image.PixelIterator

PixelIterator.Builder, PixelIterator.Window<T extends Buffer>

Field Summary

Fields

Modifier and Type	Field	Description
private final WritableRenderedImage	destination	The image where pixels will be written, or null if the image is read-only.
private WritableRaster	destRaster	The current tile where pixels will be written, or null if no write operation is under way.

Fields inherited from class org.apache.sis.image.PixelIterator

image, lowerX, lowerY, numBands, tileX, tileY, upperX, upperY, x, y

Constructor Summary

Constructors

Constructor	Description
WritablePixelIterator(Raster input, WritableRaster output, Rectangle subArea, Dimension window, SequenceType order)	Creates an iterator for the given region in the given raster.
WritablePixelIterator(RenderedImage input, WritableRenderedImage output, Rectangle subArea, Dimension window, SequenceType order)	Creates an iterator for the given region in the given image.

Method Summary

Modifier and Type	Method	Description
void	close()	Releases any resources hold by this iterator.
static WritablePixelIterator	create(WritableRenderedImage data)	Creates an iterator for all pixels in the given image.
(package private) final WritableRaster	destination()	The current raster destination raster, or null if none.
(package private) final Raster	fetchWritableTile()	Invoked by PixelIterator.fetchTile() when iteration switch to a new tile.
boolean	isWritable()	Returns true if this iterator can write pixel values.
(package private) void	releaseTile()	Releases the tiles acquired by this iterator, if any.
void	setDataElements(Object values)	Sets the data elements (not necessarily band values) of current pixel.
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.PixelIterator

acquiredTile, changedRowOrTile, create, createWindow, createWindow, createWindow, fetchValues, getDataElements, getDataType, getDomain, getIterationOrder, getNumBands, getPixel, getPixel, getPixel, getPosition, getSample, getSampleDouble, getSampleFloat, getSampleRanges, getTransferType, isSameRowAndTile, moveTo, next, rewind

Methods inherited from class java.lang.Object

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

Field Details

destination

private final WritableRenderedImage destination

The image where pixels will be written, or null if the image is read-only. The destination image may or may not be the same instance than the source PixelIterator.image. However, the sample model, the minimal X and Y values and the tile grid must be the same.

destRaster

private WritableRaster destRaster

The current tile where pixels will be written, or null if no write operation is under way. It may or may not be the same instance than PixelIterator.currentRaster.

See Also:

• WritableRenderedImage.getWritableTile(int, int)
• WritableRenderedImage.releaseWritableTile(int, int)

Constructor Details

WritablePixelIterator

WritablePixelIterator(Raster input,
 WritableRaster output,
 Rectangle subArea,
 Dimension window,
 SequenceType order)

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.

WritablePixelIterator

WritablePixelIterator(RenderedImage input,
 WritableRenderedImage output,
 Rectangle subArea,
 Dimension window,
 SequenceType order)

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.

Method Details

create

public static WritablePixelIterator create(WritableRenderedImage data)

Creates an iterator for all pixels in the given image. This is a convenience method for new Builder().createWritable(data).

Parameters:

data - the image which contains the sample values on which to iterate.

Returns:

a new iterator traversing all pixels in the given image, in arbitrary order.

isWritable

public boolean isWritable()

Returns true if this iterator can write pixel values. For some implementations, being an instance of WritablePixelIterator is not sufficient for being able to write pixel values.

Note: all instances created by WritablePixelIterator.create(…) methods are guaranteed to true.

Overrides:

isWritable in class PixelIterator

Returns:

true if this iterator can be used for writing pixel values.

setSample

public void setSample(int band,
 int value)

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).

Parameters:

band - the band in which to set the sample value.

value - the sample value to write in the specified band.

See Also:

• WritableRaster.setSample(int, int, int, int)
• PixelIterator.getSample(int)

setSample

public void setSample(int band,
 float value)

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).

Parameters:

band - the band in which to set the sample value.

value - the sample value to write in the specified band.

See Also:

• WritableRaster.setSample(int, int, int, float)
• PixelIterator.getSampleFloat(int)

setSample

public void setSample(int band,
 double value)

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).

Parameters:

band - the band in which to set the sample value.

value - the sample value to write in the specified band.

See Also:

• WritableRaster.setSample(int, int, int, double)
• PixelIterator.getSampleDouble(int)

setPixel

public void setPixel(int[] values)

Sets the sample values of current pixel for all bands. The PixelIterator.next() method must have returned true, or the PixelIterator.moveTo(int,int) method must have been invoked successfully, before this setPixel(…) method is invoked. If above condition is not met, then this method behavior is undefined (there is no explicit bounds check for performance reasons).

Parameters:

values - the new sample values for current pixel.

See Also:

• WritableRaster.setPixel(int, int, int[])
• PixelIterator.getPixel(int[])

setPixel

public void setPixel(float[] values)

Sets the sample values of current pixel for all bands. The PixelIterator.next() method must have returned true, or the PixelIterator.moveTo(int,int) method must have been invoked successfully, before this setPixel(…) method is invoked. If above condition is not met, then this method behavior is undefined (there is no explicit bounds check for performance reasons).

Parameters:

values - the new sample values for current pixel.

See Also:

• WritableRaster.setPixel(int, int, float[])
• PixelIterator.getPixel(float[])

setPixel

public void setPixel(double[] values)

Sets the sample values of current pixel for all bands. The PixelIterator.next() method must have returned true, or the PixelIterator.moveTo(int,int) method must have been invoked successfully, before this setPixel(…) method is invoked. If above condition is not met, then this method behavior is undefined (there is no explicit bounds check for performance reasons).

Parameters:

values - the new sample values for current pixel.

See Also:

• WritableRaster.setPixel(int, int, double[])
• PixelIterator.getPixel(double[])

setDataElements

public void setDataElements(Object values)

Sets the data elements (not necessarily band values) of current pixel. The Object argument is a relatively opaque format (it may be int[], byte[], etc.). It should be the value provided by a call to PixelIterator.getDataElements(Object) on an image using a compatible sample model.

Parameters:

values - the new the data elements.

Since:

1.1

See Also:

• WritableRaster.setDataElements(int, int, Object)
• PixelIterator.getDataElements(Object)

destination

final WritableRaster destination()

The current raster destination raster, or null if none.

fetchWritableTile

final Raster fetchWritableTile()

Invoked by PixelIterator.fetchTile() when iteration switch to a new tile.

Overrides:

fetchWritableTile in class PixelIterator

Returns:

if the new writable tile can also be used for reading, that tile. Otherwise null.

releaseTile

void releaseTile()

Releases the tiles acquired by this iterator, if any. This method does nothing if the iterator is read-only.

Overrides:

releaseTile in class PixelIterator

close

public void close()

Releases any resources hold by this iterator. If some pixel values have been written, the changes are committed.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable