Module org.apache.sis.feature
Package org.apache.sis.image

# Class WritablePixelIterator

Object
PixelIterator
WritablePixelIterator

All Implemented Interfaces:
  `Closeable`, `AutoCloseable`

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:

    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 `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

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from class PixelIterator

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

- ## 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.
  `boolean`
  `isWritable()`
  Returns `true` if this iterator can write pixel values.
  `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 PixelIterator

  `create, createWindow, getDataElements, getDataType, getDomain, getIterationOrder, getNumBands, getPixel, getPixel, getPixel, getPosition, getSample, getSampleDouble, getSampleFloat, getSampleRanges, getTransferType, moveTo, next, rewind`

  ### Methods inherited from class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, 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()​.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)`

  - ### 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`