Package org.apache.sis.coverage.grid

# Class GridEvaluator

Object
GridEvaluator

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

public class GridEvaluator extends Object implements BandedCoverage.Evaluator
Computes or interpolates values of sample dimensions at given positions. Values are computed by calls to `apply(DirectPosition)` and are returned as `double[]`.

## Multi-threading

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

## Limitations

Current implementation performs nearest-neighbor sampling only. A future version will provide interpolations.

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

Defined in the `sis-feature` module

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `GridEvaluator(GridCoverage coverage)`
  Creates a new evaluator for the given coverage.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `double[]`
  `apply(DirectPosition point)`
  Returns a sequence of double values for a given point in the coverage.
  `GridCoverage`
  `getCoverage()`
  Returns the coverage from which this evaluator is fetching sample values.
  `boolean`
  `isNullIfOutside()`
  Returns whether to return `null` instead of throwing an exception if a point is outside coverage bounds.
  `void`
  `setNullIfOutside(boolean flag)`
  Sets whether to return `null` instead of throwing an exception if a point is outside coverage bounds.
  `FractionalGridCoordinates`
  `toGridCoordinates(DirectPosition point)`
  Converts the specified geospatial position to grid coordinates.

  ### Methods inherited from class Object

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

  ### Methods inherited from interface Function

  `andThen, compose`

- ## Constructor Details

  - ### GridEvaluator

    protected GridEvaluator(GridCoverage coverage)
    Creates a new evaluator for the given coverage. This constructor is protected for allowing `GridCoverage` subclasses to provide their own `GridEvaluator` implementations. For using an evaluator, invoke `GridCoverage​.evaluator()` instead.
    Parameters:
      `coverage` - the coverage for which to create an evaluator.
    See Also:
      - `GridCoverage​.evaluator()`

- ## Method Details

  - ### getCoverage

    public GridCoverage getCoverage()
    Returns the coverage from which this evaluator is fetching sample values.
    Specified by:
      `getCoverage` in interface `BandedCoverage​.Evaluator`
    Returns:
      the source of sample values for this evaluator.

  - ### isNullIfOutside

    public boolean isNullIfOutside()
    Returns whether to return `null` instead of throwing an exception if a point is outside coverage bounds. The default value is `false`, which means that the default `apply(DirectPosition)` behavior is to throw `PointOutsideCoverageException` for points outside bounds.
    Specified by:
      `isNullIfOutside` in interface `BandedCoverage​.Evaluator`
    Returns:
      whether `apply(DirectPosition)` return `null` for points outside coverage bounds.

  - ### setNullIfOutside

    public void setNullIfOutside(boolean flag)
    Sets whether to return `null` instead of throwing an exception if a point is outside coverage bounds. The default value is `false`. Setting this flag to `true` may improve performances if the caller expects that many points will be outside coverage bounds, since it reduces the amount of exceptions to be created.
    Specified by:
      `setNullIfOutside` in interface `BandedCoverage​.Evaluator`
    Parameters:
      `flag` - whether `apply(DirectPosition)` should use `null` return value instead of `PointOutsideCoverageException` for signaling that a point is outside coverage bounds.

  - ### apply

    public double[] apply(DirectPosition point) throws CannotEvaluateException
    Returns a sequence of double values for a given point in the coverage. The CRS of the given point may be any coordinate reference system; coordinate conversions will be applied as needed. If the CRS of the point is undefined, then it is assumed to be the coverage CRS. The returned sequence includes a value for each sample dimension.

    The default interpolation type used when accessing grid values for points which fall between grid cells is nearest neighbor. This default interpolation method may change in future version.

    The default implementation invokes `GridCoverage​.render(GridExtent)` for a small region around the point. Subclasses should override with more efficient implementation.

    Specified by:
      `apply` in interface `BandedCoverage​.Evaluator`
    Specified by:
      `apply` in interface `Function<DirectPosition,double[]>`
    Parameters:
      `point` - the coordinate point where to evaluate.
    Returns:
      the sample values at the specified point, or `null` if the point is outside the coverage. For performance reason, this method may return the same array on every method call by overwriting previous values. Callers should not assume that the array content stay valid for a long time.
    Throws:
      `PointOutsideCoverageException` - if the evaluation failed because the input point has invalid coordinates and the `isNullIfOutside()` flag is `false`.
      `CannotEvaluateException` - if the values can not be computed at the specified coordinates for another reason. This exception may be thrown if the coverage data type can not be converted to `double` by an identity or widening conversion. Subclasses may relax this constraint if appropriate.

  - ### toGridCoordinates

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

    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 can not be transformed.
    See Also:
      - `FractionalGridCoordinates​.toPosition(MathTransform)`