Module org.apache.sis.storage
Package org.apache.sis.storage.tiling

Interface TileMatrix

All Known Subinterfaces:
Writable­Tile­Matrix
public interface TileMatrix
A collection of tiles with the same size and properties placed on a regular grid with no overlapping. A tile matrix usually has 2 dimensions (width and height), but this API allows any number of dimensions. The number of dimensions is given by get­Tiling­Scheme()​.get­Dimension().

Unless otherwise specified in the Javadoc, all methods in this interface expect non-null arguments are return non-null values.

Since:
1.2

  • Method Details

    • getIdentifier

      GenericName getIdentifier()
      Returns an alphanumeric identifier which is unique in the Tile­Matrix­Set that contains this Tile­Matrix. The identifier is often a zoom level (as a number encoded in ASCII), but this is not mandatory.
      Returns:
      a unique (within Tile­Matrix­Set) identifier.

    • getResolution

      double[] getResolution()
      Returns the resolution (in units of CRS axes) at which tiles in this matrix should be used. If the tiled data is a Grid­Coverage, then the resolution is typically the size of pixels in units of CRS axes. That resolution may be evaluated at some representative point such as coverage center if the pixel size is not constant everywhere.

      The array length shall be the number of CRS dimensions, and value at index i is the resolution along CRS dimension i in units of the CRS axis i.

      Returns:
      resolution (in units of CRS axes) at which tiles in this matrix should be used.
      See Also:

    • getTilingScheme

      GridGeometry getTilingScheme()
      Returns a description about how space is partitioned into individual tiled units. The description contains the extent of valid tile indices, the spatial reference system, and the conversion from tile indices to the spatial reference system coordinates. The CRS shall be the same as Tile­Matrix­Set​.get­Coordinate­Reference­System(). The "grid to CRS" transform should be defined and should be affine. The grid geometry shall have a Grid­Extent which gives the range of valid indices that can be used in calls to get­Tile(long...) and get­Tile­Status(long...) methods.

      The "grid to CRS" transform converts tile indices to "real world" coordinates. This conversion can follow two conventions:

      • The Pixel­In­Cell​.CELL_CORNER convention maps tile indices to the extreme corner (in the direction of smallest indices) of the bounding box of the tile. In a two-dimensional space having the usual display axis orientations, this is the top-left corner of the top-left pixel.
      • The Pixel­In­Cell​.CELL_CENTER convention maps tile indices to the median value of the tile bounding box in all dimensions.

      Relationship with OGC specification

      OGC has a more generic definition of tiling scheme, where the scheme specifies which space a uniquely identified tile occupies. Reversely, the tiling scheme makes possible to find which unique identifier corresponds to a space satisfying the geometric properties to be a tile. In Tile­Matrix, the unique identifier of a tile is the sequence of tile indices stored in a long[] array. The space occupied by a tile can be computed by the above-cited "grid to CRS" transform. Reversely the tile indices for a given space can be computed by the inverse of the "grid to CRS" transform.
      Returns:
      extent of valid tile indices (mandatory) and their relationship with "real world" coordinates (optional).
      See Also:

    • getTileStatus

      TileStatus getTileStatus(long... indices) throws DataStoreException
      Fetches information about whether a tile exists, is missing or failed to load. The accuracy of a tile status greatly varies with each protocol. If the returned value is different than Tile­Status​.UNKNOWN, then:
      Relationship between return value and tile fetching behavior}
      Return value Consequence
      TileStatus.EXISTS getTile(indices) should return a non-empty value.
      TileStatus.MISSING getTile(indices) should return an empty value.
      TileStatus.OUTSIDE_EXTENT getTile(indices) should throw No­Such­Data­Exception.
      TileStatus.IN_ERROR getTile(indices) should throw Data­Store­Exception (or a sub-type).
      Parameters:
      indices - indices of the requested tile (may be outside the tile matrix extent).
      Returns:
      information about the availability of the specified tile, or Tile­Status​.OUTSIDE_EXTENT if the given indices are invalid.
      Throws:
      Data­Store­Exception - if fetching the tile status failed.
      See Also:

    • getTile

      Optional<Tile> getTile(long... indices) throws DataStoreException
      Gets a tile at the given indices.
      Parameters:
      indices - indices of the tile to fetch, as coordinates inside the matrix Grid­Extent.
      Returns:
      the tile if it exists, or an empty value if the tile is missing.
      Throws:
      No­Such­Data­Exception - if the given indices are outside the matrix extent.
      Data­Store­Exception - if fetching the tile failed for another reason.

    • getTiles

      Stream<Tile> getTiles(GridExtent indicesRanges, boolean parallel) throws DataStoreException
      Retrieves a stream of existing tiles in the specified region. The stream contains the existing tiles that are inside the given region and excludes all missing tiles. If a tile is in error, then the stream should nevertheless return a Tile instance but its Tile​.get­Resource() method should throw the exception.

      The parallel argument specifies whether a parallelized stream is desired. If false, the stream is guaranteed to be sequential. If true, the stream may or may not be parallel; implementations are free to ignore this argument if they do not support parallelism.

      Parameters:
      indices­Ranges - ranges of tile indices in all dimensions, or null for all tiles.
      parallel - true for a parallel stream (if supported), or false for a sequential stream.
      Returns:
      stream of tiles, excluding missing tiles. Iteration order of the stream may vary from one implementation to another and from one call to another.
      Throws:
      Data­Store­Exception - if the stream creation failed.