Class TiledGridCoverageResource.Subset

Object
Subset
Enclosing class:
Tiled­Grid­Coverage­Resource
public class TiledGridCoverageResource.Subset extends Object
Parameters that describe the resource subset to be accepted by the Tiled­Grid­Coverage constructor. Instances of this class are created by a factory method and are short-lived, only for transferring information from Tiled­Grid­Coverage­Resource to Tiled­Grid­Coverage. This class does not perform I/O operations.
Since:
1.7
See Also:

  • Field Details

    • domain

      public final GridGeometry domain
      The sub-region extent, CRS and conversion from cell indices to CRS. This is the domain of the grid coverage to create. The CRS of this domain is the CRS of the base grid geometry, or a subset of it.

      This value is derived from the domain argument given to the constructor, but is not necessarily identical since it has been converted to the CRS of the base grid geometry.

      See Also:

    • ranges

      public final List<? extends SampleDimension> ranges
      Sample dimension for each image band, in the order requested by the user. The size of this list is the number of bands in the rendered image. This is the sample dimensions of the grid coverage to create.
      See Also:

  • Constructor Details

    • Subset

      protected Subset(GridGeometry domain, int[] range, ImageLayout tilingPreferences) throws DataStoreException
      Creates parameters for the given domain and range. The domain and range arguments given to this constructor are the arguments given to the Tiled­Grid­Coverage­Resource​.read(Grid­Geometry, int...) method. Instances are created by Tiled­Grid­Coverage­Resource​.describe­Subset(Grid­Geometry, int[]).

      Changes of tile size

      The tiling­Preferences argument is a hint used for choosing a virtual tile size. Virtual tiles may be used when the real tile size seems sub-optimal. For example, the tile may be unreasonably large (with "reasonably" defined by an arbitrary threshold), This case typically happens with large untiled images, where the whole image appears as a single tile. Depending on the loading strategy, requesting even a small sub-region may cause the reading of the whole tile, which may be slow or cause Out­Of­Memory­Error. A virtual tile size may also be used if, on the contrary, the tiles would become too small after the subsampling implied by the domain argument has been applied. In the latter case, tile coalescing may be desirable.

      If the tiling­Preferences argument is non-null, this constructor will use it for deriving a virtual tile size from the real tile size. If the virtual tile size is supported, it will be used by Tiled­Grid­Coverage. Otherwise, the real tile size is used.

      If the tiling­Preferences argument is null, this constructor does not derive a virtual tile size. The real tile size is unconditionally used.

      It is okay to specify Image­Layout​.DEFAULT for the tiling­Preferences argument. It is not necessary to tune the preferred tile size property because it is used only for targeting an order of magnitude when coalescing or dividing tiles. Note: the preferred size is the desired order of magnitude after subsampling has been applied.

      Parameters:
      domain - the domain argument specified by user in a call to Grid­Coverage­Resource​.read(…).
      range - the range argument specified by user in a call to Grid­Coverage­Resource​.read(…).
      tiling­Preferences - provider of tile size suggestions, or null if none.
      Throws:
      Arithmetic­Exception - if pixel indices exceed 64 bits integer capacity.
      Data­Store­Exception - if a call to Tiled­Grid­Coverage­Resource method failed.
      Raster­Format­Exception - if the sample model is not recognized.
      Illegal­Argument­Exception - if an error occurred in an operation such as creating the Sample­Model subset for selected bands.
      See Also:

  • Method Details

    • resource

      public final TiledGridCoverageResource resource()
      Returns the resource from which a coverage subset will be read.
      Returns:
      the enclosing resource.

    • getDimension

      public final int getDimension()
      Returns the number of dimensions of the grid.
      Returns:
      number of dimensions of the grid.

    • getVirtualTileSize

      public final long getVirtualTileSize(int dimension)
      Returns the size of tiles (or chunks) to read from the resource, ignoring sub-sampling. The virtual tile size may be larger or smaller than the real tile size if the resource can easily coalesce many tiles in a single read operation, or on the contrary if large tiles need to be divided into smaller tiles.
      Parameters:
      dimension - the dimension for which the virtual tile size is desired.
      Returns:
      the size of tiles (in pixels) to read from the resource.
      Throws:
      Index­Out­Of­Bounds­Exception - if dimension is not between 0 inclusive and get­Dimension() exclusive.
      See Also:

    • getImageTileSize

      public final int getImageTileSize(int dimension)
      Returns the size of the tiles in the rendered image to create. This is the virtual tile size with subsampling applied and clipped to the image size.
      Parameters:
      dimension - the dimension for which the image tile size is desired.
      Returns:
      the size of tiles (in pixels) of the image to create.
      Throws:
      Index­Out­Of­Bounds­Exception - if dimension is not between 0 inclusive and get­Dimension() exclusive.

    • getSubsampling

      public final long getSubsampling(int dimension)
      Returns the subsampling to apply along the specified dimension of the grid. The returned value is guaranteed equal or greater than 1.
      Parameters:
      dimension - the dimension for which the subsampling is desired.
      Returns:
      the subsampling to apply along the specified dimension.
      Throws:
      Index­Out­Of­Bounds­Exception - if dimension is not between 0 inclusive and get­Dimension() exclusive.

    • getSubsamplingOffset

      public final long getSubsamplingOffset(int dimension)
      Returns the offset of the first cell to read along the specified dimension of the grid. The value is guaranteed between 0 inclusive and get­Subsampling(i) exclusive. In the common case where no subsampling is applied, the offset is always zero.
      Parameters:
      dimension - the dimension for which the subsampling offset is desired.
      Returns:
      offset of the first cell to read along the specified dimension of the grid.
      Throws:
      Index­Out­Of­Bounds­Exception - if dimension is not between 0 inclusive and get­Dimension() exclusive.

    • isXContiguous

      public final boolean isXContiguous()
      Returns true if reading data in this subset will read contiguous values on the x axis. This method returns true if all following conditions are met:
      • All bands will be read (ignoring change of band order because this change is handled by the sample model).
      • There is no subsampling on the x axis.
      Note that the first criterion can often be relaxed when the sample model is an instance of Banded­Sample­Model. This method does not check the sample model type.
      Returns:
      whether the values to read on a row are contiguous.

    • xDimension

      public final int xDimension()
      Returns dimension of the grid which is mapped to the x axis (column indexes) in rendered images. This is usually 0.
      Returns:
      grid dimension mapped to image columns (usually 0).

    • yDimension

      public final int yDimension()
      Returns dimension of the grid which is mapped to the y axis (row indexes) in rendered images. This is usually 1.
      Returns:
      grid dimension mapped to image rows (usually 1).

    • getImageModel

      public final SampleModel getImageModel()
      Returns the sample model of the rendered image to create. The width and height of the returned sample model are the expected size of tiles in the rendered image, as computed by get­Image­Tile­Size(int) for dimensions returned by x­Dimension() (width) and y­Dimension() (height).

      The sample model has the number of bands specified in the range arguments of the constructor. The data buffers should store the sample values in order of increasing band index. If the range argument specified bands in a different order, the reordering will be applied by the returned Sample­Model.

      Returns:
      the sample model of the image to create.
      See Also:

    • createCoverage

      protected GridCoverage createCoverage() throws DataStoreException
      Creates a tiled grid coverage for the coverage subset described by this Subset. If this subset uses the tile size specified by the resource, or use (for efficiency reasons) a virtual tile size which is supported by the resource, then this method delegates to Tiled­Grid­Coverage­Resource​.read(Subset). Otherwise, this method returns a wrapper which will simulate the virtual tiling.

      Usage

      This method is invoked by the default implementation of Tiled­Grid­Coverage­Resource​.read(Grid­Geometry, int...). This method should generally not be invoked by user's code. It is rather for overriding in subclasses. The caller is responsible for holding the synchronization lock.
      Returns:
      the grid coverage for the specified domain, resolution and ranges.
      Throws:
      Data­Store­Exception - if the coverage cannot be created.
      Runtime­Exception - if the coverage cannot be created for a reason not handled as a data store exception.
      See Also: