Module org.apache.sis.storage
Package org.apache.sis.storage

# Class CoverageQuery

Object
Query
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
See Also:
  - Serialized Form

- ## Constructor Summary

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

- ## Method Summary

  Modifier and Type
  Method
  Description
  `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.
  `Function<GridGeometry,DimensionalityReduction>`
  `getAxisSelection()`
  Returns the dimensionality reduction to apply on coverage domain.
  `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.
  `void`
  `setAxisSelection(Function<GridGeometry,DimensionalityReduction> reduction)`
  Requests dimensionality reduction by selecting or removing specified domain axes.
  `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(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 Object

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

- ## Constructor Details

  - ### CoverageQuery

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

- ## Method Details

  - ### setSelection

    public void setSelection(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.

    If a dimensionality reduction is applied, the specified envelope can be either the full envelope (with all dimensions) or an envelope with reduced dimensions.

    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.

    If a dimensionality reduction is applied, the specified domain can be either the full domain (with all dimensions) or a domain with reduced dimensions.

    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.

  - ### setAxisSelection

    public void setAxisSelection(Function<GridGeometry,DimensionalityReduction> reduction)
    Requests dimensionality reduction by selecting or removing specified domain axes. The axes to keep or remove are specified by a `DimensionalityReduction` object, which works with indices of grid extent axes. It may be the same indices than the indices of the CRS axes which will be kept or removed, but not necessarily. It is the `Function` responsibility to map CRS dimensions to grid dimensions if desired.

    Example 1: automatically reduce a grid coverage dimensionality by removing all grid axes with an extent size of 1.

        query.setAxisSelection(DimensionalityReduction::reduce);

    Example 2: take a two-dimensional slice by keeping the two first axes and selecting the median grid coordinate (0.5 ratio) in all other dimensions.

        query.setAxisSelection((domain) -> DimensionalityReduction.select2D(domain).withSliceByRatio(0.5));

    Parameters:
      `reduction` - the function to apply for obtaining a dimensionality reduction from a grid coverage, or `null` if none.
    Since:
      1.4
    See Also:
      - `GridCoverageProcessor​.selectGridDimensions(GridCoverage, int...)`
      - `GridCoverageProcessor​.removeGridDimensions(GridCoverage, int...)`
      - `GridCoverageProcessor​.reduceDimensionality(GridCoverage)`

  - ### getAxisSelection

    public Function<GridGeometry,DimensionalityReduction> getAxisSelection()
    Returns the dimensionality reduction to apply on coverage domain. This is the value specified in the last call to `setAxisSelection(Function)`.
    Returns:
      the function to apply for obtaining a dimensionality reduction from a grid coverage, or `null` if none.
    Since:
      1.4

  - ### 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.

  - ### 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 while fetching information from the source.
      `IllegalGridGeometryException` - if a dimensionality reduction was requested but cannot be applied.
    Since:
      1.2
    See Also:
      - `GridCoverageResource​.subset(CoverageQuerty)`
      - `FeatureQuery​.execute(FeatureSet)`

  - ### 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.