Package org.apache.sis.image

## Class WritablePixelIterator

- Object
- - PixelIterator
  - - WritablePixelIterator

- All Implemented Interfaces:
    `Closeable`, `AutoCloseable`

      public abstract 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

  Defined in the `sis-feature` module

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class PixelIterator

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

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `abstract 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.
    `abstract void` | `setPixel​(double[] values)` | Sets the sample values of current pixel for all bands.
    `abstract void` | `setPixel​(float[] values)` | Sets the sample values of current pixel for all bands.
    `abstract void` | `setPixel​(int[] values)` | Sets the sample values of current pixel for all bands.
    `abstract void` | `setSample​(int band, double value)` | Writes a sample value in the specified band of current pixel.
    `abstract void` | `setSample​(int band, float value)` | Writes a sample value in the specified band of current pixel.
    `abstract void` | `setSample​(int band, int value)` | Writes a sample value in the specified band of current pixel.

    - ### Methods inherited from class PixelIterator

      `create, createWindow, getDomain, 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 Detail

    - #### 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 abstract 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 abstract 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 abstract 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 abstract 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 abstract 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 abstract 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[])`

    - #### close

          public abstract void close()

      Releases any resources hold by this iterator. Invoking this method may flush some tiles content to disk.
      Specified by:
        `close` in interface `AutoCloseable`
      Specified by:
        `close` in interface `Closeable`