Package org.apache.sis.coverage.grid

Class DefaultEvaluator

java.lang.Object
org.apache.sis.coverage.grid.DefaultEvaluator
All Implemented Interfaces:
Function<org.opengis.geometry.DirectPosition,double[]>, BandedCoverage.Evaluator, GridCoverage.Evaluator
Direct Known Subclasses:
BufferedGridCoverage.CellAccessor, GridCoverage2D.PixelAccessor
class DefaultEvaluator extends Object implements GridCoverage.Evaluator
Default implementation of GridCoverage.Evaluator for interpolating values 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 DefaultEvaluator 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
Version:
1.3
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private final GridCoverage
    coverage
    The coverage in which to evaluate sample values.
    private org.opengis.referencing.operation.MathTransform
    gridToWraparound
    Transform from grid coordinates to the CRS where wraparound axes may exist.
    private org.opengis.referencing.crs.CoordinateReferenceSystem
    inputCRS
    The coordinate reference system of input points given to this converter, or null if assumed the same than the coverage CRS.
    private org.opengis.referencing.operation.MathTransform
    inputToGrid
    The transform from inputCRS to grid coordinates.
    private boolean
    nullIfOutside
    Whether to return null instead of throwing an exception if given point is outside coverage bounds.
    private double[]
    periods
    The span (maximum - minimum) of wraparound axes, with 0 value for axes that are not wraparound.
    private FractionalGridCoordinates.Position
    position
    Grid coordinates after inputToGrid conversion.
    private Map<Integer,Long>
    slice
    The slice where to perform evaluation, or null if not yet computed.
    (package private) double[]
    values
    Array where to store sample values computed by apply(DirectPosition).
    private long
    wraparoundAxes
    A bitmask of grid dimensions that need to be verified for wraparound axes.
    private double[]
    wraparoundExtent
    Coverage extent converted to floating point numbers, only for the grid dimensions having a bit set to 1 in wraparoundAxes bitmask.

  • Constructor Summary

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

  • Method Summary

    Modifier and Type
    Method
    Description
    double[]
    apply(org.opengis.geometry.DirectPosition point)
    Returns a sequence of double values for a given point in the coverage.
    (package private) final double[]
    evaluate(RenderedImage data, int x, int y)
    Gets sample values from the given image at the given index.
    GridCoverage
    getCoverage()
    Returns the coverage from which this evaluator is fetching sample values.
    Map<Integer,Long>
    getDefaultSlice()
    Returns the default slice where to perform evaluation, or an empty map if unspecified.
    boolean
    isNullIfOutside()
    Returns whether to return null instead of throwing an exception if a point is outside coverage bounds.
    boolean
    isWraparoundEnabled()
    Returns true if this evaluator is allowed to wraparound coordinates that are outside the grid.
    private static void
    recoverableException(String caller, org.opengis.referencing.operation.TransformException exception)
    Invoked when a recoverable exception occurred.
    void
    setDefaultSlice(Map<Integer,Long> slice)
    Sets the default slice where to perform evaluation when the points do not have enough dimensions.
    private void
    setInputCRS(org.opengis.referencing.crs.CoordinateReferenceSystem crs)
    Recomputes the inputToGrid field.
    void
    setNullIfOutside(boolean flag)
    Sets whether to return null instead of throwing an exception if a point is outside coverage bounds.
    void
    setWraparoundEnabled(boolean allow)
    Specifies whether this evaluator is allowed to wraparound coordinates that are outside the grid.
    FractionalGridCoordinates
    toGridCoordinates(org.opengis.geometry.DirectPosition point)
    Converts the specified geospatial position to grid coordinates.
    (package private) final FractionalGridCoordinates.Position
    toGridPosition(org.opengis.geometry.DirectPosition point)
    Updates the grid position with the given geospatial position.

    Methods inherited from class java.lang.Object

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

    Methods inherited from interface java.util.function.Function

    andThen, compose

  • Field Details

    • coverage

      private final GridCoverage coverage
      The coverage in which to evaluate sample values.

    • inputCRS

      private org.opengis.referencing.crs.CoordinateReferenceSystem inputCRS
      The coordinate reference system of input points given to this converter, or null if assumed the same than the coverage CRS. This is used by toGridPosition(DirectPosition) for checking if inputToGrid needs to be recomputed. As long at the evaluated points have the same CRS, the same transform is reused.

    • inputToGrid

      private org.opengis.referencing.operation.MathTransform inputToGrid
      The transform from inputCRS to grid coordinates. This is cached for avoiding the costly process of fetching a coordinate operation in the common case where the coordinate reference systems did not changed.

    • position

      private FractionalGridCoordinates.Position position
      Grid coordinates after inputToGrid conversion.
      See Also:

    • values

      double[] values
      Array where to store sample values computed by apply(DirectPosition). For performance reasons, the same array may be recycled on every method call.

    • nullIfOutside

      private boolean nullIfOutside
      Whether to return null instead of throwing an exception if given point is outside coverage bounds.
      See Also:

    • wraparoundAxes

      private long wraparoundAxes
      A bitmask of grid dimensions that need to be verified for wraparound axes.

    • wraparoundExtent

      private double[] wraparoundExtent
      Coverage extent converted to floating point numbers, only for the grid dimensions having a bit set to 1 in wraparoundAxes bitmask. The length of this array is the number of bits set in wraparoundAxes multiplied by 2. Elements are (lower, upper) tuples.

    • gridToWraparound

      private org.opengis.referencing.operation.MathTransform gridToWraparound
      Transform from grid coordinates to the CRS where wraparound axes may exist. It is sometimes the same transform than gridToCRS but not always. It may differ for example if a projected CRS has been replaced by a geographic CRS.

    • periods

      private double[] periods
      The span (maximum - minimum) of wraparound axes, with 0 value for axes that are not wraparound. The length of this array may be shorter than the CRS number of dimensions if all remaining axes are not wraparound axes.

    • slice

      private Map<Integer,Long> slice
      The slice where to perform evaluation, or null if not yet computed. This information allows to specify for example two-dimensional points for evaluating in a three-dimensional data cube. This is used for completing the missing coordinate values.
      See Also:

  • Constructor Details

    • DefaultEvaluator

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

  • Method Details

    • getCoverage

      public GridCoverage getCoverage()
      Returns the coverage from which this evaluator is fetching sample values. This is the coverage on which the GridCoverage.evaluator() method has been invoked.
      Specified by:
      getCoverage in interface BandedCoverage.Evaluator
      Specified by:
      getCoverage in interface GridCoverage.Evaluator
      Returns:
      the source of sample values for this evaluator.

    • getDefaultSlice

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

      Specified by:
      getDefaultSlice in interface GridCoverage.Evaluator
      Returns:
      the default slice where to perform evaluation, or an empty map if unspecified.
      Since:
      1.3

    • setDefaultSlice

      public 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.
      Specified by:
      setDefaultSlice in interface GridCoverage.Evaluator
      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.
      Since:
      1.3
      See Also:

    • isWraparoundEnabled

      public boolean isWraparoundEnabled()
      Returns true if this evaluator is allowed to wraparound coordinates that are outside the grid. The initial value is false. This method may continue to return false even after a call to setWraparoundEnabled(true) if no wraparound axis has been found in the coverage CRS.
      Specified by:
      isWraparoundEnabled in interface BandedCoverage.Evaluator
      Returns:
      true if this evaluator may wraparound coordinates that are outside the grid.
      Since:
      1.2

    • setWraparoundEnabled

      public void setWraparoundEnabled(boolean allow)
      Specifies whether this evaluator is allowed to wraparound coordinates that are outside the grid. If true and if a given coordinate is outside the grid, then this evaluator may translate the point along a wraparound axis in an attempt to get the point inside the grid. For example, if the coverage CRS has a longitude axis, then the evaluator may translate the longitude value by a multiple of 360°.
      Specified by:
      setWraparoundEnabled in interface BandedCoverage.Evaluator
      Parameters:
      allow - whether to allow wraparound of coordinates that are outside the grid.
      Since:
      1.2

    • 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(org.opengis.geometry.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<org.opengis.geometry.DirectPosition,double[]>
      Parameters:
      point - the position 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 cannot be computed at the specified coordinates for another reason. This exception may be thrown if the coverage data type cannot be converted to double by an identity or widening conversion. Subclasses may relax this constraint if appropriate.

    • evaluate

      final double[] evaluate(RenderedImage data, int x, int y)
      Gets sample values from the given image at the given index. This method does not verify explicitly if the coordinates are out of bounds; we rely on the checks performed by the image and sample model implementations.
      Parameters:
      data - the data from which to get the sample values.
      x - column index of the value to get.
      y - row index of the value to get.
      Returns:
      the sample values. The same array may be recycled on every method call.
      Throws:
      ArithmeticException - if an integer overflow occurred while computing indices.
      IndexOutOfBoundsException - if a coordinate is out of bounds.

    • toGridCoordinates

      public FractionalGridCoordinates toGridCoordinates(org.opengis.geometry.DirectPosition point) throws org.opengis.referencing.operation.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.

      Specified by:
      toGridCoordinates in interface GridCoverage.Evaluator
      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.
      org.opengis.referencing.operation.TransformException - if the given coordinates cannot be transformed.
      See Also:

    • toGridPosition

      final FractionalGridCoordinates.Position toGridPosition(org.opengis.geometry.DirectPosition point) throws org.opengis.util.FactoryException, org.opengis.referencing.operation.TransformException
      Updates the grid position with the given geospatial position. This is the implementation of toGridCoordinates(DirectPosition) except that it avoid creating a new FractionalGridCoordinates on each method call.
      Parameters:
      point - the geospatial position.
      Returns:
      the given position converted to grid coordinates (possibly out of grid bounds).
      Throws:
      org.opengis.util.FactoryException - if no operation is found form given point CRS to coverage CRS.
      org.opengis.referencing.operation.TransformException - if the given position cannot be converted.

    • setInputCRS

      private void setInputCRS(org.opengis.referencing.crs.CoordinateReferenceSystem crs) throws org.opengis.util.FactoryException, org.opengis.referencing.operation.NoninvertibleTransformException
      Recomputes the inputToGrid field. This method should be invoked when the transform has not yet been computed or became outdated because inputCRS needs to be changed.
      Parameters:
      crs - the new value to assign to inputCRS.
      Throws:
      org.opengis.util.FactoryException
      org.opengis.referencing.operation.NoninvertibleTransformException

    • recoverableException

      private static void recoverableException(String caller, org.opengis.referencing.operation.TransformException exception)
      Invoked when a recoverable exception occurred. Those exceptions must be minor enough that they can be silently ignored in most cases.
      Parameters:
      caller - the method where exception occurred.
      exception - the exception that occurred.