- All Known Subinterfaces:
WritableGridCoverageResource
- All Known Implementing Classes:
AbstractGridCoverageResource
- The function input is a position valid in the coverage domain. In the particular case of
GridCoverage
, the domain is described by a grid geometry. - The function output is a record of values in the coverage range. In the particular case of
GridCoverage
, the range is described by a list of sample dimensions.
Aggregate
if a single file can provide many rasters.- Since:
- 1.0
-
Method Summary
Modifier and TypeMethodDescriptionReturns the valid extent of grid coordinates together with the conversion from those grid coordinates to real world coordinates.default RasterLoadingStrategy
Returns an indication about when the "physical" loading of raster data will happen.default List
<double[]> Returns the preferred resolutions (in units of CRS axes) for read operations in this data store.Returns the ranges of sample values together with the conversion from samples to real values.read
(GridGeometry domain, int... ranges) Loads a subset of the grid coverage represented by this resource.default boolean
setLoadingStrategy
(RasterLoadingStrategy strategy) Sets the preferred strategy about when to do the "physical" loading of raster data.default GridCoverageResource
Requests a subset of the coverage.Methods inherited from interface DataSet
getEnvelope
Methods inherited from interface Resource
addListener, getIdentifier, getMetadata, removeListener
-
Method Details
-
getGridGeometry
Returns the valid extent of grid coordinates together with the conversion from those grid coordinates to real world coordinates. A grid geometry contains the following information:- The minimum and maximum grid coordinates as integers (the Grid Extent). The minimum coordinates are typically (0,0, …, 0) but not necessarily.
- The minimum and maximum "real world" coordinates (the Envelope). Those coordinates are typically, but not necessarily, latitudes and longitudes or projected coordinates, together with altitudes and dates.
- A description of the datum and axes of above "real world" coordinates (the Coordinate Reference System).
- The conversion from grid coordinates to "real world" coordinates. This conversion is often, but not necessarily, a linear relationship. Axis order or direction may be changed by the conversion. For example, row indices may be increasing toward down while latitude coordinates are increasing toward up.
- An estimation of grid resolution for each "real world" axis.
read(null).getGridGeometry()
. However, the grid geometry returned by this method is allowed to be only approximate if computing accurate information would be prohibitively expensive, or if the grid geometry depends on the exact argument value given to theread(…)
method. At least, the number of dimensions should match.- Returns:
- extent of grid coordinates together with their mapping to "real world" coordinates.
- Throws:
DataStoreException
- if an error occurred while reading definitions from the underlying data store.- See Also:
-
getSampleDimensions
Returns the ranges of sample values together with the conversion from samples to real values. Sample dimensions contain the following information:- The range of valid sample values, typically but not necessarily as positive integers.
- A transfer function for converting sample values to real values, for example measurements of a geophysics phenomenon. The transfer function is typically defined by a scale factor and an offset, but is not restricted to such linear equations.
- The units of measurement of "real world" values after their conversions from sample values.
- The sample values reserved for missing values.
The list returned by this method should be equal to the list returned by
read(null).getSampleDimensions()
. However, the sample dimensions returned by this method is allowed to be only approximate if computing accurate information would be prohibitively expensive, or if the sample dimensions depend on thedomain
argument (area of interest) given to theread(…)
method. At least, the number of sample dimensions should match.- Returns:
- ranges of sample values together with their mapping to "real values".
- Throws:
DataStoreException
- if an error occurred while reading definitions from the underlying data store.- See Also:
-
getResolutions
Returns the preferred resolutions (in units of CRS axes) for read operations in this data store. If the storage supports pyramid, then the list should contain the resolution at each pyramid level ordered from finest (smallest numbers) to coarsest (largest numbers) resolution. Otherwise the list contains a single element which is the grid geometry resolution, or an empty list if no resolution is applicable to the coverage (e.g. because non-constant).Each element shall be an array with a length equals to the number of CRS dimensions. In each array, value at index i is the cell size along CRS dimension i in units of the CRS axis i.
Note that arguments given to
subset(…)
orread(…)
methods are not constrained to the resolutions returned by this method. Those resolutions are only hints about resolution values where read operations are likely to be more efficient.- Returns:
- preferred resolutions for read operations in this data store, or an empty array if none.
- Throws:
DataStoreException
- if an error occurred while reading definitions from the underlying data store.- Since:
- 1.2
- See Also:
-
subset
default GridCoverageResource subset(Query query) throws UnsupportedQueryException, DataStoreException Requests a subset of the coverage. The filtering can be applied in two aspects:- The returned
GridCoverageResource
may contain a smaller domain (grid extent). - The returned
GridCoverageResource
may contain a smaller range (less sample dimensions).
The returned subset may be a view of this set, i.e. changes in this
GridCoverageResource
may be reflected immediately on the returned subset (and conversely), but not necessarily. However, the returned subset may not have the same capabilities as thisGridCoverageResource
. In particular, write operations may become unsupported after complex queries.Default implementation
The default implementation delegates toCoverageQuery.execute(GridCoverageResource)
if the given query is an instance ofCoverageQuery
, or throwsUnsupportedQueryException
otherwise.- Parameters:
query
- definition of domain (grid extent) and range (sample dimensions) filtering applied at reading time.- Returns:
- resulting coverage resource (never
null
). - Throws:
UnsupportedQueryException
- if the given query is not valid for thisGridCoverageResource
. This includes query validation errors.DataStoreException
- if another error occurred while processing the query.- Since:
- 1.1
- See Also:
- The returned
-
read
Loads a subset of the grid coverage represented by this resource. If a non-null grid geometry is specified, then this method will try to return a grid coverage matching the given grid geometry on a best-effort basis; the coverage actually returned may have a different resolution, cover a different area in a different CRS, etc. The general contract is that the returned coverage should not contain less data than a coverage matching exactly the given geometry.The returned coverage shall contain the exact set of sample dimensions specified by the
range
argument, in the specified order (the "best-effort basis" flexibility applies only to the grid geometry, not to the ranges). Allranges
values shall be between 0 inclusive andgetSampleDimensions().size()
exclusive, without duplicated values.While this method name suggests an immediate reading, some implementations may defer the actual reading at a later stage.
- Parameters:
domain
- desired grid extent and resolution, ornull
for reading the whole domain.ranges
- 0-based indices of sample dimensions to read, ornull
or an empty sequence for reading them all.- Returns:
- the grid coverage for the specified domain and ranges.
- Throws:
DisjointExtentException
- if the given domain does not intersect the resource extent.IllegalArgumentException
- if the given domain or ranges are invalid for another reason.DataStoreException
- if an error occurred while reading the grid coverage data.
-
getLoadingStrategy
Returns an indication about when the "physical" loading of raster data will happen. This is the strategy actually applied by this resource implementation, not necessarily the strategy given in the last call tosetLoadingStrategy(…)
.The default strategy is to load raster data at
read(…)
method invocation time.- Returns:
- current raster data loading strategy for this resource.
- Throws:
DataStoreException
- if an error occurred while fetching data store configuration.- Since:
- 1.1
-
setLoadingStrategy
Sets the preferred strategy about when to do the "physical" loading of raster data. Implementations are free to ignore this parameter or to replace the given strategy by the closest alternative that this resource can support.- Parameters:
strategy
- the desired strategy for loading raster data.- Returns:
true
if the given strategy has been accepted, orfalse
if this implementation replaced the given strategy by an alternative.- Throws:
DataStoreException
- if an error occurred while setting data store configuration.- Since:
- 1.1
-