Interface BandedCoverage.Evaluator

All Superinterfaces:

Function<Direct­Position, double[]>

All Known Subinterfaces:

Grid­Coverage.Evaluator

Enclosing class:

Banded­Coverage

public static interface BandedCoverage.Evaluator
extends Function<DirectPosition, double[]>

Computes or interpolates values of sample dimensions at given positions. Values are computed by calls to apply(Direct­Position) and are returned as double[].

Multi-threading

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

Since:

1.1

See Also:

• Banded­Coverage.evaluator()

Method Summary

Modifier and Type	Method	Description
double[]	apply(Direct­Position point)	Returns a sequence of double values for a given point in the coverage.
Banded­Coverage	get­Coverage()	Returns the coverage from which this evaluator is computing sample values.
boolean	is­Null­If­Outside()	Returns whether to return null instead of throwing an exception if a point is outside coverage bounds.
boolean	is­Wraparound­Enabled()	Returns true if this evaluator is allowed to wraparound coordinates that are outside the coverage.
void	set­Null­If­Outside(boolean flag)	Sets whether to return null instead of throwing an exception if a point is outside coverage bounds.
void	set­Wraparound­Enabled(boolean allow)	Specifies whether this evaluator is allowed to wraparound coordinates that are outside the coverage.
default Stream<double[]>	stream(Collection<? extends Direct­Position> points, boolean parallel)	Returns a stream of sample values for each point of the given collection.

Methods inherited from interface Function

and­Then, compose

Method Details

getCoverage

BandedCoverage getCoverage()

Returns the coverage from which this evaluator is computing sample values. This is usually the instance on which the Banded­Coverage.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.

Returns:

the source of sample values for this evaluator.

isNullIfOutside

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(Direct­Position) behavior is to throw Point­Outside­Coverage­Exception for points outside bounds.

Returns:

whether apply(Direct­Position) return null for points outside coverage bounds.

setNullIfOutside

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 number of exceptions to be thrown.

Parameters:

flag - whether apply(Direct­Position) should use null return value instead of Point­Outside­Coverage­Exception for signaling that a point is outside coverage bounds.

isWraparoundEnabled

boolean isWraparoundEnabled()

Returns true if this evaluator is allowed to wraparound coordinates that are outside the coverage. The initial value is false. This method may continue to return false even after a call to set­Wraparound­Enabled(true) if no wraparound axis has been found in the coverage CRS, or if automatic wraparound is not supported.

Returns:

true if this evaluator may wraparound coordinates that are outside the coverage.

Since:

1.3

setWraparoundEnabled

void setWraparoundEnabled(boolean allow)

Specifies whether this evaluator is allowed to wraparound coordinates that are outside the coverage. If true and if a given coordinate is outside the coverage, then this evaluator may translate the point along a wraparound axis in an attempt to get the point inside the coverage. For example, if the coverage CRS has a longitude axis, then the evaluator may translate the longitude value by a multiple of 360°.

Parameters:

allow - whether to allow wraparound of coordinates that are outside the coverage.

Since:

1.3

apply

double[] apply(DirectPosition point)
        throws CannotEvaluateException

Returns a sequence of double values for a given point in the coverage. If the CRS of the point is undefined (i.e., null), then it is assumed to be the CRS of the coverage. If the CRS of the point is defined but different than the coverage CRS, then coordinate conversions or transformations will be applied automatically by this method.

The returned sequence includes a value for each sample dimension. For performance reason, this method may return the same array on every method call by overwriting previous values. Therefore, callers can assume that the array content is stable only until the next call to an Evaluator method or traversal of more elements in the stream.

Specified by:

apply in interface Function<Direct­Position, 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. This is not guaranteed to be a new array on each method call.

Throws:

Point­Outside­Coverage­Exception - if the evaluation failed because the input point has invalid coordinates and the is­Null­If­Outside() flag is false.

Cannot­Evaluate­Exception - if the values cannot be computed at the specified coordinates for another reason. For example, this exception may be thrown if the coverage data type cannot be converted to double by an identity or widening conversion.

stream

default Stream<double[]> stream(Collection<? extends DirectPosition> points,
 boolean parallel)

Returns a stream of sample values for each point of the given collection. The values in the returned stream are traversed in the iteration order of the given collection. The returned stream behave as if apply(Direct­Position) was invoked for each point.

This method is equivalent to points.stream().map(this::apply), but potentially more efficient. Therefore, the notes documented in apply(Direct­Position) apply also to each elements traversed by the stream: the CRS of each point is handled as documented in apply(Direct­Position), consumers should not assume that the content of the double[] arrays are stable after execution of the consumer body, and some elements provided by the stream may be null if a point is outside the coverage and the is­Null­If­Outside() flag is true.

Parallel streams

While Evaluator is not thread-safe, parallel streams may be supported provided that the state of this Evaluator is not modified during stream execution. A parallel stream can be requested by invoking this method with the parallel argument set to true. The Base­Stream.parallel() method should not by invoked.

Implementations may ignore the parallel argument if they do not support parallel streams. It is more difficult for implementations to ignore a call to Base­Stream.parallel(), which is why parallel() should not be invoked on streams returned by this method.

Exceptions

Cannot­Evaluate­Exception may be thrown either when this method is invoked, or later during the traversal, at implementation choice.

Parameters:

points - the positions where to evaluate.

parallel - true for a parallel stream, or false for a sequential stream.

Returns:

a sequential or parallel stream of sample values at the specified positions.

Since:

1.6