Package org.apache.sis.internal.referencing

Class ExtentSelector<T>

java.lang.Object
org.apache.sis.internal.referencing.ExtentSelector<T>
Type Parameters:
T - the type of object to be selected.
public final class ExtentSelector<T> extends Object
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:
  1. Object having largest intersection with the time of interest (TOI) is selected.
  2. If two or more candidates have the same intersection with TOI, then the one with less "overtime" (time outside TOI) is selected.
  3. 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:
  1. Largest intersection with the area of interest (AOI) is selected.
  2. 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.
  3. If two or more candidates are considered equal after above criteria, the one best centered on the AOI is selected.
  4. 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.

Usage

Example:
Since:
0.4
Version:
1.3
Author:
Martin Desruisseaux (Geomatys)

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    boolean
    alternateOrdering
    Whether to use an alternate conditions order where the time center criterion is tested last.

  • Constructor Summary

    Constructors
    Constructor
    Description
    ExtentSelector(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 Type
    Method
    Description
    T
    best()
    Returns the object associated to the largest area found so far.
    void
    evaluate(org.opengis.metadata.extent.Extent domain, T object)
    Evaluates the given extent against the criteria represented by this ExtentSelector.
    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 this ExtentSelector.
    final org.opengis.metadata.extent.GeographicBoundingBox
    getAreaOfInterest()
    Returns the area of interest.
    final Instant[]
    getTimeOfInterest()
    Returns the time of interest as an array of length 2, or null if none.
    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).

    Methods inherited from class java.lang.Object

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

  • Field Details

    • alternateOrdering

      public boolean alternateOrdering
      Whether to use an alternate conditions order where the time center criterion is tested last. This flag can be set to true 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.

  • Constructor Details

    • ExtentSelector

      public ExtentSelector(org.opengis.metadata.extent.GeographicBoundingBox aoi, Instant[] toi)
      Creates a selector for the given area and time of interest.
      Parameters:
      aoi - the area of interest, or null if unbounded.
      toi - the time of interest, or null 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, or null 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 if best() returned null. 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 returns false, except for invoking this setExtentOfInterest(…) method again with different values until this method returns true.

      Parameters:
      domain - the area and time of interest, or null if none.
      aoi - second area of interest as a bounding box, or null if none.
      toi - second time of interest as a an array of length 2, 1 or 0, or null. 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 with aoi and toi 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

      public final Instant[] getTimeOfInterest()
      Returns the time of interest as an array of length 2, or null if none.
      Returns:
      the start time and end time of interest, or null if none.

    • setTimeGranularity

      public final void setTimeGranularity(Duration resolution)
      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, or null if none.
      Throws:
      IllegalArgumentException - if the given resolution is zero or negative.

    • evaluate

      public void evaluate(org.opengis.metadata.extent.Extent domain, T object)
      Evaluates the given extent against the criteria represented by this ExtentSelector. See class javadoc for a list of criteria and the order in which they are applied. Implementation delegates to evaluate(GeographicBoundingBox, Instant, Instant, Object).
      Parameters:
      domain - the extent to evaluate, or null 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 this ExtentSelector. See class javadoc for a list of criteria and the order in which they are applied.
      Parameters:
      bbox - the geographic extent of object, or null if none.
      startTime - start time of object, or null if none (unbounded).
      endTime - end time of object, or null if none (unbounded).
      object - a user object associated to the given extent.

    • best

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