Package org.apache.sis.coverage.grid

## Class ImageRenderer

- Object
- - ImageRenderer

-     public class ImageRenderer
      extends Object

  A builder for the rendered image to be returned by `GridCoverage​.render(GridExtent)`. This builder does not copy any sample values. Instead, it wraps existing data arrays into `Raster` objects by computing required information such as pixel stride, scanline stride and band offsets. Different `setData(…)` methods are provided for allowing to specify the data arrays from different objects such as Java2D `DataBuffer` or NIO `Buffer`.

  All `setData(…)` methods assume that the first valid element in each array is the value located at `GridCoverage​.getGridGeometry().getExtent().getLow()`. This `ImageRenderer` class computes automatically the offsets from that position to the position of the first value included in the `sliceExtent` given to the constructor.

  Usage example:

  >     class MyResource extends GridCoverage {
  >         @Override
  >         public RenderedImage render(GridExtent sliceExtent) {
  >             try {
  >                 ImageRenderer renderer = new ImageRenderer(this, sliceExtent);
  >                 renderer.setData(data);
  >                 return renderer.image();
  >             } catch (IllegalArgumentException | ArithmeticException | RasterFormatException e) {
  >                 throw new CannotEvaluateException("Can not create an image.", e);
  >             }
  >         }
  >     }

  Limitations
  Current implementation constructs only images made of a single tile. Support for tiled images will be added in a future version.
  Since:
    1.0
  See Also:
    `GridCoverage​.render(GridExtent)`

  Defined in the `sis-feature` module

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `ImageRenderer​(GridCoverage coverage, GridExtent sliceExtent)` | Creates a new image renderer for the given slice extent.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `Rectangle` | `getBounds()` | Returns the location of the image upper-left corner together with the image size.
    `int` | `getNumBands()` | Returns the number of bands that the image will have.
    `RenderedImage` | `image()` | Creates an image with the data specified by the last call to a `setData(…)` method.
    `WritableRaster` | `raster()` | Creates a raster with the data specified by the last call to a `setData(…)` method.
    `void` | `setData​(int dataType, Buffer... data)` | Sets the data as NIO buffers.
    `void` | `setData​(DataBuffer data)` | Sets the data as a Java2D buffer.
    `void` | `setData​(Vector... data)` | Sets the data as vectors.
    `void` | `setInterleavedPixelOffsets​(int pixelStride, int[] bandOffsets)` | Specifies the offsets to add to sample index in each band in order to reach the sample value in the `DataBuffer` bank.

    - ### Methods inherited from class Object

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

