Class WritablePixelIterator

Object

PixelIterator

WritablePixelIterator

All Implemented Interfaces:

Closeable, Auto­Closeable

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

Contrary to Pixel­Iterator, Writable­Pixel­Iterator needs to be closed after iteration in order to release tiles. Example:

try (WritablePixelIterator it = WritablePixelIterator.create(image)) {
    double[] samples = null;
    while (it.next()) {
        samples = it.getPixel(samples);      // Get values in all bands.
        // Perform computation here...
        it.setPixels(sample);                // Replace values in all bands.
    }
}

Casting a Pixel­Iterator

To check if a Pixel­Iterator can be used for writing pixels, a … instanceof Writable­Pixel­Iterator check is not sufficient. The Pixel­Iterator.is­Writable() method should be invoked instead.

Since:

1.0

Nested Class Summary

Nested classes/interfaces inherited from class PixelIterator

Pixel­Iterator.Builder, Pixel­Iterator.Window<T>

Modifier and Type	Class	Description
static class	Pixel­Iterator.Builder	Builds pixel iterators for specified region of interest, window size or iteration order.
static class	Pixel­Iterator.Window<T extends Buffer>	Contains the sample values in a moving window over the image.

Method Summary

Modifier and Type	Method	Description
void	close()	Releases any resources hold by this iterator.
static Writable­Pixel­Iterator	create(Writable­Rendered­Image data)	Creates an iterator for all pixels in the given image.
boolean	is­Writable()	Returns true if this iterator can write pixel values.
void	set­Data­Elements(Object values)	Sets the data elements (not necessarily band values) of current pixel.
void	set­Pixel(double[] values)	Sets the sample values of current pixel for all bands.
void	set­Pixel(float[] values)	Sets the sample values of current pixel for all bands.
void	set­Pixel(int[] values)	Sets the sample values of current pixel for all bands.
void	set­Remaining­Pixels(Double­Binary­Operator[] bands)	Sets all remaining pixels to floating-point values computed by the given functions.
void	set­Remaining­Pixels(Int­Binary­Operator[] bands)	Sets all remaining pixels to integer values computed by the given functions.
void	set­Sample(int band, double value)	Writes a sample value in the specified band of current pixel.
void	set­Sample(int band, float value)	Writes a sample value in the specified band of current pixel.
void	set­Sample(int band, int value)	Writes a sample value in the specified band of current pixel.

Methods inherited from class PixelIterator

create, create­Window, get­Data­Elements, get­Data­Type, get­Domain, get­Iteration­Order, get­Num­Bands, get­Pixel, get­Pixel, get­Pixel, get­Position, get­Sample, get­Sample­Double, get­Sample­Float, get­Sample­Ranges, get­Transfer­Type, move­To, next, rewind

Modifier and Type	Method	Description
static Pixel­Iterator	create(Rendered­Image data)	Creates an iterator for all pixels in the given image.
<T extends Buffer> Pixel­Iterator.Window<T>	create­Window(Transfer­Type<T> type)	Returns a moving window over the sample values in a rectangular region starting at iterator position.
Object	get­Data­Elements(Object dest)	Returns the data elements (not necessarily band values) of current pixel.
Data­Type	get­Data­Type()	Returns the type of sample values.
Rectangle	get­Domain()	Returns the pixel coordinates of the region where this iterator is doing the iteration.
Optional<Sequence­Type>	get­Iteration­Order()	Returns the order in which pixels are traversed.
int	get­Num­Bands()	Returns the number of bands (samples per pixel) in the image or raster.
double[]	get­Pixel(double[] dest)	Returns the sample values of current pixel for all bands.
float[]	get­Pixel(float[] dest)	Returns the sample values of current pixel for all bands.
int[]	get­Pixel(int[] dest)	Returns the sample values of current pixel for all bands.
Point	get­Position()	Returns the column (x) and row (y) indices of the current pixel.
int	get­Sample(int band)	Returns the sample value in the specified band of current pixel, rounded toward zero.
double	get­Sample­Double(int band)	Returns the sample value in the specified band of current pixel, without precision lost.
float	get­Sample­Float(int band)	Returns the sample value in the specified band of current pixel as a single-precision floating point number.
Number­Range<?>[]	get­Sample­Ranges()	Returns the range of sample values that can be stored in each band of the rendered image or raster.
Transfer­Type<?>	get­Transfer­Type()	Returns the most efficient type (int, float or double) for transferring data between the underlying rasters and this iterator.
void	move­To(int px, int py)	Moves the pixel iterator to the given column (x) and row (y) indices.
boolean	next()	Moves the iterator to the next pixel.
void	rewind()	Restores the iterator to the start position.

