Package org.apache.sis.storage

Class CoverageQuery

java.lang.Object
org.apache.sis.storage.Query
org.apache.sis.storage.CoverageQuery
All Implemented Interfaces:
Serializable, Cloneable
public class CoverageQuery extends Query implements Cloneable, Serializable
Definition of filtering to apply for fetching a subset of GridCoverageResource. This query allows requesting a subset of the coverage domain and the range.

Terminology

This class uses relational database terminology for consistency with generic queries:
  • A selection is a filter choosing the cells or pixels to include in the subset. In this context, the selection is the coverage domain.
  • A projection (not to be confused with map projection) is the set of sample values to keep. In this context, the projection is the coverage range (i.e. set of sample dimensions).

Optional values

All aspects of this query are optional and initialized to "none". Unless otherwise specified, all methods accept a null argument or can return a null value, which means "none".
Since:
1.1
Version:
1.2
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private GridGeometry
    domain
    Desired grid extent and resolution, or null for reading the whole domain.
    private int[]
    range
    0-based indices of sample dimensions to read, or null for reading them all.
    private String[]
    rangeNames
    The range specified by names instead of indices.
    private static final long
    serialVersionUID
    For cross-version compatibility.
    private int
    sourceDomainExpansion
    Number of additional cells to read on each border of the source grid coverage.

  • Constructor Summary

    Constructors
    Constructor
    Description
    CoverageQuery()
    Creates a new query performing no filtering.

  • Method Summary

    Modifier and Type
    Method
    Description
    private static void
    append(StringBuffer sb, AngleFormat f, Angle start, Angle end)
    Formats a range of longitude or latitude values in the pseudo-SQL statement.
    CoverageQuery
    clone()
    Returns a clone of this query.
    boolean
    equals(Object obj)
    Compares this query with the given object for equality.
    protected GridCoverageResource
    execute(GridCoverageResource source)
    Applies this query on the given coverage resource.
    int[]
    getProjection()
    Returns the indices of samples dimensions to read, or null if there is no filtering on range.
    GridGeometry
    getSelection()
    Returns the desired grid extent and resolution.
    int
    getSourceDomainExpansion()
    Returns the number of additional cells to read on each border of the source grid coverage.
    int
    hashCode()
    Returns a hash code value for this query.
    private void
    namesToIndices(GridCoverageResource source)
    Converts the sample dimension names to sample dimension indices.
    void
    setProjection(int... range)
    Sets the indices of samples dimensions to read (the coverage range).
    void
    setProjection(String... range)
    Sets the sample dimensions to read by their names.
    void
    setSelection(GridGeometry domain)
    Sets the desired grid extent and resolution.
    void
    setSelection(org.opengis.geometry.Envelope domain)
    Sets the approximate area of cells or pixels to include in the subset.
    void
    setSourceDomainExpansion(int margin)
    Sets a number of additional cells to read on each border of the source grid coverage.
    String
    toString()
    Returns a textual representation of this query for debugging purposes.

    Methods inherited from class java.lang.Object

    finalize, getClass, notify, notifyAll, wait, wait, wait

  • Field Details

    • serialVersionUID

      private static final long serialVersionUID
      For cross-version compatibility.
      See Also:

    • domain

      private GridGeometry domain
      Desired grid extent and resolution, or null for reading the whole domain. This is the "selection" in query terminology.

    • range

      private int[] range
      0-based indices of sample dimensions to read, or null for reading them all. This is the "projection" (not to be confused with map projection) in query terminology.

    • rangeNames

      private String[] rangeNames
      The range specified by names instead of indices. At most one of range and rangeNames shall be non-null.

    • sourceDomainExpansion

      private int sourceDomainExpansion
      Number of additional cells to read on each border of the source grid coverage. If non-zero, this property expands the domain to be read by an amount specified in unit of cells of the image to be read. Those cells do not necessarily have the same size than the cells of domain.getExtent().

  • Constructor Details

    • CoverageQuery

      public CoverageQuery()
      Creates a new query performing no filtering.

  • Method Details

    • setSelection

      public void setSelection(org.opengis.geometry.Envelope domain)
      Sets the approximate area of cells or pixels to include in the subset. This convenience method creates a grid geometry containing only the given envelope. Note that the given envelope is approximate: Coverages may expand the envelope to an integer amount of tiles.
      Specified by:
      setSelection in class Query
      Parameters:
      domain - the approximate area of interest, or null if none.

    • setSelection

      public void setSelection(GridGeometry domain)
      Sets the desired grid extent and resolution. The given domain is approximate: Coverages may use a different resolution and expand the envelope to an integer amount of tiles.
      Parameters:
      domain - desired grid extent and resolution, or null for reading the whole domain.

    • getSelection

      public GridGeometry getSelection()
      Returns the desired grid extent and resolution. This is the value set by the last call to setSelection(GridGeometry).
      Note on terminology: "selection" is the generic term used in queries for designating a subset of feature instances. In a grid coverage, feature instances are cells or pixels. So this concept maps to the coverage domain.
      Returns:
      desired grid extent and resolution, or null for reading the whole domain.

    • setProjection

      public void setProjection(String... range)
      Sets the sample dimensions to read by their names.
      Specified by:
      setProjection in class Query
      Parameters:
      range - sample dimensions to retrieve, or null to retrieve all properties.
      Throws:
      IllegalArgumentException - if a sample dimension is duplicated.

    • setProjection

      public void setProjection(int... range)
      Sets the indices of samples dimensions to read (the coverage range). A null value means to read all sample dimensions (no filtering on range). If non-null, then the range array shall contain at least one element, all elements must be positive and no value can be duplicated.
      Parameters:
      range - 0-based indices of sample dimensions to read, or null for reading them all.
      Throws:
      IllegalArgumentException - if the given array is empty or contains negative or duplicated values.

    • getProjection

      public int[] getProjection()
      Returns the indices of samples dimensions to read, or null if there is no filtering on range. If non-null, the returned array shall never be empty.
      Note on terminology: "projection" (not to be confused with map projection) is the generic term used in queries for designating a subset of feature properties retained in each feature instances. In a coverage, this concept maps to the coverage range.
      Returns:
      0-based indices of sample dimensions to read, or null for reading them all.

    • namesToIndices

      private void namesToIndices(GridCoverageResource source) throws DataStoreException
      Converts the sample dimension names to sample dimension indices. This conversion depends on the resource on which the query will be applied.
      Parameters:
      source - the resource for which to to the conversion.
      Throws:
      DataStoreException

    • setSourceDomainExpansion

      public void setSourceDomainExpansion(int margin)
      Sets a number of additional cells to read on each border of the source grid coverage. If non-zero, this property expands the domain to be read by the specified margin.

      Unit of measurement

      The parameter value is a number of cells in the domain argument specified in a read operation. If no domain is specified at read time, then this is a number of cells in the full image to be read from the resource. Cells are counted after subsampling, e.g. cells are twice bigger if a subsampling of 2 is applied. Those cells do not necessarily have the same size than the cells of the domain of this query.

      Use case

      At reading time it may be necessary to add a margin to the coverage extent. This margin is used when the user knows that an image processing operation will need to iterate over a little bit more data than the area of interest. For example, the bilinear interpolation uses a 2×2 pixels window.
      Parameters:
      margin - read margin, which must be zero or positive.

    • getSourceDomainExpansion

      public int getSourceDomainExpansion()
      Returns the number of additional cells to read on each border of the source grid coverage. This is the value sets by the last call to setSourceDomainExpansion(int).
      Returns:
      read margin, zero or positive.

    • execute

      protected GridCoverageResource execute(GridCoverageResource source) throws DataStoreException
      Applies this query on the given coverage resource. This method is invoked by the default implementation of GridCoverageResource.subset(Query).
      Parameters:
      source - the coverage resource to filter.
      Returns:
      a view over the given coverage resource containing only the given domain and range.
      Throws:
      DataStoreException - if an error occurred during creation of the subset.
      Since:
      1.2
      See Also:

    • clone

      public CoverageQuery clone()
      Returns a clone of this query.
      Overrides:
      clone in class Object
      Returns:
      a clone of this query.

    • hashCode

      public int hashCode()
      Returns a hash code value for this query.
      Overrides:
      hashCode in class Object
      Returns:
      a hash value for this query.

    • equals

      public boolean equals(Object obj)
      Compares this query with the given object for equality.
      Overrides:
      equals in class Object
      Parameters:
      obj - the object to compare with this query.
      Returns:
      whether the two objects are equal.

    • toString

      public String toString()
      Returns a textual representation of this query for debugging purposes. The default implementation returns a string that looks like an SQL Select query.
      Overrides:
      toString in class Object
      Returns:
      textual representation of this query.

    • append

      private static void append(StringBuffer sb, AngleFormat f, Angle start, Angle end)
      Formats a range of longitude or latitude values in the pseudo-SQL statement. This is a helper method for toString().