- - ### Constructor Detail

    - #### ImageRenderer

          public ImageRenderer​(GridCoverage coverage,
                               GridExtent sliceExtent)

      Creates a new image renderer for the given slice extent.
      Parameters:
        `coverage` - the grid coverage for which to build an image.
        `sliceExtent` - the grid geometry from which to create an image, or `null` for the `coverage` extent.
      Throws:
        `SubspaceNotSpecifiedException` - if this method can not infer a two-dimensional slice from `sliceExtent`.
        `DisjointExtentException` - if the given extent does not intersect this grid coverage.
        `ArithmeticException` - if a stride calculation overflows the 32 bits integer capacity.

  - ### Method Detail

    - #### getNumBands

          public final int getNumBands()

      Returns the number of bands that the image will have. By default, this is the number of sample dimensions in the grid coverage.
      Returns:
        the number of bands in the rendered image.

    - #### getBounds

          public final Rectangle getBounds()

      Returns the location of the image upper-left corner together with the image size.
      Returns:
        the rendered image location and size (never null).

    - #### setData

          public void setData​(DataBuffer data)

      Sets the data as a Java2D buffer. The number of banks in the given buffer must be equal to the expected number of bands. In each bank, the value located at the bank offset is the value located at `GridCoverage​.getGridGeometry().getExtent().getLow()`, as specified in class javadoc.
      Parameters:
        `data` - the Java2D buffer containing data for all bands.
      Throws:
        `NullArgumentException` - if `data` is null.
        `MismatchedCoverageRangeException` - if the given data buffer does not have the expected amount of banks.

    - #### setData

          public void setData​(int dataType,
                              Buffer... data)

      Sets the data as NIO buffers. The number of buffers must be equal to the expected number of bands. All buffers must be backed by arrays of the type specified by the `dataType` argument and have the same amount of remaining elements. This method wraps the underlying arrays of a primitive type into a Java2D buffer; data are not copied. For each buffer, the grid coverage data (not only the slice data) starts at buffer position and ends at that position + remaining.

      The data type must be specified in order to distinguish between the signed and unsigned types. `DataBuffer​.TYPE_BYTE` and `DataBuffer​.TYPE_USHORT` are unsigned, all other supported types are signed.

      Implementation note: the Java2D buffer is set by a call to `setData(DataBuffer)`, which can be overridden by subclasses if desired.

      Parameters:
        `dataType` - type of data as one of `DataBuffer​.TYPE_BYTE`, `TYPE_SHORT` `TYPE_USHORT`, `TYPE_INT`, `TYPE_FLOAT` or `TYPE_DOUBLE` constants.
        `data` - the buffers wrapping arrays of primitive type.
      Throws:
        `NullArgumentException` - if `data` is null or one of `data` element is null.
        `IllegalArgumentException` - if `dataType` is not a supported value.
        `MismatchedCoverageRangeException` - if the number of specified buffers is not equal to the number of bands.
        `UnsupportedOperationException` - if a buffer is not backed by an accessible array or is read-only.
        `ArrayStoreException` - if a buffer type is incompatible with `dataType`.
        `RasterFormatException` - if buffers do not have the same amount of remaining values.
        `ArithmeticException` - if a buffer position overflows the 32 bits integer capacity.

    - #### setData

          public void setData​(Vector... data)

      Sets the data as vectors. The number of vectors must be equal to the expected number of bands. All vectors must be backed by arrays (indirectly, through buffers backed by arrays) and have the same size. This method wraps the underlying arrays of a primitive type into a Java2D buffer; data are not copied.

      Implementation note: the NIO buffers are set by a call to `setData(int, Buffer...)`, which can be overridden by subclasses if desired.

      Parameters:
        `data` - the vectors wrapping arrays of primitive type.
      Throws:
        `NullArgumentException` - if `data` is null or one of `data` element is null.
        `MismatchedCoverageRangeException` - if the number of specified vectors is not equal to the number of bands.
        `UnsupportedOperationException` - if a vector is not backed by an accessible array or is read-only.
        `RasterFormatException` - if vectors do not have the same size.
        `ArithmeticException` - if a buffer position overflows the 32 bits integer capacity.

    - #### setInterleavedPixelOffsets

          public void setInterleavedPixelOffsets​(int pixelStride,
                                                 int[] bandOffsets)

      Specifies the offsets to add to sample index in each band in order to reach the sample value in the `DataBuffer` bank. This method should be invoked when the data given to `setData(…)` contains only one `Vector`, `Buffer` or `DataBuffer` bank, and the bands in that unique bank are interleaved.
      Example: for an image having three bands named Red (R), Green (G) and Blue (B), if the sample values are stored in a single bank in a R₀,G₀,B₀, R₁,G₁,B₁, R₂,G₂,B₂, R₃,G₃,B₃, etc. fashion, then this method should be invoked as below:

      >     setInterleavedPixelOffsets(3, new int[] {0, 1, 2});

      Parameters:
        `pixelStride` - the number of data elements between each pixel in the data vector or buffer.
        `bandOffsets` - offsets to add to sample index in each band. This is typically {0, 1, 2, …}. The length of this array shall be equal to `getNumBands()`.

    - #### raster

          public WritableRaster raster()

      Creates a raster with the data specified by the last call to a `setData(…)` method. The raster upper-left corner is located at the position given by `getBounds()`.
      Returns:
        the raster.
      Throws:
        `IllegalStateException` - if no `setData(…)` method has been invoked before this method call.
        `RasterFormatException` - if a call to a `WritableRaster` factory method failed.
        `ArithmeticException` - if a property of the raster to construct exceeds the capacity of 32 bits integers.

    - #### image

          public RenderedImage image()

      Creates an image with the data specified by the last call to a `setData(…)` method. The image upper-left corner is located at the position given by `getBounds()`.
      Returns:
        the image.
      Throws:
        `IllegalStateException` - if no `setData(…)` method has been invoked before this method call.
        `RasterFormatException` - if a call to a `WritableRaster` factory method failed.
        `ArithmeticException` - if a property of the image to construct exceeds the capacity of 32 bits integers.