Package org.apache.sis.storage
Class CoverageQuery
- All Implemented Interfaces:
Serializable
,Cloneable
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:
Defined in the sis-storage
module
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionclone()
Returns a clone of this query.boolean
Compares this query with the given object for equality.protected GridCoverageResource
execute
(GridCoverageResource source) Applies this query on the given coverage resource.int[]
Returns the indices of samples dimensions to read, ornull
if there is no filtering on range.Returns the desired grid extent and resolution.int
Returns the number of additional cells to read on each border of the source grid coverage.int
Returns a hash code value for this query.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.Returns a textual representation of this query for debugging purposes.
-
Constructor Details
-
CoverageQuery
public CoverageQuery()Creates a new query performing no filtering.
-
-
Method Details
-
setSelection
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 classQuery
- Parameters:
domain
- the approximate area of interest, ornull
if none.
-
setSelection
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, ornull
for reading the whole domain.
-
getSelection
Returns the desired grid extent and resolution. This is the value set by the last call tosetSelection(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
Sets the sample dimensions to read by their names.- Specified by:
setProjection
in classQuery
- Parameters:
range
- sample dimensions to retrieve, ornull
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). Anull
value means to read all sample dimensions (no filtering on range). If non-null, then therange
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, ornull
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, ornull
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 thedomain
to be read by the specified margin.Unit of measurement
The parameter value is a number of cells in thedomain
argument specified in a read operation. If nodomain
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 thedomain 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 tosetSourceDomainExpansion(int)
.- Returns:
- read margin, zero or positive.
-
execute
Applies this query on the given coverage resource. This method is invoked by the default implementation ofGridCoverageResource.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
Returns a clone of this query. -
hashCode
public int hashCode()Returns a hash code value for this query. -
equals
Compares this query with the given object for equality. -
toString
Returns a textual representation of this query for debugging purposes. The default implementation returns a string that looks like an SQL Select query.
-