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

# Class ResampledImage

Object
PlanarImage
ComputedImage
ResampledImage

All Implemented Interfaces:
  `RenderedImage`, `Disposable`

public class ResampledImage extends ComputedImage
An image which is the result of resampling the pixel values of another image. Resampling is the action of computing pixel values at possibly non-integral positions of a source image. It can be used for projecting an image to another coordinate reference system, for example from (latitude, longitude) to World Mercator. The resampling is defined by a non-linear `MathTransform` (for example a map projection) which converts pixel center coordinates from this image to pixel center coordinates in the source image. The converted coordinates usually contain fraction digits, in which case an interpolation is applied.

## Usage note

This class should be used with non-linear transforms such as map projections. It is technically possible to use this class with linear transforms such as `AffineTransform`, but there is more efficient alternatives for linear cases (for example specifying the affine transform at rendering time).

Since:
  1.1
See Also:
  - `Interpolation`
  - `AffineTransformOp`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected final Interpolation`
  `interpolation`
  The object to use for performing interpolations.
  `static final String`
  `POSITIONAL_CONSISTENCY_KEY`
  Key of a property providing an estimation of positional error for each pixel.
  `protected final MathTransform`
  `toSource`
  Conversion from pixel center coordinates of this image to pixel center coordinates of source image.

  ### Fields inherited from class ComputedImage

  `sampleModel, SOURCE_PADDING_KEY`

  ### Fields inherited from class PlanarImage

  `GRID_GEOMETRY_KEY, MASK_KEY, POSITIONAL_ACCURACY_KEY, SAMPLE_DIMENSIONS_KEY, SAMPLE_RESOLUTIONS_KEY, STATISTICS_KEY`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `ResampledImage(RenderedImage source, SampleModel sampleModel, Point minTile, Rectangle bounds, MathTransform toSource, Interpolation interpolation, Number[] fillValues, Quantity<?>[] accuracy)`
  Creates a new image which will resample the given image.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected Raster`
  `computeTile(int tileX, int tileY, WritableRaster tile)`
  Invoked when a tile need to be computed or updated.
  `boolean`
  `equals(Object object)`
  Compares the given object with this image for equality.
  `ColorModel`
  `getColorModel()`
  Returns the color model of this resampled image.
  `final int`
  `getHeight()`
  Returns the number of rows in this image.
  `final int`
  `getMinTileX()`
  Returns the minimum tile index in the x direction.
  `final int`
  `getMinTileY()`
  Returns the minimum tile index in the y direction.
  `final int`
  `getMinX()`
  Returns the minimum x coordinate (inclusive) of this image.
  `final int`
  `getMinY()`
  Returns the minimum y coordinate (inclusive) of this image.
  `Object`
  `getProperty(String key)`
  Gets a property from this image.
  `String[]`
  `getPropertyNames()`
  Returns the names of all recognized properties, or `null` if this image has no properties.
  `final int`
  `getWidth()`
  Returns the number of columns in this image.
  `int`
  `hashCode()`
  Returns a hash code value for this image.
  `protected Disposable`
  `prefetch(Rectangle tiles)`
  Notifies the source image that tiles will be computed soon in the given region.
  `String`
  `verify()`
  Verifies whether image layout information are consistent.

  ### Methods inherited from class ComputedImage

  `clearErrorFlags, createTile, dispose, getSampleModel, getSource, getSources, getTile, getTileHeight, getTileWidth, getWritableTileIndices, hasTileWriters, isTileWritable, markDirtyTiles, markTileWritable, sourceTileChanged`

  ### Methods inherited from class PlanarImage

  `copyData, getBounds, getData, getData, getNumXTiles, getNumYTiles, getTileGridXOffset, getTileGridYOffset, toString`

  ### Methods inherited from class Object

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- ## Field Details

  - ### POSITIONAL_CONSISTENCY_KEY

    public static final String POSITIONAL_CONSISTENCY_KEY
    Key of a property providing an estimation of positional error for each pixel. Values shall be instances of `RenderedImage` with same size and origin than this image. The image should contain a single band where all sample values are error estimations in pixel units (relative to pixels of this image). The value should be small, for example between 0 and 0.2.

    The default implementation transforms all pixel coordinates to source, then convert them back to pixel coordinates in this image. The result is compared with expected coordinates and the distance is stored in the image.

    See Also:
      - `PlanarImage​.POSITIONAL_ACCURACY_KEY`
      - Constant Field Values

  - ### toSource

    protected final MathTransform toSource
    Conversion from pixel center coordinates of this image to pixel center coordinates of source image. This transform should be an instance of `MathTransform2D`, but this is not required by this class (a future version may allow interpolations in a n-dimensional cube).
    See Also:
      - `PixelInCell​.CELL_CENTER`

  - ### interpolation

    protected final Interpolation interpolation
    The object to use for performing interpolations.

