# Interface TileMatrixSet

All Known Subinterfaces:
  `WritableTileMatrixSet`

public interface TileMatrixSet
A collection of `TileMatrix` in the same CRS but at different scale levels. Each `TileMatrix` is optimized for a particular scale and is identified by a tile matrix identifier. Tile matrices usually have 2 dimensions (width and height), but this API allows any number of dimensions. However, the number of dimensions must be the same for all tile matrices.

The `TileMatrixSet` concept is derived from OGC standards. The same concept is called image pyramid or resolution levels in some other standards. Some standards require that all scales must be related by a power of 2, but `TileMatrixSet` does not have this restriction.

## Tile matrix identification

Each `TileMatrix` in a `TileMatrixSet` is identified by a `GenericName`. Identifiers can be any character strings. A common practice is to use zoom levels as identifiers, but this is not mandatory. However, tile matrices must be sorted from coarser resolution (highest scale denominator) to most detailed resolution (lowest scale denominator).

All methods in this interface return non-null values.

Since:
  1.2

- ## Method Summary

  Modifier and Type
  Method
  Description
  `CoordinateReferenceSystem`
  `getCoordinateReferenceSystem()`
  Returns the coordinate reference system of all `TileMatrix` instances in this set.
  `Optional<Envelope>`
  `getEnvelope()`
  Returns an envelope that encompasses all `TileMatrix` instances in this set.
  `GenericName`
  `getIdentifier()`
  Returns an alphanumeric identifier which is unique in the `TiledResource` that contains this `TileMatrixSet`.
  `default Metadata`
  `getMetadata()`
  Returns information about this tile matrix set.
  `SortedMap<GenericName, ? extends TileMatrix>`
  `getTileMatrices()`
  Returns all `TileMatrix` instances in this set, together with their identifiers.

- ## Method Details

  - ### getIdentifier

    GenericName getIdentifier()
    Returns an alphanumeric identifier which is unique in the `TiledResource` that contains this `TileMatrixSet`. A tiled resource may contains more than one tile matrix set if the resource prepared different set of tiles for different CRS.
    Returns:
      a unique (within `TiledResource`) identifier.

  - ### getMetadata

    default Metadata getMetadata()
    Returns information about this tile matrix set. The metadata should contain at least the following information:
    - `metadata` / `identificationInfo` / `citation` / `title`:
      a human-readable designation for this tile matrix set.
    - `metadata` / `identificationInfo` / `citation` / `identifier`:
      this `TileMatrixSet` identifier.
    - `metadata` / `identificationInfo` / `extent`:
      this `TileMatrixSet` envelope.
    - `metadata` / `referenceSystemInfo`:
      this `TileMatrixSet` 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()`, `getEnvelope()` and `getCoordinateReferenceSystem()`. 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 set. Should not be `null`.
    Since:
      1.5

  - ### getCoordinateReferenceSystem

    CoordinateReferenceSystem getCoordinateReferenceSystem()
    Returns the coordinate reference system of all `TileMatrix` instances in this set. This is the value returned by `TileMatrix​.getTilingScheme()​.getCoordinateReferenceSystem()`.
    Returns:
      the CRS used by all `TileMatrix` instances in this set.
    See Also:
      - `TileMatrix​.getTilingScheme()`

  - ### getEnvelope

    Optional<Envelope> getEnvelope()
    Returns an envelope that encompasses all `TileMatrix` instances in this set. This is the union of all values returned by `TileMatrix​.getTilingScheme()​.getEnvelope()`. May be empty if too costly to compute.
    Returns:
      the bounding box for all tile matrices in CRS coordinates, if available.

  - ### getTileMatrices

    SortedMap<GenericName, ? extends TileMatrix> getTileMatrices()
    Returns all `TileMatrix` instances in this set, together with their identifiers. For each value in the map, the associated key is `TileMatrix​.getIdentifier()`. Entries are sorted from coarser resolution (highest scale denominator) to most detailed resolution (lowest scale denominator). This is not necessarily the natural ordering of the `GenericName` instances used as keys.
    Returns:
      unmodifiable collection of all `TileMatrix` instances with their identifiers.