Module org.apache.sis.feature
Package org.apache.sis.coverage.grid

# Interface GridCoverage.Evaluator

All Superinterfaces:
  `BandedCoverage​.Evaluator`, `Function<DirectPosition,double[]>`

Enclosing class:
  `GridCoverage`

public static interface GridCoverage.Evaluator extends BandedCoverage.Evaluator
Interpolates values of sample dimensions at given positions. Values are computed by calls to `BandedCoverage​.Evaluator​.apply(DirectPosition)` and are returned as `double[]`. This method extends `BandedCoverage​.Evaluator` with the addition of some methods specific to gridded data.

## Multi-threading

Evaluators are not thread-safe. An instance of `Evaluator` should be created for each thread that need to interpolate sample values.

Since:
  1.3
See Also:
  - `GridCoverage​.evaluator()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `GridCoverage`
  `getCoverage()`
  Returns the grid coverage from which this evaluator is computing sample values.
  `Map<Integer,Long>`
  `getDefaultSlice()`
  Returns the default slice where to perform evaluation, or an empty map if unspecified.
  `void`
  `setDefaultSlice(Map<Integer,Long> slice)`
  Sets the default slice where to perform evaluation when the points do not have enough dimensions.
  `FractionalGridCoordinates`
  `toGridCoordinates(DirectPosition point)`
  Converts the specified geospatial position to grid coordinates.

  ### Methods inherited from interface BandedCoverage.Evaluator

  `apply, isNullIfOutside, isWraparoundEnabled, setNullIfOutside, setWraparoundEnabled`

  ### Methods inherited from interface Function

  `andThen, compose`

- ## Method Details

  - ### getCoverage

    GridCoverage getCoverage()
    Returns the grid coverage from which this evaluator is computing sample values. This is usually the instance on which the `GridCoverage​.evaluator()` method has been invoked, but not necessarily. Evaluators are allowed to fetch values from a different source for better performances or accuracies.

    #### Example

    If the values of the enclosing coverage are interpolated from the values of another coverage, then this evaluator may use directly the values of the latter coverage. Doing so avoid to add more interpolations on values that are already interpolated.
    Specified by:
      `getCoverage` in interface `BandedCoverage​.Evaluator`
    Returns:
      the source of sample values for this evaluator.
    See Also:
      - `toGridCoordinates(DirectPosition)`

  - ### getDefaultSlice

    Map<Integer,Long> getDefaultSlice()
    Returns the default slice where to perform evaluation, or an empty map if unspecified. Keys are dimensions from 0 inclusive to `GridGeometry​.getDimension()` exclusive, and values are the grid coordinates of the slice in the dimension specified by the key.

    This information allows to invoke `BandedCoverage​.Evaluator​.apply(DirectPosition)` with for example two-dimensional points even if the underlying coverage is three-dimensional. The missing coordinate values are replaced by the values provided in the map.

    Returns:
      the default slice where to perform evaluation, or an empty map if unspecified.

  - ### setDefaultSlice

    void setDefaultSlice(Map<Integer,Long> slice)
    Sets the default slice where to perform evaluation when the points do not have enough dimensions. A `null` argument restores the default value, which is to infer the slice from the coverage grid geometry.
    Parameters:
      `slice` - the default slice where to perform evaluation, or an empty map if none.
    Throws:
      `IllegalArgumentException` - if the map contains an illegal dimension or grid coordinate value.
    See Also:
      - `GridExtent​.getSliceCoordinates()`

  - ### toGridCoordinates

    FractionalGridCoordinates toGridCoordinates(DirectPosition point) throws TransformException
    Converts the specified geospatial position to grid coordinates. If the given position is associated to a non-null coordinate reference system (CRS) different than the coverage CRS, then this method automatically transforms that position to the coverage CRS before to compute grid coordinates.

    The returned value are coordinates in the grid of the coverage returned by `getCoverage()`. This is usually the coverage instance on which `GridCoverage​.evaluator()` has been invoked, but not necessarily. Evaluators are allowed to fetch values from a different source for better performances or accuracies.

    This method does not put any restriction on the grid coordinates result. The result may be outside the grid extent if the grid to CRS transform allows it.

    Parameters:
      `point` - geospatial coordinates (in arbitrary CRS) to transform to grid coordinates.
    Returns:
      the grid coordinates for the given geospatial coordinates.
    Throws:
      `IncompleteGridGeometryException` - if the grid geometry does not define a "grid to CRS" transform, or if the given point has a non-null CRS but the coverage does not have a CRS.
      `TransformException` - if the given coordinates cannot be transformed.
    See Also:
      - `FractionalGridCoordinates​.toPosition(MathTransform)`