Class ExtentSelector<T>
java.lang.Object
org.apache.sis.internal.referencing.ExtentSelector<T>
- Type Parameters:
T
- the type of object to be selected.
Selects an object in a sequence of objects using their extent as a criterion.
The selection is based on the temporal extent and geographic area using the following rules:
- Object having largest intersection with the time of interest (TOI) is selected.
- If two or more candidates have the same intersection with TOI, then the one with less "overtime" (time outside TOI) is selected.
- If two or more candidates are considered equal after above criteria, then the one best centered on the TOI is selected.
Rational:
the "smallest time outside" criterion (rule 2) is before "best centered" criterion (rule 3)
because of the following scenario: if a user specifies a "time of interest" (TOI) of 1 day
and if the candidates are a raster of monthly averages and a raster of daily data, we want
the daily data to be selected even if by coincidence the monthly averages is more centered.
If there is no time of interest, or the candidate objects do not declare time range,
or some objects are still at equality after application of above criteria,
then the selection continues on the basis of geographic criteria:
- Largest intersection with the area of interest (AOI) is selected.
- If two or more candidates have the same intersection area with AOI, then the one with the less "irrelevant" material is selected. "Irrelevant" material are area outside the AOI.
- If two or more candidates are considered equal after above criteria, the one best centered on the AOI is selected.
- If two or more candidates are considered equal after above criteria, then the first of those candidates is selected.
Change of rule order
The following configuration flags change the order in which above rules are applied.alternateOrdering
— whether the time center criterion is tested last.
Usage
Example:- Since:
- 0.4
- Version:
- 1.3
-
Field Summary
FieldsModifier and TypeFieldDescriptionboolean
Whether to use an alternate conditions order where the time center criterion is tested last.private org.opengis.metadata.extent.GeographicBoundingBox
The area of interest (AOI), ornull
if unbounded.private T
The best object found so far.private long
Granularity of the time of interest in seconds, or 0 if none.private double
The area covered by the best object (m²).private Duration
Duration of the best object, ornull
if none.private Instant
Start/end of the time of interest (TOI), ornull
if unbounded.private Instant
Start/end of the time of interest (TOI), ornull
if unbounded.private static final int
Identification of which fields need to be recomputed.private static final int
Identification of which fields need to be recomputed.private double
Area of best object which is outside the area of interest.private Duration
Duration of best object which is outside the time of interest.private static final int
Identification of which fields need to be recomputed.private static final int
Identification of which fields need to be recomputed.private double
A pseudo-distance from best object center toareaOfInterest
center.private static final int
Identification of which fields need to be recomputed.private double
Time between best entry center and TOI center. -
Constructor Summary
ConstructorsConstructorDescriptionExtentSelector
(org.opengis.metadata.extent.Extent domain) Creates a selector for the given area of interest.ExtentSelector
(org.opengis.metadata.extent.GeographicBoundingBox aoi, Instant[] toi) Creates a selector for the given area and time of interest. -
Method Summary
Modifier and TypeMethodDescriptionbest()
Returns the object associated to the largest area found so far.private static int
compare
(double a, double b, int missing) Compares the given values as documented inDouble.compareTo(Double)
except in the handling of zero and NaN values.private static int
Compares the given duration as documented inDuration.compareTo(Duration)
with the addition of supportingnull
values.void
Evaluates the given extent against the criteria represented by thisExtentSelector
.void
evaluate
(org.opengis.metadata.extent.GeographicBoundingBox bbox, Instant startTime, Instant endTime, T object) Evaluates the given bounding box and time range against the criteria represented by thisExtentSelector
.final org.opengis.metadata.extent.GeographicBoundingBox
Returns the area of interest.final Instant[]
Returns the time of interest as an array of length 2, ornull
if none.private static double
Returns instant (in milliseconds) in the middle of given time range, orDouble.NaN
if none.private Duration
Computes the amount of time outside the time of interest (TOI).private double
pseudoDistance
(org.opengis.metadata.extent.GeographicBoundingBox area) Computes a pseudo-distance between the center of given area and ofareaOfInterest
.private Duration
Returns the given duration rounded to the nearest integer amount of temporal granularity.final boolean
setExtentOfInterest
(org.opengis.metadata.extent.Extent domain, org.opengis.metadata.extent.GeographicBoundingBox aoi, Instant[] toi) Sets the area of interest (AOI) and time of interest (TOI) to the intersection of given arguments.final void
setTimeGranularity
(Duration resolution) Sets the temporal granularity of the Time of Interest (TOI).private double
temporalDistance
(Instant startTime, Instant endTime) Computes a temporal distance between the center of given range and center of time of interest.
-
Field Details
-
areaOfInterest
private org.opengis.metadata.extent.GeographicBoundingBox areaOfInterestThe area of interest (AOI), ornull
if unbounded. This is initialized at construction time, but can be modified later. -
minTOI
Start/end of the time of interest (TOI), ornull
if unbounded. This is initialized at construction time, but can be modified later. -
maxTOI
Start/end of the time of interest (TOI), ornull
if unbounded. This is initialized at construction time, but can be modified later. -
granularity
private long granularityGranularity of the time of interest in seconds, or 0 if none. If non-zero, this this is always positive.- See Also:
-
alternateOrdering
public boolean alternateOrderingWhether to use an alternate conditions order where the time center criterion is tested last. This flag can be set totrue
if the Time Of Interest (TOI) is expected to be larger than the temporal extent of candidate objects, in which case many objects may fit in the TOI. Those candidates may be considered practically equally good regarding temporal aspect, in which case the caller may want to give precedence to geographic area.This flag is often used together with
setTimeGranularity(Duration)
method for reducing the preponderance of temporal criteria. -
best
The best object found so far. -
largestArea
private double largestAreaThe area covered by the best object (m²). This is the first criterion cited in class javadoc. -
longestTime
Duration of the best object, ornull
if none. This is equivalent tolargestArea
in the temporal domain. Value is rounded byround(Duration)
. -
outsideArea
private double outsideAreaArea of best object which is outside the area of interest. This is used as a discriminatory criterion only whenlargestArea
has the same value for two or more objects. This is the second criterion cited in class javadoc. -
overtime
Duration of best object which is outside the time of interest. This is used as a discriminatory criterion only whenlongestTime
has the same value for two or more objects. This is equivalent tooutsideArea
in the temporal domain. -
pseudoDistance
private double pseudoDistanceA pseudo-distance from best object center toareaOfInterest
center. This is not a real distance, neither great circle distance or rhumb line. The only requirements are: a value equals to zero when the two centers are coincident and increasing when the centers are mowing away.This value is used as a discriminatory criterion only when
largestArea
andoutsideArea
have the same values for two or more objects. This is the third criterion cited in class javadoc. -
temporalDistance
private double temporalDistanceTime between best entry center and TOI center. This value is used as a discriminatory criterion only whenlongestTime
andovertime
have the same values for two or more objects. This is equivalent topseudoDistance
in the temporal domain. -
OVERTIME
private static final int OVERTIMEIdentification of which fields need to be recomputed. This is an ordered enumeration: recomputing a field implies recomputing all following fields (identified by greater values). For example if thetemporalDistance
field needs to be recomputed, then theoutsideArea
andpseudoDistance
fields must be recomputed as well. This is a consequence of the order in which criteria documented in class javadoc are applied.- See Also:
-
TEMPORAL_DISTANCE
private static final int TEMPORAL_DISTANCEIdentification of which fields need to be recomputed. This is an ordered enumeration: recomputing a field implies recomputing all following fields (identified by greater values). For example if thetemporalDistance
field needs to be recomputed, then theoutsideArea
andpseudoDistance
fields must be recomputed as well. This is a consequence of the order in which criteria documented in class javadoc are applied.- See Also:
-
OUTSIDE_AREA
private static final int OUTSIDE_AREAIdentification of which fields need to be recomputed. This is an ordered enumeration: recomputing a field implies recomputing all following fields (identified by greater values). For example if thetemporalDistance
field needs to be recomputed, then theoutsideArea
andpseudoDistance
fields must be recomputed as well. This is a consequence of the order in which criteria documented in class javadoc are applied.- See Also:
-
PSEUDO_DISTANCE
private static final int PSEUDO_DISTANCEIdentification of which fields need to be recomputed. This is an ordered enumeration: recomputing a field implies recomputing all following fields (identified by greater values). For example if thetemporalDistance
field needs to be recomputed, then theoutsideArea
andpseudoDistance
fields must be recomputed as well. This is a consequence of the order in which criteria documented in class javadoc are applied.- See Also:
-
NONE
private static final int NONEIdentification of which fields need to be recomputed. This is an ordered enumeration: recomputing a field implies recomputing all following fields (identified by greater values). For example if thetemporalDistance
field needs to be recomputed, then theoutsideArea
andpseudoDistance
fields must be recomputed as well. This is a consequence of the order in which criteria documented in class javadoc are applied.- See Also:
-
-
Constructor Details
-
ExtentSelector
Creates a selector for the given area and time of interest.- Parameters:
aoi
- the area of interest, ornull
if unbounded.toi
- the time of interest, ornull
or empty if unbounded. The first element is start time and the last element is end time.
-
ExtentSelector
public ExtentSelector(org.opengis.metadata.extent.Extent domain) Creates a selector for the given area of interest.- Parameters:
domain
- the area and time of interest, ornull
if none.- Throws:
IllegalArgumentException
- if AOI or TOI has an invalid range.
-
-
Method Details
-
setExtentOfInterest
public final boolean setExtentOfInterest(org.opengis.metadata.extent.Extent domain, org.opengis.metadata.extent.GeographicBoundingBox aoi, Instant[] toi) Sets the area of interest (AOI) and time of interest (TOI) to the intersection of given arguments. This method should be invoked only ifbest()
returnednull
. It allows to make new attempts with a different domain of interest when the search using previous AOI/TOI gave no result.Callers should not use this
ExtentSelector
if this method returnsfalse
, except for invoking thissetExtentOfInterest(…)
method again with different values until this method returnstrue
.- Parameters:
domain
- the area and time of interest, ornull
if none.aoi
- second area of interest as a bounding box, ornull
if none.toi
- second time of interest as a an array of length 2, 1 or 0, ornull
. If array length is 2, it contains start time and end time in that order. If array length is 1, start time and end time are assumed the same. If array length is 0 or array reference is null, there is no temporal range to intersect.- Returns:
- whether the intersections of
domain
withaoi
andtoi
have valid ranges.
-
getAreaOfInterest
public final org.opengis.metadata.extent.GeographicBoundingBox getAreaOfInterest()Returns the area of interest.- Returns:
- area of interest, or
null
if none.
-
getTimeOfInterest
Returns the time of interest as an array of length 2, ornull
if none.- Returns:
- the start time and end time of interest, or
null
if none.
-
setTimeGranularity
Sets the temporal granularity of the Time of Interest (TOI). If non-null, intersections with TOI will be rounded to an integer amount of this granularity. This is useful if data are expected at an approximately regular interval (for example one remote sensing image per day) and we want to ignore slight variations in the temporal extent declared for each image.This method is often used together with
alternateOrdering
flag for reducing the preponderance of temporal criteria.- Parameters:
resolution
- granularity of the time of interest, ornull
if none.- Throws:
IllegalArgumentException
- if the given resolution is zero or negative.
-
round
Returns the given duration rounded to the nearest integer amount of temporal granularity. If no granularity has been specified, then this method returns the given duration unmodified. -
pseudoDistance
private double pseudoDistance(org.opengis.metadata.extent.GeographicBoundingBox area) Computes a pseudo-distance between the center of given area and ofareaOfInterest
. This is not a real distance, neither great circle distance or rhumb line. May beDouble.NaN
if information is unknown.- See Also:
-
temporalDistance
Computes a temporal distance between the center of given range and center of time of interest. This is always a positive value orDouble.NaN
. Unit is irrelevant (as long as constant) because we only compare distances with other distances.- See Also:
-
median
Returns instant (in milliseconds) in the middle of given time range, orDouble.NaN
if none. Used fortemporalDistance(Instant, Instant)
implementation only. -
overtime
Computes the amount of time outside the time of interest (TOI). The returned value is always positive becauseintersection
should always be less thanendTime
−startTime
duration. Value is rounded byround(Duration)
. -
evaluate
Evaluates the given extent against the criteria represented by thisExtentSelector
. See class javadoc for a list of criteria and the order in which they are applied. Implementation delegates toevaluate(GeographicBoundingBox, Instant, Instant, Object)
.- Parameters:
domain
- the extent to evaluate, ornull
if none.object
- a user object associated to the given extent.
-
evaluate
public void evaluate(org.opengis.metadata.extent.GeographicBoundingBox bbox, Instant startTime, Instant endTime, T object) Evaluates the given bounding box and time range against the criteria represented by thisExtentSelector
. See class javadoc for a list of criteria and the order in which they are applied.- Parameters:
bbox
- the geographic extent ofobject
, ornull
if none.startTime
- start time ofobject
, ornull
if none (unbounded).endTime
- end time ofobject
, ornull
if none (unbounded).object
- a user object associated to the given extent.
-
compare
Compares the given duration as documented inDuration.compareTo(Duration)
with the addition of supportingnull
values. Themissing
argument tells whether null values shall be considered smaller (-1) or greater (+1) than all non-null values. -
compare
private static int compare(double a, double b, int missing) Compares the given values as documented inDouble.compareTo(Double)
except in the handling of zero and NaN values.- The
missing
argument tells whether NaN values shall be considered smaller (-1) or greater (+1) than all non-NaN values. - Positive and negative zeros are considered equal.
- The
-
best
Returns the object associated to the largest area found so far.- Returns:
- the object associated to the largest area found so far, or
null
.
-