ST_TileEnvelope
Name
ST_TileEnvelope — Creates a rectangular Polygon in Web Mercator (SRID:3857) using the XYZ tile system .
Synopsis
geometry
ST_TileEnvelope
(
integer
tileZoom
, integer
tileX
, integer
tileY
, geometry
bounds=SRID=3857;LINESTRING(-20037508.342789 -20037508.342789,20037508.342789 20037508.342789)
, float
margin=0.0
)
;
Description
Creates a rectangular Polygon giving the extent of a tile in the XYZ tile system . The tile is specified by the zoom level Z and the XY index of the tile in the grid at that level. Can be used to define the tile bounds required by ST_AsMVTGeom to convert geometry into the MVT tile coordinate space.
By default, the tile envelope is in the
Web Mercator
coordinate system (SRID:3857)
using the standard range of the Web Mercator system (-20037508.342789, 20037508.342789).
This is the most common coordinate system used for MVT tiles.
The optional
bounds
parameter can be used to generate tiles in any coordinate system.
It is a geometry that has the SRID and extent of the "Zoom Level zero" square within which the XYZ tile system is inscribed.
The optional
margin
parameter can be used to expand a tile by the given percentage.
E.g.
margin=0.125
expands the tile by 12.5%, which is equivalent to buffer=512 when the tile extent size is 4096, as used in
ST_AsMVTGeom
.
This is useful to create a tile buffer to include data lying outside of the tile's visible area, but whose existence affects the tile rendering.
For example, a city name (a point) could be near an edge of a tile, so its label should be rendered on two tiles, even though the point is located in the visible area of just one tile.
Using expanded tiles in a query will include the city point in both tiles.
Use a negative value to shrink the tile instead. Values less than -0.5 are prohibited because that would eliminate the tile completely.
Do not specify a margin when using with
ST_AsMVTGeom
.
See the example for
ST_AsMVT
.
Enhanced: 3.1.0 Added margin parameter.
Availability: 3.0.0
Examples
Show tile (2, 1, 1) within the root tile (0, 0, 0).
SELECT ST_TileEnvelope(0, 0, 0) AS input_z0_x0_y0, ST_TileEnvelope(2, 1, 1) AS z2_x1_y1;
input_z0_x0_y0 | z2_x1_y1 ----------------+----------- POLYGON((-20037508.342789244 -20037508.342789244,-20037508.342789244 20037508.342789244,20037508.342789244 20037508.342789244,20037508.342789244 -20037508.342789244,-20037508.342789244 -20037508.342789244)) | POLYGON((-10018754.171394622 0,-10018754.171394622 10018754.171394622,0 10018754.171394622,0 0,-10018754.171394622 0))
SELECT ST_TileEnvelope(3, 1, 1, ST_MakeEnvelope(-180, -90, 180, 90, 4326));
POLYGON((-135 45,-135 67.5,-90 67.5,-90 45,-135 45))