Class TiledGridCoverage

Object
BandedCoverage
GridCoverage
TiledGridCoverage
public abstract class TiledGridCoverage extends GridCoverage
Base class of grid coverages that are read from resources with data stored in tiles. This grid coverage may represent only a subset of the coverage resource. Tiles are read from the storage when first needed, then cached using weak references. The reading of tiles is done by the read­Tiles(Tile­Iterator) method, which must be defined by subclasses.

Cell coordinates

When there is no subsampling, this coverage uses the same cell coordinates as the originating resource. When there is a subsampling, cell coordinates in this coverage are divided by the subsampling factors. Conversions can be done by coverage­To­Resource­Coordinate(long, int).

Design note: Tiled­Grid­Coverage uses the same cell coordinates as the originating Tiled­Grid­Coverage­Resource (when no subsampling) because those two classes use long integers. There is no integer overflow to avoid, contrary to tile matrix indices described below.

Tile matrix coordinate (TMC)

In each Tiled­Grid­Coverage, indices of tiles starts at (0, 0, …). This class does not use the same tile indices as the coverage resource in order to avoid integer overflow. Each Tiled­Grid­Coverage instance uses its own, independent, Tile Matrix Coordinates (TMC).
Since:
1.7

  • Field Details

  • Constructor Details

  • Method Details

    • getIdentifier

      protected abstract GenericName getIdentifier()
      Returns a unique name that identifies this coverage. The name shall be unique in the Tile­Matrix­Set.
      Returns:
      an human-readable identification of this coverage.

    • getContentPath

      protected Path getContentPath(long... tileIndices)
      Returns the path to the content of the specified data, or null if none or unknown. If tile­Indices is null, then this method returns a path to the content of the whole coverage (if known). Otherwise, this method returns a path to the content of the tile at the specified indices.

      The default implementation returns null.

      Parameters:
      tile­Indices - indices of the tile, or null for the whole coverage.
      Returns:
      path to the content of the coverage (if tile­Indices was null) or to the specified tile, or null if none or unknown.
      See Also:

    • getTileSize

      protected final long getTileSize(int dimension)
      Returns the size of all tiles in the domain of this Tiled­Grid­Coverage, without sub-sampling. This is usually the same size as the tiles in the storage which is read by Tiled­Grid­Coverage­Resource, but not necessarily. It may be larger if the Tiled­Grid­Coverage­Resource subclass decided to coalesce many real tiles into larger virtual tiles, or it may be smaller when reading a sub-region of an effectively untiled coverage.
      Parameters:
      dimension - dimension for which to get tile size.
      Returns:
      tile size in the given dimension, without clipping and subsampling.

    • getSubsampling

      protected final long getSubsampling(int dimension)
      Returns the subsampling in the given dimension.
      Parameters:
      dimension - dimension for which to get subsampling.
      Returns:
      subsampling as a value ≥ 1.

    • coverageToResourceCoordinate

      protected final long coverageToResourceCoordinate(long coordinate, int dimension)
      Converts a cell coordinate of this coverage to the Tiled­Grid­Coverage­Resource coordinate space. This method removes the subsampling effect, i.e. returns the coordinate that we would have if this coverage was at full resolution. The result is the given coordinate value unchanged when there is no subsampling.
      Parameters:
      coordinate - coordinate in this Tiled­Grid­Coverage domain.
      dimension - the dimension of the coordinate to convert.
      Returns:
      coordinate in the Tiled­Grid­Coverage­Resource domain with no subsampling applied.
      Throws:
      Arithmetic­Exception - if the coordinate cannot be represented as a 64 bits integer.

    • resourceToCoverageCoordinate

      protected final long resourceToCoverageCoordinate(long coordinate, int dimension)
      Converts a cell coordinate from the Tiled­Grid­Coverage­Resource to this coverage coordinate space. This method is the converse of coverage­To­Resource­Coordinate(long, int). The result is the given coordinate value unchanged when there is no subsampling. If there is a subsampling, the returned value is rounded toward negative infinity.
      Parameters:
      coordinate - coordinate in the Tiled­Grid­Coverage­Resource domain.
      dimension - the dimension of the coordinate to convert.
      Returns:
      coordinates in this subsampled Tiled­Grid­Coverage domain.
      Throws:
      Arithmetic­Exception - if the coordinate cannot be represented as a 64 bits integer.

    • getPixelsPerElement

      protected final int getPixelsPerElement()
      Returns the number of pixels in a single bank element. This is usually 1, except for Multi­Pixel­Packed­Sample­Model which packs many pixels in a single bank element. This value is a power of 2 according Multi­Pixel­Packed­Sample­Model specification.

      Design note

      This is value is the number of pixels per element, not samples per element. This distinction is important in the case of Single­Pixel­Packed­Sample­Model, for which this method returns 1 (contrary to the number of samples per element which would be greater than 1).
      Returns:
      number of pixels in a single bank element. This is often 1.
      See Also:

    • bidimensional

      protected final Rectangle bidimensional(GridExtent extent)
      Returns the two-dimensional slice of the given grid extent, converted to 32-bits integers. By default, the x axis is the grid dimension at index 0 and the y axis is the grid dimension at index 1. Other dimensions are ignored.
      Parameters:
      extent - the grid extent to slice, or null.
      Returns:
      two-dimensional slice of the given extent, or null if the given extent was null.
      Throws:
      Arithmetic­Exception - if the extent exceeds the capacity of 32-bits integers.

    • render

      public RenderedImage render(GridExtent sliceExtent)
      Returns a two-dimensional slice of grid data as a rendered image. The default implementation creates a Tiled­Grid­Coverage​.Tile­Iterator over the region specified in argument, then reads the tiles and stores the result in a rendered image.
      Specified by:
      render in class Grid­Coverage
      Parameters:
      slice­Extent - a subspace of this grid coverage, or null for the whole image.
      Returns:
      the grid slice as a rendered image. Image location is relative to slice­Extent.
      Throws:
      Mismatched­Dimension­Exception - if the given extent does not have the same number of dimensions as this coverage.
      Subspace­Not­Specified­Exception - if the given argument is not sufficient for reducing the grid to a two-dimensional slice.
      Disjoint­Extent­Exception - if the given extent does not intersect this grid coverage.
      Cannot­Evaluate­Exception - if this method cannot produce the rendered image for another reason.

    • readTiles

      protected abstract Raster[] readTiles(TiledGridCoverage.TileIterator iterator) throws Exception
      Returns all tiles in the given area of interest. Tile indices are relative to this Tiled­Grid­Coverage: (0,0) is the tile in the upper-left corner of this Tiled­Grid­Coverage (not necessarily the upper-left corner of the image in the Tiled­Grid­Coverage­Resource).

      The Raster​.get­Min­X() and get­Min­Y() coordinates of returned rasters shall start at the values given by Tiled­Grid­Coverage​.Tile­Iterator​.get­Tile­Origin(int). Each tile in the returned array shall be stored at the index given by Tiled­Grid­Coverage​.AOI​.get­Tile­Index­In­Result­Array().

      The x axis of the raster shall be the grid dimension specified by x­Dimension. Likewise, the y axis shall be the dimension specified by y­Dimension. These dimensions are usually 0 and 1 respectively.

      This method must be thread-safe. It is implementer responsibility to ensure synchronization, for example using Abstract­Resource​.get­Synchronization­Lock().

      Parameters:
      iterator - an iterator over the tiles that intersect the Area Of Interest specified by user.
      Returns:
      tiles decoded from the Tiled­Grid­Coverage­Resource.
      Throws:
      Exception - if the tile cannot be created. There is too many possible exceptions for listing all types, but the main ones are IOException for I/O errors and various Runtime­Exception subtypes for Java2D errors.
      See Also: