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
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 ofDefaultEvaluator
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
FieldsModifier and TypeFieldDescriptionprivate final GridCoverage
The coverage in which to evaluate sample values.private org.opengis.referencing.operation.MathTransform
Transform from grid coordinates to the CRS where wraparound axes may exist.private org.opengis.referencing.crs.CoordinateReferenceSystem
The coordinate reference system of input points given to this converter, ornull
if assumed the same than the coverage CRS.private org.opengis.referencing.operation.MathTransform
The transform frominputCRS
to grid coordinates.private boolean
Whether to returnnull
instead of throwing an exception if given point is outside coverage bounds.private double[]
The span (maximum - minimum) of wraparound axes, with 0 value for axes that are not wraparound.Grid coordinates afterinputToGrid
conversion.The slice where to perform evaluation, ornull
if not yet computed.(package private) double[]
Array where to store sample values computed byapply(DirectPosition)
.private long
A bitmask of grid dimensions that need to be verified for wraparound axes.private double[]
Coverage extent converted to floating point numbers, only for the grid dimensions having a bit set to 1 inwraparoundAxes
bitmask. -
Constructor Summary
ConstructorsModifierConstructorDescriptionprotected
DefaultEvaluator
(GridCoverage coverage) Creates a new evaluator for the given coverage. -
Method Summary
Modifier and TypeMethodDescriptiondouble[]
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.Returns the coverage from which this evaluator is fetching sample values.Returns the default slice where to perform evaluation, or an empty map if unspecified.boolean
Returns whether to returnnull
instead of throwing an exception if a point is outside coverage bounds.boolean
Returnstrue
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 theinputToGrid
field.void
setNullIfOutside
(boolean flag) Sets whether to returnnull
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.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.
-
Field Details
-
coverage
The coverage in which to evaluate sample values. -
inputCRS
private org.opengis.referencing.crs.CoordinateReferenceSystem inputCRSThe coordinate reference system of input points given to this converter, ornull
if assumed the same than the coverage CRS. This is used bytoGridPosition(DirectPosition)
for checking ifinputToGrid
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 inputToGridThe transform frominputCRS
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
Grid coordinates afterinputToGrid
conversion.- See Also:
-
values
double[] valuesArray where to store sample values computed byapply(DirectPosition)
. For performance reasons, the same array may be recycled on every method call. -
nullIfOutside
private boolean nullIfOutsideWhether to returnnull
instead of throwing an exception if given point is outside coverage bounds.- See Also:
-
wraparoundAxes
private long wraparoundAxesA bitmask of grid dimensions that need to be verified for wraparound axes. -
wraparoundExtent
private double[] wraparoundExtentCoverage extent converted to floating point numbers, only for the grid dimensions having a bit set to 1 inwraparoundAxes
bitmask. The length of this array is the number of bits set inwraparoundAxes
multiplied by 2. Elements are (lower, upper) tuples. -
gridToWraparound
private org.opengis.referencing.operation.MathTransform gridToWraparoundTransform from grid coordinates to the CRS where wraparound axes may exist. It is sometimes the same transform thangridToCRS
but not always. It may differ for example if a projected CRS has been replaced by a geographic CRS. -
periods
private double[] periodsThe 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
The slice where to perform evaluation, ornull
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
Creates a new evaluator for the given coverage. This constructor is protected for allowingGridCoverage
subclasses to provide their ownDefaultEvaluator
implementations. For using an evaluator, invokeGridCoverage.evaluator()
instead.- Parameters:
coverage
- the coverage for which to create an evaluator.- See Also:
-
-
Method Details
-
getCoverage
Returns the coverage from which this evaluator is fetching sample values. This is the coverage on which theGridCoverage.evaluator()
method has been invoked.- Specified by:
getCoverage
in interfaceBandedCoverage.Evaluator
- Specified by:
getCoverage
in interfaceGridCoverage.Evaluator
- Returns:
- the source of sample values for this evaluator.
-
getDefaultSlice
Returns the default slice where to perform evaluation, or an empty map if unspecified. Keys are dimensions from 0 inclusive toGridGeometry.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 interfaceGridCoverage.Evaluator
- Returns:
- the default slice where to perform evaluation, or an empty map if unspecified.
- Since:
- 1.3
-
setDefaultSlice
Sets the default slice where to perform evaluation when the points do not have enough dimensions. Anull
argument restores the default value, which is to infer the slice from the coverage grid geometry.- Specified by:
setDefaultSlice
in interfaceGridCoverage.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()Returnstrue
if this evaluator is allowed to wraparound coordinates that are outside the grid. The initial value isfalse
. This method may continue to returnfalse
even after a call tosetWraparoundEnabled(true)
if no wraparound axis has been found in the coverage CRS.- Specified by:
isWraparoundEnabled
in interfaceBandedCoverage.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. Iftrue
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 interfaceBandedCoverage.Evaluator
- Parameters:
allow
- whether to allow wraparound of coordinates that are outside the grid.- Since:
- 1.2
-
isNullIfOutside
public boolean isNullIfOutside()Returns whether to returnnull
instead of throwing an exception if a point is outside coverage bounds. The default value isfalse
, which means that the defaultapply(DirectPosition)
behavior is to throwPointOutsideCoverageException
for points outside bounds.- Specified by:
isNullIfOutside
in interfaceBandedCoverage.Evaluator
- Returns:
- whether
apply(DirectPosition)
returnnull
for points outside coverage bounds.
-
setNullIfOutside
public void setNullIfOutside(boolean flag) Sets whether to returnnull
instead of throwing an exception if a point is outside coverage bounds. The default value isfalse
. Setting this flag totrue
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 interfaceBandedCoverage.Evaluator
- Parameters:
flag
- whetherapply(DirectPosition)
should usenull
return value instead ofPointOutsideCoverageException
for signaling that a point is outside coverage bounds.
-
apply
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 interfaceBandedCoverage.Evaluator
- Specified by:
apply
in interfaceFunction<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 theisNullIfOutside()
flag isfalse
.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 todouble
by an identity or widening conversion. Subclasses may relax this constraint if appropriate.
-
evaluate
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 interfaceGridCoverage.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 oftoGridCoordinates(DirectPosition)
except that it avoid creating a newFractionalGridCoordinates
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 theinputToGrid
field. This method should be invoked when the transform has not yet been computed or became outdated becauseinputCRS
needs to be changed.- Parameters:
crs
- the new value to assign toinputCRS
.- 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.
-