- ## Constructor Details

  - ### ResampledImage

    protected ResampledImage(RenderedImage source, SampleModel sampleModel, Point minTile, Rectangle bounds, MathTransform toSource, Interpolation interpolation, Number[] fillValues, Quantity<?>[] accuracy)
    Creates a new image which will resample the given image. The resampling operation is defined by a potentially non-linear transform from this image to the specified source image. That transform should map pixel centers.

    The `sampleModel` determines the tile size and the target data type. This is often the same sample model than the one used by the `source` image, but may also be different for forcing a different tile size or a different data type (e.g. `byte` versus `float`) for storing resampled values. If the specified sample model is not the same than the one used by the source image, then subclass should override `getColorModel()` for returning a color model which is compatible with the sample model.

    If a pixel in this image cannot be mapped to a pixel in the source image, then the sample values are set to `fillValues`. If the given array is `null`, or if any element in the given array is `null`, then the default fill value is NaN for floating point data types or zero for integer data types. If the array is shorter than the number of bands, then above-cited default values are used for missing values. If longer than the number of bands, extraneous values are ignored.

    Parameters:
      `source` - the image to be resampled.
      `sampleModel` - the sample model shared by all tiles in this resampled image.
      `minTile` - indices of the first tile (`minTileX`, `minTileY`), or `null` for (0,0).
      `bounds` - domain of pixel coordinates of this resampled image.
      `toSource` - conversion of pixel coordinates of this image to pixel coordinates of `source` image.
      `interpolation` - the object to use for performing interpolations.
      `fillValues` - the values to use for pixels in this image that cannot be mapped to pixels in source image. May be `null` or contain `null` elements, and may have any length (see above for more details).
      `accuracy` - values of "org.apache.sis.PositionalAccuracy" property, or `null` if none. This constructor may retain only a subset of specified values or replace some of them. If an accuracy is specified in pixel units, then a value such as 0.125 pixel may enable the use of a slightly faster algorithm at the expense of accuracy. This is only a hint honored on a best-effort basis.
    See Also:
      - `ImageProcessor​.resample(RenderedImage, Rectangle, MathTransform)`

