[postgis-tickets] [SCM] PostGIS branch master updated. 3.3.0rc2-3-g40a051601
git at osgeo.org
git at osgeo.org
Mon Aug 22 15:39:44 PDT 2022
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "PostGIS".
The branch, master has been updated
via 40a051601130f7c42243f6c616951977e384f278 (commit)
from 4b9b65fd05b5421baa0a6e32e06dec3466f260a3 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit 40a051601130f7c42243f6c616951977e384f278
Author: Martin Davis <mtnclimb at gmail.com>
Date: Mon Aug 22 15:39:40 2022 -0700
Improve doc for MVT functions
diff --git a/doc/reference_constructor.xml b/doc/reference_constructor.xml
index ef1c1bfff..9cf04149a 100644
--- a/doc/reference_constructor.xml
+++ b/doc/reference_constructor.xml
@@ -916,9 +916,26 @@ SRID=4326;POLYGON((75 29 1, 77 29 2, 77 29 3, 75 29 1))
<refsection>
<title>Description</title>
- <para>Creates a rectangular Polygon in <ulink url="https://en.wikipedia.org/wiki/Web_Mercator_projection">Web Mercator</ulink> (SRID:3857) using the <ulink url="https://en.wikipedia.org/wiki/Tiled_web_map">XYZ tile system</ulink>. By default, the bounds are the in EPSG:3857 using the standard range of the Web Mercator system (-20037508.342789, 20037508.342789). The optional bounds parameter can be used to generate envelopes for any tiling scheme: provide a geometry that has the SRID and extent of the initial "zoom level zero" square within which the tile system is to be inscribed.</para>
-
- <para>The optional margin parameter can be used to grow a tile by the given percentage, e.g. margin=0.125 grows the tile by 12.5%, which is equivalent to buffer=512 when extent is 4096, as used in <xref linkend="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 current tile's rendering. For example, a city name (a geopoint) could be near an edge of a tile, but the text would need to render on two tiles, even though the geopoint is located in the visible area of just one tile. Using an expanded tile in a search would include the city geopoint for both tiles. Use negative value to shrink the tile instead. Values less than -0.5 are prohibited because that would eliminate the tile completely. Do not use margin with ST_AsMVTGeom(). See example in <xref linkend="ST_AsMVT" />.</para>
+ <para>Creates a rectangular Polygon
+ giving the extent of a tile in the <ulink url="https://en.wikipedia.org/wiki/Tiled_web_map">XYZ tile system</ulink>.
+ The tile is specifed 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 <xref linkend="ST_AsMVTGeom" /> to convert geometry
+ into the MVT tile coordinate space.
+ </para>
+ <para>By default, the tile envelope is in the <ulink url="https://en.wikipedia.org/wiki/Web_Mercator_projection">Web Mercator</ulink> 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 <varname>bounds</varname> 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.</para>
+
+ <para>The optional <varname>margin</varname> parameter can be used to expand a tile by the given percentage.
+ E.g. <varname>margin=0.125</varname> expands the tile by 12.5%, which is equivalent to buffer=512 when the tile extent size is 4096, as used in <xref linkend="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 <varname>ST_AsMVTGeom</varname>.
+ See the example for <xref linkend="ST_AsMVT" />.</para>
<para>Enhanced: 3.1.0 Added margin parameter.</para>
<para>Availability: 3.0.0</para>
diff --git a/doc/reference_output.xml b/doc/reference_output.xml
index e07bc22c8..29b95d3d7 100644
--- a/doc/reference_output.xml
+++ b/doc/reference_output.xml
@@ -1159,7 +1159,7 @@ SELECT (ST_AsLatLonText('POINT (-302.2342342 -792.32498)'));
<refnamediv>
<refname>ST_AsMVTGeom</refname>
- <refpurpose>Transform a geometry into the coordinate space of a <ulink url="https://www.mapbox.com/vector-tiles/">Mapbox Vector Tile</ulink>.</refpurpose>
+ <refpurpose>Transforms a geometry into the coordinate space of a MVT tile.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
@@ -1177,15 +1177,27 @@ SELECT (ST_AsLatLonText('POINT (-302.2342342 -792.32498)'));
<refsection>
<title>Description</title>
- <para>Transform a geometry into the coordinate space of a <ulink url="https://www.mapbox.com/vector-tiles/">Mapbox Vector Tile</ulink> of a set of rows corresponding to a Layer.
- Makes best effort to keep and even correct validity and might collapse geometry into a lower dimension in the process.
+ <para>Transforms a geometry into the coordinate space of a MVT (<ulink url="https://www.mapbox.com/vector-tiles/">Mapbox Vector Tile</ulink>) tile,
+ clipping it to the tile bounds if required.
+ The geometry must be in the coordinate system of the target map (using <xref linkend="ST_Transform" /> if needed).
+ Commonly this is <ulink url="https://en.wikipedia.org/wiki/Web_Mercator_projection">Web Mercator</ulink> (SRID:3857).
+ </para>
+ <para>The function attempts to preserve geometry validity, and corrects it if needed.
+ This may cause the result geometry to collapse to a lower dimension.
</para>
-
- <para><varname>geom</varname> is the geometry to transform.</para>
- <para><varname>bounds</varname> is the geometric bounds of the tile contents without buffer.</para>
- <para><varname>extent</varname> is the tile extent in tile coordinate space as defined by the <ulink url="https://www.mapbox.com/vector-tiles/specification/">specification</ulink>. If NULL it will default to 4096.</para>
- <para><varname>buffer</varname> is the buffer distance in tile coordinate space to optionally clip geometries. If NULL it will default to 256.</para>
- <para><varname>clip_geom</varname> is a boolean to control if geometries should be clipped or encoded as is. If NULL it will default to true.</para>
+ <para>The rectangular bounds of the tile in the target map coordinate space must be provided,
+ so the geometry can be transformed, and clipped if required.
+ The bounds can be generated using <xref linkend="ST_TileEnvelope" />.
+ </para>
+ <para>
+ This function is used to convert geometry into the tile coordinate space required by <xref linkend="ST_AsMVT" />.
+ </para>
+
+ <para><varname>geom</varname> is the geometry to transform, in the coordinate system of the target map.</para>
+ <para><varname>bounds</varname> is the rectangular bounds of the tile in map coordinate space, with no buffer.</para>
+ <para><varname>extent</varname> is the tile extent size in tile coordinate space as defined by the <ulink url="https://www.mapbox.com/vector-tiles/specification/">MVT specification</ulink>. Defaults to 4096.</para>
+ <para><varname>buffer</varname> is the buffer size in tile coordinate space for geometry clippig. Defaults to 256.</para>
+ <para><varname>clip_geom</varname> is a boolean to control if geometries are clipped or encoded as-is. Defaults to true.</para>
<para>Availability: 2.4.0</para>
@@ -1196,16 +1208,27 @@ SELECT (ST_AsLatLonText('POINT (-302.2342342 -792.32498)'));
<refsection>
<title>Examples</title>
- <programlisting><![CDATA[SELECT ST_AsText(ST_AsMVTGeom(
+ <programlisting>
+SELECT ST_AsText(ST_AsMVTGeom(
ST_GeomFromText('POLYGON ((0 0, 10 0, 10 5, 0 -5, 0 0))'),
ST_MakeBox2D(ST_Point(0, 0), ST_Point(4096, 4096)),
4096, 0, false));
st_astext
--------------------------------------------------------------------
MULTIPOLYGON(((5 4096,10 4091,10 4096,5 4096)),((5 4096,0 4101,0 4096,5 4096)))
-
- ]]>
</programlisting>
+
+ <para>Canonical example for a Web Mercator tile using a computed tile bounds to query and clip geometry.
+ </para>
+ <programlisting>
+<![CDATA[SELECT ST_AsMVTGeom(
+ ST_Transform( geom, 3857 ),
+ ST_TileEnvelope(12, 513, 412), extent => 4096, buffer => 64) AS geom
+ FROM data
+ WHERE geom && ST_TileEnvelope(12, 513, 412, margin => (64.0 / 4096))
+]]>
+</programlisting>
+
</refsection>
<refsection>
@@ -1222,7 +1245,7 @@ SELECT (ST_AsLatLonText('POINT (-302.2342342 -792.32498)'));
<refnamediv>
<refname>ST_AsMVT</refname>
- <refpurpose>Aggregate function returning a Mapbox Vector Tile representation of a set of rows.</refpurpose>
+ <refpurpose>Aggregate function returning a MVT representation of a set of rows.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
@@ -1264,8 +1287,8 @@ SELECT (ST_AsLatLonText('POINT (-302.2342342 -792.32498)'));
<para>An aggregate function which returns a binary <ulink url="https://www.mapbox.com/vector-tiles/">Mapbox Vector Tile</ulink>
representation of a set of rows corresponding to a tile layer.
- The rows should contain a geometry column which will be encoded as a feature geometry.
- The geometry should be in tile coordinate space
+ The rows must contain a geometry column which will be encoded as a feature geometry.
+ The geometry must be in tile coordinate space
and valid as per the <ulink url="https://www.mapbox.com/vector-tiles/specification/">MVT specification</ulink>.
<xref linkend="ST_AsMVTGeom" /> can be used to transform geometry into tile coordinate space.
Other row columns are encoded as feature attributes.
-----------------------------------------------------------------------
Summary of changes:
doc/reference_constructor.xml | 23 ++++++++++++++++---
doc/reference_output.xml | 53 +++++++++++++++++++++++++++++++------------
2 files changed, 58 insertions(+), 18 deletions(-)
hooks/post-receive
--
PostGIS
More information about the postgis-tickets
mailing list