com.pb.lisdk.maptiling

## Interface ITileGrid

    public interface ITileGrid

A tile grid divides a rectangular geographic region into tiles. At each level, the grid breaks a tile from the level above into four tiles of equal size. A particular tile is identified by a row index, a column index and a level. At each level, any point within the geographic region of the grid belongs to one and only one tile. Note that tile grid instances are not concerned with the rendering of map tiles into, for example, raster images. Instead, it provides a reusable abstraction for commonly used tile calculations. A tile grid distinguishes between three different coordinate systems.

1. Tile coordinates refer to the row, column and level of a single tile. The values are positive integers and may include 0, if the tile grid uses zero-based indexes.
2. Screen coordinates refer to a virtual coordinate system of pixels The screen coordinate system originates in the top left corner of the tile grid. It extends horizontally to `column count * tile width` and vertically to `row count * tile height`. The origin is `(0,0)` irrespective of whether this tile grid uses zero or one-based indexes.
3. Geographic coordinates are used to represent grid and tile boundaries in a specific spatial reference system. These can then be used during tile rendering to retrieve the correct set of features from a spatial data store.

The tile grid interface provides a range of operations to convert between these three types of coordinates.

### Method Summary

All Methods Instance Methods Abstract Methods
`Envelope` `getBounds()` Returns the geographic bounds of this tile grid.
`int` `getMaxLevel()` Returns the maximum zoom level supported by this tile grid.
`int` `getMinLevel()` Returns the minimum zoom level supported by this tile grid.
`Dimension` `getTileSize()` Returns the tile size of this grid.
`ITileCoordinate` `newTileCoordinate(int row, int col, int level)` Returns a new tile coordinate instance for the given row, column and level.
`ITileCoordinate` `tileForPoint(IPoint mapPoint, int level)` Returns the coordinates of the tile that contains the given point at the provided zoom level.
`ITileCoordinate` `tileForScreenCoordinates(Point screenPoint, int level)` Returns the coordinates of the tile that contains the given screen coordinates at the given level.
`ITileCoordinateRange` `tileRangeForBounds(Envelope bounds, int level)` Returns the range of tiles that cover the given geographic bounds.
`ITileCoordinateRange` `tileRangeForLevel(int level)` Returns a tile range comprised of all tiles of the given level.
`IPoint` `toMapCoordinates(Point screenPoint, int level)` Converts the given screen coordinates to geographic coordinates at the given level.
`Point` `toScreenCoordinates(IPoint mapPoint, int level)` Converts the given geographic point to screen coordinates at the given level.

### Method Detail

#### tileForPoint

    ITileCoordinate tileForPoint(IPoint mapPoint,
                                 int level)

Returns the coordinates of the tile that contains the given point at the provided zoom level. For every point there's a single tile at a specific zoom level that contains the point.

Parameters:
  `mapPoint` - a point that will be inside the bounds of the returned tile coordinate.
  `level` - the zoom level to request the tile coordinate for.
Returns:
  a tile coordinate object that contains the given point.
Throws:
  `InvalidLevelException` - if the level is outside of the allowed minimum and maximum levels.
  `MapPointOutsideOfGridBoundsException` - if the given point is outside the bounds of this tile grid.

#### tileForScreenCoordinates

    ITileCoordinate tileForScreenCoordinates(Point screenPoint,
                                             int level)

Returns the coordinates of the tile that contains the given screen coordinates at the given level.

Parameters:
  `screenPoint` - the screen coordinates to get the tile coordinate for.
  `level` - the zoom level to request the tile coordinate for.
Returns:
  a tile coordinate object that contains the given screen coordinate.

#### tileRangeForBounds

    ITileCoordinateRange tileRangeForBounds(Envelope bounds,
                                            int level)

Returns the range of tiles that cover the given geographic bounds.

Parameters:
  `bounds` - The bounds to get all overlapping tiles for
  `level` - the zoom level to request the tile coordinate range for.
Returns:
  a tile range object covering the given bounds
Throws:
  `InvalidLevelException` - if the level is outside of the allowed minimum and maximum levels.

#### tileRangeForLevel

    ITileCoordinateRange tileRangeForLevel(int level)

Returns a tile range comprised of all tiles of the given level.

Parameters:
  `level` - the zoom level to request the coordinate range for.
Returns:
  a tile range object covering the entire grid at the given level
Throws:
  `InvalidLevelException` - if the level is outside of the allowed minimum and maximum levels.

#### newTileCoordinate

    ITileCoordinate newTileCoordinate(int row,
                                      int col,
                                      int level)

Returns a new tile coordinate instance for the given row, column and level.

Parameters:
  `row` - the row of the tile in the overall tile grid
  `col` - the column of the tile in the overall tile grid
  `level` - the zoom level of the tile
Throws:
  `InvalidRowOrColumnException` - if the column or row are outside the minimum and maximum column or row values.
  `InvalidLevelException` - if the level is outside of the allowed minimum and maximum levels.

#### toScreenCoordinates

    Point toScreenCoordinates(IPoint mapPoint,
                              int level)

Converts the given geographic point to screen coordinates at the given level.

Parameters:
  `mapPoint` - the point to convert to screen coordinates.
  `level` - the level at which to calculate the screen coordinates.
Returns:
  the screen coordinates corresponding to the given geographic coordinates.
Throws:
  `InvalidLevelException` - if the level is outside of the allowed minimum and maximum levels
  `MapPointOutsideOfGridBoundsException` - if the given point is outside the bounds of this tile grid.

#### toMapCoordinates

    IPoint toMapCoordinates(Point screenPoint,
                            int level)

Converts the given screen coordinates to geographic coordinates at the given level.

Parameters:
  `screenPoint` - the screen coordinates to convert to geographic coordinates.
  `level` - the level at which to interpret the screen coordinates.
Returns:
  the geographic coordinates corresponding to the given screen coordinates.
Throws:
  `InvalidLevelException` - if the level is outside of the allowed minimum and maximum levels.

#### getBounds

    Envelope getBounds()

Returns the geographic bounds of this tile grid.

#### getTileSize

    Dimension getTileSize()

Returns the tile size of this grid. The tile size is constant for all tiles at all levels.

#### getMinLevel

    int getMinLevel()

Returns the minimum zoom level supported by this tile grid.

#### getMaxLevel

    int getMaxLevel()

Returns the maximum zoom level supported by this tile grid.