Methods inherited from class Object

clone, equals, finalize, get­Class, hash­Code, notify, notify­All, to­String, wait, wait, wait

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().create­Writable(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 Writable­Pixel­Iterator is not sufficient for being able to write pixel values.

Note: all instances created by Writable­Pixel­Iterator.create(…) methods are guaranteed to true.

Overrides:

is­Writable in class Pixel­Iterator

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 Pixel­Iterator.next() method must have returned true, or the Pixel­Iterator.move­To(int,int) method must have been invoked successfully, before this set­Sample(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:

• Writable­Raster.set­Sample(int, int, int, int)
• Pixel­Iterator.get­Sample(int)

setSample

public void setSample(int band,
 float value)

Writes a sample value in the specified band of current pixel. The Pixel­Iterator.next() method must have returned true, or the Pixel­Iterator.move­To(int,int) method must have been invoked successfully, before this set­Sample(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:

• Writable­Raster.set­Sample(int, int, int, float)
• Pixel­Iterator.get­Sample­Float(int)

setSample

public void setSample(int band,
 double value)

Writes a sample value in the specified band of current pixel. The Pixel­Iterator.next() method must have returned true, or the Pixel­Iterator.move­To(int,int) method must have been invoked successfully, before this set­Sample(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:

• Writable­Raster.set­Sample(int, int, int, double)
• Pixel­Iterator.get­Sample­Double(int)

setPixel

public void setPixel(int[] values)

Sets the sample values of current pixel for all bands. The Pixel­Iterator.next() method must have returned true, or the Pixel­Iterator.move­To(int,int) method must have been invoked successfully, before this set­Pixel(…) 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:

• Writable­Raster.set­Pixel(int, int, int[])
• Pixel­Iterator.get­Pixel(int[])

setPixel

public void setPixel(float[] values)

Sets the sample values of current pixel for all bands. The Pixel­Iterator.next() method must have returned true, or the Pixel­Iterator.move­To(int,int) method must have been invoked successfully, before this set­Pixel(…) 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:

• Writable­Raster.set­Pixel(int, int, float[])
• Pixel­Iterator.get­Pixel(float[])

setPixel

public void setPixel(double[] values)

Sets the sample values of current pixel for all bands. The Pixel­Iterator.next() method must have returned true, or the Pixel­Iterator.move­To(int,int) method must have been invoked successfully, before this set­Pixel(…) 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:

• Writable­Raster.set­Pixel(int, int, double[])
• Pixel­Iterator.get­Pixel(double[])

setRemainingPixels

public void setRemainingPixels(IntBinaryOperator[] bands)

Sets all remaining pixels to integer values computed by the given functions. Each function will receive pixel coordinates (x, y) and shall return the sample value to store in one band of the image at that pixel position. The functions shall be given in the same order as the bands. Therefore, the function at index i computes the sample values of band i.

Parameters:

bands - functions providing sample values in each band, in order.

Throws:

Illegal­Argument­Exception - if the number of functions is not equal to the number of bands.

Since:

1.7

setRemainingPixels

public void setRemainingPixels(DoubleBinaryOperator[] bands)

Sets all remaining pixels to floating-point values computed by the given functions. Each function will receive pixel coordinates (x, y) and shall return the sample value to store in one band of the image at that pixel position. The functions shall be given in the same order as the bands. Therefore, the function at index i computes the sample values of band i.

Parameters:

bands - functions providing sample values in each band, in order.

Throws:

Illegal­Argument­Exception - if the number of functions is not equal to the number of bands.

Since:

1.7

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 Pixel­Iterator.get­Data­Elements(Object) on an image using a compatible sample model.

Parameters:

values - the new the data elements.

Since:

1.1

See Also:

• Writable­Raster.set­Data­Elements(int, int, Object)
• Pixel­Iterator.get­Data­Elements(Object)

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 Auto­Closeable

Specified by:

close in interface Closeable