Tutorial¶
This guide walks through the everyday operations of tileverse-tilematrixset: selecting a tile matrix set, mapping coordinates to tiles, iterating over a region, and building a custom set.
1. Pick a standard set¶
Standard sets are available as static constants on DefaultTileMatrixSets. Each one has an OGC identifier, a supportedCRS URI, and, where applicable, a wellKnownScaleSet URI.
import io.tileverse.tiling.matrix.DefaultTileMatrixSets;
import io.tileverse.tiling.matrix.TileMatrixSet;
TileMatrixSet tms = DefaultTileMatrixSets.WEB_MERCATOR_QUAD;
System.out.println(tms.identifier()); // "WebMercatorQuad"
System.out.println(tms.supportedCRS()); // http://www.opengis.net/def/crs/EPSG/0/3857
System.out.println(tms.wellKnownScaleSet()); // Optional[http://...GoogleMapsCompatible]
2. Map a coordinate to a tile¶
coordinateToTile accepts a coordinate in the CRS of the matrix set and returns the tile that contains it. Inputs must already be in the target CRS; use a projection library if you need to convert from longitude/latitude.
import io.tileverse.geom.Coordinate;
import io.tileverse.tiling.matrix.DefaultTileMatrixSets;
import io.tileverse.tiling.matrix.TileMatrixSet;
import io.tileverse.tiling.pyramid.TileIndex;
TileMatrixSet tms = DefaultTileMatrixSets.WORLD_CRS84_QUAD;
Coordinate london = new Coordinate(-0.1276, 51.5074); // lon/lat in CRS84
TileIndex tile = tms.coordinateToTile(london, 10);
System.out.printf("Tile z=%d x=%d y=%d%n", tile.z(), tile.x(), tile.y());
3. Iterate tiles intersecting an area¶
TileMatrix.intersection(bbox) returns a matrix restricted to the tiles overlapping the bounding box, and its tiles() stream emits only those tiles. extentToRange(bbox) returns the same tiles as a TileRange of tile indices.
import io.tileverse.geom.BoundingBox2D;
import io.tileverse.tiling.matrix.TileMatrix;
TileMatrix matrixZ12 = tms.getTileMatrix(12);
BoundingBox2D area = BoundingBox2D.extent(-1.0, 50.0, 1.0, 52.0);
matrixZ12.intersection(area).ifPresent(view ->
view.tiles().forEach(tile ->
System.out.println("Processing " + tile.tileIndex())));
4. Build a custom set¶
The builder requires identifier, CRS, tile pyramid, extent, and resolutions. Optional OGC metadata (title, abstract, keywords, well-known scale set) goes through fluent setters.
import io.tileverse.geom.BoundingBox2D;
import io.tileverse.tiling.pyramid.CornerOfOrigin;
import io.tileverse.tiling.matrix.TileMatrixSet;
import io.tileverse.tiling.pyramid.TilePyramid;
import io.tileverse.tiling.pyramid.TileRange;
double[] resolutions = {0.703125, 0.3515625, 0.17578125};
TilePyramid pyramid = TilePyramid.builder()
.cornerOfOrigin(CornerOfOrigin.TOP_LEFT)
.level(TileRange.of(0, 0, 1, 0, 0, CornerOfOrigin.TOP_LEFT))
.level(TileRange.of(0, 0, 3, 1, 1, CornerOfOrigin.TOP_LEFT))
.level(TileRange.of(0, 0, 7, 3, 2, CornerOfOrigin.TOP_LEFT))
.build();
TileMatrixSet custom = TileMatrixSet.builder()
.identifier("MyCustomSet")
.title("Custom 4326 set, zooms 0-2")
.crs("EPSG:4326")
.tilePyramid(pyramid)
.tileSize(256, 256)
.extent(BoundingBox2D.extent(-180, -90, 180, 90))
.resolutions(resolutions)
.build();