Class MultiResolutionCoverageLoader
java.lang.Object
org.apache.sis.internal.map.coverage.MultiResolutionCoverageLoader
A helper class for reading
GridCoverage
instances at various resolutions.
The resolutions are inferred from GridCoverageResource.getResolutions()
,
using default values if necessary. The objective CRS does not need to be the same
than the coverage CRS, in which case transformations are applied at the point in
the center of the display bounds.
Multi-threading
Instances of this class are immutable (except for the cache) and safe for use by multiple threads. However, it assumes that theGridCoverageResource
given to the constructor is also thread-safe;
this class does not synchronize accesses to the resource (because it may be used outside this class anyway).- Since:
- 1.2
- Version:
- 1.2
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate final org.opengis.geometry.Envelope
The area of interest in any CRS (transformations will be applied as needed), ornull
for not restricting the coverage to a sub-area.private final Reference<GridCoverage>[]
The weak or soft references to coverages for each pyramid level.private static final int
Arbitrary number of levels if we cannot compute it fromDEFAULT_SIZE
andDEFAULT_SCALE_LOG
.private static final int
Value of log₂(rₙ₊₁/rₙ) where rₙ is the resolution at a level and rₙ₊₁ is the resolution at the coarser level.private static final int
Approximate size in pixels of the pyramid level having coarsest resolution.private final int[]
0-based indices of sample dimensions to read, ornull
or an empty sequence for reading them all.private final double[][]
Squares of resolution at each pyramid level, from finest (smaller numbers) to coarsest (largest numbers).final GridCoverageResource
The resource from which to read grid coverages. -
Constructor Summary
ConstructorsConstructorDescriptionMultiResolutionCoverageLoader
(GridCoverageResource resource, org.opengis.geometry.Envelope domain, int[] range) Creates a new loader of grid coverages from the given resource. -
Method Summary
Modifier and TypeMethodDescriptionprivate static double[][]
defaultResolutions
(GridGeometry gg, double[] base) Computes default resolutions starting from the given finest level.(package private) final int
findPyramidLevel
(org.opengis.referencing.operation.MathTransform dataToObjective, LinearTransform objectiveToDisplay, org.opengis.geometry.DirectPosition objectivePOI) Returns the pyramid level for a zoom defined by the given "objective to display" transform.(package private) final int
Returns the maximal level (the level with coarsest resolution).final GridCoverage
getOrLoad
(int level) Returns the coverage at the given level if it is present in the cache, or loads and caches it otherwise.final GridCoverage
getOrLoad
(GridGeometry domain, int[] range) If the a grid coverage for the given domain and range is in the cache, returns that coverage.private double
magnitude
(int level) Returns the magnitude of resolution at the given level.toString()
Returns a string representation of this loader for debugging purpose.
-
Field Details
-
DEFAULT_SIZE
private static final int DEFAULT_SIZEApproximate size in pixels of the pyramid level having coarsest resolution. This is used bydefaultResolutions(GridGeometry, double[])
when no resolution levels are explicitly given by the resource.- See Also:
-
DEFAULT_SCALE_LOG
private static final int DEFAULT_SCALE_LOGValue of log₂(rₙ₊₁/rₙ) where rₙ is the resolution at a level and rₙ₊₁ is the resolution at the coarser level. The usual value is 1, which means that there is a scale factor of 2 between each level. We use a higher value because if the resource did not declared a pyramid, reading coverages at low resolution may be as costly as high resolution. in that case, we want to reduce the number of read operations.- See Also:
-
DEFAULT_NUM_LEVELS
private static final int DEFAULT_NUM_LEVELSArbitrary number of levels if we cannot compute it fromDEFAULT_SIZE
andDEFAULT_SCALE_LOG
. Reminder: the multiplication factor between two levels is 2^3, so the resolution goes down very fast.- See Also:
-
resource
The resource from which to read grid coverages. -
resolutionSquared
private final double[][] resolutionSquaredSquares of resolution at each pyramid level, from finest (smaller numbers) to coarsest (largest numbers). This is same same order thanGridCoverageResource.getResolutions()
. For a given level, the arrayresolutionSquared[level]
gives the squares of the resolution for each CRS dimension. -
coverages
The weak or soft references to coverages for each pyramid level. The array length is at least 1, even ifresolutionSquared
is empty. Accesses to this array should be synchronized oncoverages
. -
areaOfInterest
private final org.opengis.geometry.Envelope areaOfInterestThe area of interest in any CRS (transformations will be applied as needed), ornull
for not restricting the coverage to a sub-area. -
readRanges
private final int[] readRanges0-based indices of sample dimensions to read, ornull
or an empty sequence for reading them all.
-
-
Constructor Details
-
MultiResolutionCoverageLoader
public MultiResolutionCoverageLoader(GridCoverageResource resource, org.opengis.geometry.Envelope domain, int[] range) throws DataStoreException Creates a new loader of grid coverages from the given resource. The loader assumes a pyramid with resolutions declared by the given resource if present, or computes default resolutions otherwise.- Parameters:
resource
- the resource from which to read grid coverages. Should be thread-safe.domain
- desired spatiotemporal region in any CRS, ornull
for no sub-area.range
- 0-based indices of sample dimensions to read, ornull
for all.- Throws:
DataStoreException
- if an error occurred while querying the resource for resolutions.
-
-
Method Details
-
defaultResolutions
Computes default resolutions starting from the given finest level. This method uses a scale factor determined byDEFAULT_SCALE_LOG
between each level. The coarsest level will have a size of approximately 512 pixels.- Parameters:
base
- resolution of the finest level.envelope
- bounding box of the coverage in units of the coverage CRS.- Returns:
- default resolutions from finest to coarsest. The first element is always
base
.
-
getLastLevel
final int getLastLevel()Returns the maximal level (the level with coarsest resolution). -
findPyramidLevel
final int findPyramidLevel(org.opengis.referencing.operation.MathTransform dataToObjective, LinearTransform objectiveToDisplay, org.opengis.geometry.DirectPosition objectivePOI) throws org.opengis.referencing.operation.TransformException Returns the pyramid level for a zoom defined by the given "objective to display" transform. Only the scale factors of the given transform will be considered; translations are ignored.- Parameters:
dataToObjective
- transform from data CRS to the CRS for rendering, ornull
if none.objectiveToDisplay
- transform used for rendering the coverage on screen.objectivePOI
- point where to compute resolution, in coordinates of objective CRS. Can be null ifdataToObjective
is null or linear.- Returns:
- pyramid level for the zoom determined by the given transform. Finest level is 0.
- Throws:
org.opengis.referencing.operation.TransformException
- if an error occurred while computing resolution from given transforms.
-
getOrLoad
Returns the coverage at the given level if it is present in the cache, or loads and caches it otherwise.- Parameters:
level
- pyramid level of the desired coverage.- Returns:
- the coverage at the specified level (never null).
- Throws:
DataStoreException
- if an error occurred while loading the coverage.
-
getOrLoad
If the a grid coverage for the given domain and range is in the cache, returns that coverage. Otherwise loads the coverage and eventually caches it. The caching happens only if the given domain and range are managed by this loader.- Parameters:
domain
- desired grid extent and resolution, ornull
for reading the whole domain.range
- 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 range.
- Throws:
DataStoreException
- if an error occurred while reading the grid coverage data.
-
toString
Returns a string representation of this loader for debugging purpose. Default implementation formats the resolution thresholds in a table with "cached" word after the level having a cached coverage. -
magnitude
private double magnitude(int level) Returns the magnitude of resolution at the given level.
-