# Interface TileMatrix

All Known Subinterfaces:
  `WritableTileMatrix`

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 `getTilingScheme()​.getDimension()`.

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

Since:
  1.2

- ## Method Summary

  Modifier and Type
  Method
  Description
  `GenericName`
  `getIdentifier()`
  Returns an alphanumeric identifier which is unique in the `TileMatrixSet` that contains this `TileMatrix`.
  `default Metadata`
  `getMetadata()`
  Returns information about this tile matrix.
  `double[]`
  `getResolution()`
  Returns the resolution (in units of CRS axes) at which tiles in this matrix should be used.
  `Optional<Tile>`
  `getTile(long... indices)`
  Gets a tile at the given indices.
  `Stream<Tile>`
  `getTiles(GridExtent indicesRanges, boolean parallel)`
  Retrieves a stream of existing tiles in the specified region.
  `TileStatus`
  `getTileStatus(long... indices)`
  Fetches information about whether a tile exists, is missing or failed to load.
  `GridGeometry`
  `getTilingScheme()`
  Returns a description about how space is partitioned into individual tiled units.

- ## Method Details

  - ### getIdentifier

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

  - ### getMetadata

    default Metadata getMetadata()
    Returns information about this tile matrix. The metadata should contain at least the following information:
    - `metadata` / `identificationInfo` / `citation` / `title`:
      a human-readable designation for this tile matrix.
    - `metadata` / `identificationInfo` / `citation` / `identifier`:
      this `TileMatrix` identifier.
    - `metadata` / `identificationInfo` / `extent`:
      this `TileMatrix` envelope.
    - `metadata` / `identificationInfo` / `spatialResolution`:
      this `TileMatrix` resolution along spatial dimensions.
    - `metadata` / `identificationInfo` / `temporalResolution`:
      this `TileMatrix` resolution along the temporal dimension.
    - `metadata` / `referenceSystemInfo`:
      this `TileMatrix` coordinate reference system.
    - `metadata` / `identificationInfo` / `resourceFormat`:
      a description of the tile format.

    #### Note for implementers

    The default implementation creates a modifiable `DefaultMetadata` instance with values derived from `getIdentifier()`, `getTilingScheme()` and `getResolution()`. Subclasses (not users) can cast and complete those metadata. In particular, implementations are encouraged to add the `title` and `resourceFormat` information.
    Returns:
      information about this tile matrix.
    Since:
      1.5

  - ### 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 `GridCoverage`, 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:
      - `GridGeometry​.getResolution(boolean)`

  - ### 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 `TileMatrixSet​.getCoordinateReferenceSystem()`. The "grid to CRS" transform should be defined and should be affine. The grid geometry shall have a `GridExtent` which gives the range of valid indices that can be used in calls to `getTile(long...)` and `getTileStatus(long...)` methods.

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

    - The `PixelInCell​.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 `PixelInCell​.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 `TileMatrix`, 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:
      - `TileMatrixSet​.getCoordinateReferenceSystem()`

  - ### 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 `TileStatus​.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 `NoSuchDataException`.
    `TileStatus.IN_ERROR` | `getTile(indices)` should throw `DataStoreException` (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 `TileStatus​.OUTSIDE_EXTENT` if the given indices are invalid.
    Throws:
      `DataStoreException` - if fetching the tile status failed.
    See Also:
      - `Tile​.getStatus()`

  - ### 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 `GridExtent`.
    Returns:
      the tile if it exists, or an empty value if the tile is missing.
    Throws:
      `NoSuchDataException` - if the given indices are outside the matrix extent.
      `DataStoreException` - 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​.getResource()` 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:
      `indicesRanges` - 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:
      `DataStoreException` - if the stream creation failed.