Class MultiResolutionCoverageLoader

java.lang.Object
org.apache.sis.internal.map.coverage.MultiResolutionCoverageLoader

public class MultiResolutionCoverageLoader extends Object
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 the GridCoverageResource 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

    Fields
    Modifier and Type
    Field
    Description
    private final org.opengis.geometry.Envelope
    The area of interest in any CRS (transformations will be applied as needed), or null 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 from DEFAULT_SIZE and DEFAULT_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, or null 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).
    The resource from which to read grid coverages.
  • Constructor Summary

    Constructors
    Constructor
    Description
    MultiResolutionCoverageLoader(GridCoverageResource resource, org.opengis.geometry.Envelope domain, int[] range)
    Creates a new loader of grid coverages from the given resource.
  • Method Summary

    Modifier and Type
    Method
    Description
    private 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).
    getOrLoad(int level)
    Returns the coverage at the given level if it is present in the cache, or loads and caches it otherwise.
    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.
    Returns a string representation of this loader for debugging purpose.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
  • Field Details

    • DEFAULT_SIZE

      private static final int DEFAULT_SIZE
      Approximate size in pixels of the pyramid level having coarsest resolution. This is used by defaultResolutions(GridGeometry, double[]) when no resolution levels are explicitly given by the resource.
      See Also:
    • DEFAULT_SCALE_LOG

      private static final int DEFAULT_SCALE_LOG
      Value 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_LEVELS
      Arbitrary number of levels if we cannot compute it from DEFAULT_SIZE and DEFAULT_SCALE_LOG. Reminder: the multiplication factor between two levels is 2^3, so the resolution goes down very fast.
      See Also:
    • resource

      public final GridCoverageResource resource
      The resource from which to read grid coverages.
    • resolutionSquared

      private final double[][] resolutionSquared
      Squares of resolution at each pyramid level, from finest (smaller numbers) to coarsest (largest numbers). This is same same order than GridCoverageResource.getResolutions(). For a given level, the array resolutionSquared[level] gives the squares of the resolution for each CRS dimension.
    • coverages

      private final Reference<GridCoverage>[] coverages
      The weak or soft references to coverages for each pyramid level. The array length is at least 1, even if resolutionSquared is empty. Accesses to this array should be synchronized on coverages.
    • areaOfInterest

      private final org.opengis.geometry.Envelope areaOfInterest
      The area of interest in any CRS (transformations will be applied as needed), or null for not restricting the coverage to a sub-area.
    • readRanges

      private final int[] readRanges
      0-based indices of sample dimensions to read, or null 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, or null for no sub-area.
      range - 0-based indices of sample dimensions to read, or null for all.
      Throws:
      DataStoreException - if an error occurred while querying the resource for resolutions.
  • Method Details

    • defaultResolutions

      private static double[][] defaultResolutions(GridGeometry gg, double[] base)
      Computes default resolutions starting from the given finest level. This method uses a scale factor determined by DEFAULT_SCALE_LOG between each level. The coarsest level will have a size of approximately 512 pixels.
      Parameters:
      envelope - bounding box of the coverage in units of the coverage CRS.
      base - resolution of the finest level.
      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, or null 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 if dataToObjective 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

      public final GridCoverage getOrLoad(int level) throws DataStoreException
      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

      public final GridCoverage getOrLoad(GridGeometry domain, int[] range) throws DataStoreException
      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, or null for reading the whole domain.
      range - 0-based indices of sample dimensions to read, or null 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

      public String 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.
      Overrides:
      toString in class Object
      Returns:
      a string representation of this loader.
    • magnitude

      private double magnitude(int level)
      Returns the magnitude of resolution at the given level.