- ## Method Details

  - ### verify

    public String verify()
    Verifies whether image layout information are consistent. This method verifies that source coordinates required by this image (computed by converting this image bounds using the `toSource` transform) intersects the bounds of the source image. If this is not the case, then this method returns `"toSource"` for signaling that the transform may have a problem. Otherwise this method completes the check with all verifications documented in parent class
    Overrides:
      `verify` in class `PlanarImage`
    Returns:
      `null` if image layout information are consistent, or the name of inconsistent attribute if a problem is found.

  - ### getColorModel

    public ColorModel getColorModel()
    Returns the color model of this resampled image. Default implementation assumes that this image has the same color model than the source image.
    Returns:
      the color model, or `null` if unspecified.

  - ### getProperty

    public Object getProperty(String key)
    Gets a property from this image. Current default implementation supports the following keys (more properties may be added to this list in any future Apache SIS versions):
    - "org.apache.sis.PositionalAccuracy"
    - "org.apache.sis.PositionalConsistency"
    - "org.apache.sis.SampleDimensions" (forwarded to the source image)
    - "org.apache.sis.SampleResolutions" (forwarded to the source image)
    - "org.apache.sis.Mask" if the image uses floating point numbers.

    #### Note on sample values

    The sample resolutions are retained because they should have approximately the same values before and after resampling. Statistics are not in this list because, while minimum and maximum values should stay approximately the same, the average value and standard deviation may be quite different.
    Specified by:
      `getProperty` in interface `RenderedImage`
    Overrides:
      `getProperty` in class `PlanarImage`
    Parameters:
      `key` - the name of the property to get.
    Returns:
      the property value, or `Image​.UndefinedProperty` if none.

  - ### getPropertyNames

    public String[] getPropertyNames()
    Returns the names of all recognized properties, or `null` if this image has no properties. The returned array contains the properties listed in `getProperty(String)` if the source image has those properties.
    Specified by:
      `getPropertyNames` in interface `RenderedImage`
    Overrides:
      `getPropertyNames` in class `PlanarImage`
    Returns:
      names of all recognized properties, or `null` if none.

  - ### getMinTileX

    public final int getMinTileX()
    Returns the minimum tile index in the x direction. This is often 0.
    Specified by:
      `getMinTileX` in interface `RenderedImage`
    Overrides:
      `getMinTileX` in class `PlanarImage`
    Returns:
      the minimum tile index in the x direction.

  - ### getMinTileY

    public final int getMinTileY()
    Returns the minimum tile index in the y direction. This is often 0.
    Specified by:
      `getMinTileY` in interface `RenderedImage`
    Overrides:
      `getMinTileY` in class `PlanarImage`
    Returns:
      the minimum tile index in the y direction.

  - ### getMinX

    public final int getMinX()
    Returns the minimum x coordinate (inclusive) of this image. This is the `Rectangle​.x` value of the `bounds` specified at construction time.
    Specified by:
      `getMinX` in interface `RenderedImage`
    Overrides:
      `getMinX` in class `PlanarImage`
    Returns:
      the minimum x coordinate (column) of this image.

  - ### getMinY

    public final int getMinY()
    Returns the minimum y coordinate (inclusive) of this image. This is the `Rectangle​.y` value of the `bounds` specified at construction time.
    Specified by:
      `getMinY` in interface `RenderedImage`
    Overrides:
      `getMinY` in class `PlanarImage`
    Returns:
      the minimum y coordinate (row) of this image.

  - ### getWidth

    public final int getWidth()
    Returns the number of columns in this image. This is the `Rectangle​.width` value of the `bounds` specified at construction time.
    Returns:
      number of columns in this image.

  - ### getHeight

    public final int getHeight()
    Returns the number of rows in this image. This is the `Rectangle​.height` value of the `bounds` specified at construction time.
    Returns:
      number of rows in this image.

  - ### computeTile

    protected Raster computeTile(int tileX, int tileY, WritableRaster tile) throws TransformException
    Invoked when a tile need to be computed or updated. This method fills all pixel values of the tile with values interpolated from the source image. It may be invoked concurrently in different threads.
    Specified by:
      `computeTile` in class `ComputedImage`
    Parameters:
      `tileX` - the column index of the tile to compute.
      `tileY` - the row index of the tile to compute.
      `tile` - if the tile already exists but needs to be updated, the tile to update. Otherwise `null`.
    Returns:
      computed tile for the given indices.
    Throws:
      `TransformException` - if an error occurred while computing pixel coordinates.

  - ### prefetch

    protected Disposable prefetch(Rectangle tiles)
    Notifies the source image that tiles will be computed soon in the given region. If the source image is an instance of `ComputedImage`, then this method forwards the notification to it. Otherwise default implementation does nothing.
    Overrides:
      `prefetch` in class `ComputedImage`
    Parameters:
      `tiles` - indices of the tiles which will be prefetched.
    Returns:
      handler on which to invoke `dispose()` after the prefetch operation completed (successfully or not), or `null` if none.
    Since:
      1.2

  - ### equals

    public boolean equals(Object object)
    Compares the given object with this image for equality. This method returns `true` if the given object is non-null, is an instance of the exact same class than this image, has equal sources and do the same resampling operation (same interpolation method, same fill values, same coordinates).
    Overrides:
      `equals` in class `Object`
    Parameters:
      `object` - the object to compare with this image.
    Returns:
      `true` if the given object is an image performing the same resampling than this image.

  - ### hashCode

    public int hashCode()
    Returns a hash code value for this image.
    Overrides:
      `hashCode` in class `Object`
    Returns:
      a hash code value based on a description of the operation performed by this image.