[postgis-tickets] [SCM] PostGIS branch master updated. 3.1.0rc1-174-g28bbc4a
git at osgeo.org
git at osgeo.org
Fri Apr 30 15:02:42 PDT 2021
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 28bbc4af43e48e9183a58fc5f221e1a1c42722c2 (commit)
from a59187e6015537724fa7de223ea0a6c3e73d84a9 (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 28bbc4af43e48e9183a58fc5f221e1a1c42722c2
Author: Martin Davis <mtnclimb at gmail.com>
Date: Fri Apr 30 15:02:29 2021 -0700
Improve doc Linear Ref sections
diff --git a/doc/reference_lrs.xml b/doc/reference_lrs.xml
index 9455c2f..8357015 100644
--- a/doc/reference_lrs.xml
+++ b/doc/reference_lrs.xml
@@ -22,14 +22,25 @@
<refsection>
<title>Description</title>
- <para>Returns a point interpolated along a line at a fractional location. First argument
- must be a LINESTRING. Second argument is a float8 between 0 and 1
- representing fraction of total linestring length the point has to be located.</para>
+ <para>Returns a point interpolated along a line at a fractional location.
+ First argument must be a LINESTRING.
+ Second argument is a float between 0 and 1
+ representing the fraction of total linestring length
+ where the point is to be located.
+ The Z and M values are interpolated if present.
+ </para>
<para>See <xref linkend="ST_LineLocatePoint" /> for
computing the line location nearest to a Point.</para>
<note>
+ <para>This function computes points in 2D and then interpolates
+ values for Z and M,
+ while <xref linkend="ST_3DLineInterpolatePoint" /> computes points in 3D
+ and only interpolates the M value.</para>
+ </note>
+
+ <note>
<para>Since release 1.1.1 this function also interpolates M and
Z values (when present), while prior releases set them to
0.0.</para>
@@ -50,31 +61,40 @@
<caption><para>A linestring with the interpolated point at 20% position (0.20) </para></caption>
</mediaobject>
</informalfigure>
- <programlisting>--Return point 20% along 2d line
-SELECT ST_AsEWKT(ST_LineInterpolatePoint(the_line, 0.20))
- FROM (SELECT ST_GeomFromEWKT('LINESTRING(25 50, 100 125, 150 190)') as the_line) As foo;
+ <programlisting>-- The point 20% along a line
+
+SELECT ST_AsEWKT(
+ ST_LineInterpolatePoint(
+ 'LINESTRING(25 50, 100 125, 150 190)',
+ 0.2 ));
+
st_asewkt
----------------
POINT(51.5974135047432 76.5974135047432)
-
</programlisting>
+
+<para>The mid-point of a 3D line:</para>
<programlisting>
---Return point mid-way of 3d line
-SELECT ST_AsEWKT(ST_LineInterpolatePoint(the_line, 0.5))
- FROM (SELECT ST_GeomFromEWKT('LINESTRING(1 2 3, 4 5 6, 6 7 8)') as the_line) As foo;
+SELECT ST_AsEWKT(
+ ST_LineInterpolatePoint('
+ LINESTRING(1 2 3, 4 5 6, 6 7 8)',
+ 0.5 ));
st_asewkt
--------------------
POINT(3.5 4.5 5.5)
+</programlisting>
+<para>The closest point on a line to a point:</para>
+<programlisting>
+SELECT ST_AsText(
+ ST_LineInterpolatePoint( line.geom,
+ ST_LineLocatePoint( line.geom, 'POINT(4 3)')))
+FROM (SELECT ST_GeomFromText('LINESTRING(1 2, 4 5, 6 7)') As geom) AS line;
---find closest point on a line to a point or other geometry
- SELECT ST_AsText(ST_LineInterpolatePoint(foo.the_line, ST_LineLocatePoint(foo.the_line, ST_GeomFromText('POINT(4 3)'))))
-FROM (SELECT ST_GeomFromText('LINESTRING(1 2, 4 5, 6 7)') As the_line) As foo;
- st_astext
-----------------
+ st_astext
+------------
POINT(3 4)
-
</programlisting>
</refsection>
@@ -83,13 +103,10 @@ FROM (SELECT ST_GeomFromText('LINESTRING(1 2, 4 5, 6 7)') As the_line) As foo;
<title>See Also</title>
<para>
- <xref linkend="ST_AsText" />,
- <xref linkend="ST_AsEWKT" />,
- <xref linkend="ST_Length" />,
- <xref linkend="ST_LineInterpolatePoints" />
- <xref linkend="ST_3DLineInterpolatePoint" />
+ <xref linkend="ST_LineInterpolatePoints" />,
+ <xref linkend="ST_3DLineInterpolatePoint" />,
<xref linkend="ST_LineLocatePoint" />
- O</para>
+ </para>
</refsection>
</refentry>
@@ -114,13 +131,17 @@ FROM (SELECT ST_GeomFromText('LINESTRING(1 2, 4 5, 6 7)') As the_line) As foo;
<title>Description</title>
<para>Returns a point interpolated along a 3D line at a fractional location.
- First argument must be a LINESTRING. Second argument is a float8 between 0 and 1
- representing fraction of total linestring length the point has to be located.</para>
+ First argument must be a LINESTRING. Second argument is a float between 0 and 1
+ representing the fraction of linestring length
+ where the point is to be located.
+ The M value is interpolated if present.
+ </para>
<note>
- <para><xref linkend="ST_LineInterpolatePoint" /> computes resulting point in 2D and then interpolates
- value for Z and M, while ST_3DLineInterpolatePoint computes directly point in 3D and only M value
- is interpolated then.</para>
+ <para><xref linkend="ST_LineInterpolatePoint" /> computes points in 2D
+ and then interpolates the values for Z and M,
+ while this function computes points in 3D
+ and only interpolates the M value.</para>
</note>
<para>Availability: 3.0.0</para>
@@ -132,11 +153,13 @@ FROM (SELECT ST_GeomFromText('LINESTRING(1 2, 4 5, 6 7)') As the_line) As foo;
<para>Return point 20% along 3D line</para>
<programlisting>
-SELECT ST_AsEWKT(ST_3DLineInterpolatePoint(the_line, 0.20))
- FROM (SELECT ST_GeomFromEWKT('LINESTRING(25 50 70, 100 125 90, 150 190 200)') as the_line) As foo;
- st_asewkt
+SELECT ST_AsText(
+ ST_3DLineInterpolatePoint('LINESTRING(25 50 70, 100 125 90, 150 190 200)',
+ 0.20));
+
+ st_asetext
----------------
- POINT(59.0675892910822 84.0675892910822 79.0846904776219)
+ POINT Z (59.0675892910822 84.0675892910822 79.0846904776219)
</programlisting>
</refsection>
@@ -145,11 +168,8 @@ SELECT ST_AsEWKT(ST_3DLineInterpolatePoint(the_line, 0.20))
<title>See Also</title>
<para>
- <xref linkend="ST_AsText" />,
- <xref linkend="ST_AsEWKT" />,
- <xref linkend="ST_Length" />,
- <xref linkend="ST_LineInterpolatePoint" />
- <xref linkend="ST_LineInterpolatePoints" />
+ <xref linkend="ST_LineInterpolatePoint" />,
+ <xref linkend="ST_LineInterpolatePoints" />,
<xref linkend="ST_LineLocatePoint" />
</para>
</refsection>
@@ -412,9 +432,9 @@ WHERE n*100.00/length < 1;
<funcsynopsis>
<funcprototype>
<funcdef>geometry <function>ST_LocateAlong</function></funcdef>
- <paramdef><type>geometry </type> <parameter>ageom_with_measure</parameter></paramdef>
- <paramdef><type>float8 </type> <parameter>a_measure</parameter></paramdef>
- <paramdef choice="opt"><type>float8 </type> <parameter>offset</parameter></paramdef>
+ <paramdef><type>geometry </type> <parameter>geom_with_measure</parameter></paramdef>
+ <paramdef><type>float8 </type> <parameter>measure</parameter></paramdef>
+ <paramdef choice="opt"><type>float8 </type> <parameter>offset = 0</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
@@ -422,21 +442,20 @@ WHERE n*100.00/length < 1;
<refsection>
<title>Description</title>
- <para>Returns the locations along a geometry (as a Point or MultiPoint)
- that match the given measure. Polygonal elements are not
- supported.</para>
+ <para>Returns the locations along a measured geometry (as a Point or MultiPoint)
+ that match a measure value.
+ Polygonal elements are not supported.</para>
+
+ <para>If the <varname>offset</varname> is provided, the result
+ is offset to the left or right of the input line by the specified distance.
+ A positive offset will be to the left, and a negative one to the right.</para>
- <para>If an offset is provided, the result will be offset to the
- left or right of the input line by the specified number of units.
- A positive offset will be to the left, and a negative one to the
- right.</para>
+ <note><para>Use this function only for geometries with an M component</para></note>
- <para>Semantic is specified by: ISO/IEC CD 13249-3:200x(E) - Text
- for Continuation CD Editing Meeting</para>
+ <para>The semantic is specified by the <emphasis>ISO/IEC 13249-3 SQL/MM Spatial</emphasis> standard.</para>
<para>Availability: 1.1.0 by old name ST_Locate_Along_Measure. </para>
<para>Changed: 2.0.0 in prior versions this used to be called ST_Locate_Along_Measure.</para>
- <note><para>Use this function only for geometries with an M component</para></note>
<para>&M_support;</para>
</refsection>
@@ -444,37 +463,23 @@ WHERE n*100.00/length < 1;
<refsection>
<title>Examples</title>
- <programlisting>SELECT ST_AsText(the_geom)
- FROM
- (SELECT ST_LocateAlong(
- ST_GeomFromText('MULTILINESTRINGM((1 2 3, 3 4 2, 9 4 3),
- (1 2 3, 5 4 5))'),3) As the_geom) As foo;
-
- st_asewkt
------------------------------------------------------------
- MULTIPOINT M (1 2 3)
-
---Geometry collections are difficult animals so dump them
---to make them more digestable
-SELECT ST_AsText((ST_Dump(the_geom)).geom)
- FROM
- (SELECT ST_LocateAlong(
- ST_GeomFromText('MULTILINESTRINGM((1 2 3, 3 4 2, 9 4 3),
- (1 2 3, 5 4 5))'),3) As the_geom) As foo;
-
- st_asewkt
----------------
- POINTM(1 2 3)
- POINTM(9 4 3)
- POINTM(1 2 3)
- </programlisting>
+<programlisting>
+SELECT ST_AsText(
+ ST_LocateAlong(
+ 'MULTILINESTRINGM((1 2 3, 3 4 2, 9 4 3),(1 2 3, 5 4 5))'::geometry,
+ 3 ));
+
+ st_astext
+----------------------------------
+ MULTIPOINT M (1 2 3,9 4 3,1 2 3)
+</programlisting>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection>
<title>See Also</title>
- <para><xref linkend="ST_Dump" />, <xref linkend="ST_LocateBetween" />, <xref linkend="ST_LocateBetweenElevations" /></para>
+ <para><xref linkend="ST_LocateBetween" />, <xref linkend="ST_LocateBetweenElevations" /></para>
</refsection>
</refentry>
@@ -492,7 +497,7 @@ SELECT ST_AsText((ST_Dump(the_geom)).geom)
<paramdef><type>geometry </type> <parameter>geom</parameter></paramdef>
<paramdef><type>float8 </type> <parameter>measure_start</parameter></paramdef>
<paramdef><type>float8 </type> <parameter>measure_end</parameter></paramdef>
- <paramdef choice="opt"><type>float8 </type> <parameter>offset</parameter></paramdef>
+ <paramdef choice="opt"><type>float8 </type> <parameter>offset = 0</parameter></paramdef>
</funcprototype>
</funcsynopsis>
@@ -501,17 +506,16 @@ SELECT ST_AsText((ST_Dump(the_geom)).geom)
<refsection>
<title>Description</title>
- <para>Return a geometry collection with elements that match the specified range of
- measures inclusively.</para>
+ <para>Return a geometry (collection) with the portions of the input measured geometry
+ that match the specified measure range (inclusively).</para>
- <para>Clipping a non-convex POLYGON may produce invalid geometry.</para>
+ <para>If the <varname>offset</varname> is provided, the result
+ is offset to the left or right of the input line by the specified distance.
+ A positive offset will be to the left, and a negative one to the right.</para>
- <para>If an offset is provided, the resultant will be offset to the left or right of the
- input line by the specified number of units. A positive offset will be to the left, and
- a negative one to the right.</para>
+ <para>Clipping a non-convex POLYGON may produce invalid geometry.</para>
- <para>Semantic is specified by: ISO/IEC CD 13249-3:200x(E) - Text for Continuation
- CD Editing Meeting</para>
+ <para>The semantic is specified by the <emphasis>ISO/IEC 13249-3 SQL/MM Spatial</emphasis> standard.</para>
<para>Availability: 1.1.0 by old name ST_Locate_Between_Measures. </para>
<para>Changed: 2.0.0 - in prior versions this used to be called ST_Locate_Between_Measures.</para>
@@ -523,42 +527,24 @@ SELECT ST_AsText((ST_Dump(the_geom)).geom)
<refsection>
<title>Examples</title>
- <programlisting>
-SELECT ST_AsText(the_geom)
-FROM (
- SELECT ST_LocateBetween(
- 'MULTILINESTRING M ((1 2 3, 3 4 2, 9 4 3),(1 2 3, 5 4 5))'),
+<programlisting>
+SELECT ST_AsText(
+ ST_LocateBetween(
+ 'MULTILINESTRING M ((1 2 3, 3 4 2, 9 4 3),(1 2 3, 5 4 5))':: geometry,
1.5,
- 3
- ) as the_geom
-) As foo;
+ 3 ));
st_asewkt
------------------------------------------------------------------------
GEOMETRYCOLLECTION M (LINESTRING M (1 2 3,3 4 2,9 4 3),POINT M (1 2 3))
-
---Geometry collections are difficult animals so dump them
---to make them more digestable
-SELECT ST_AsText((ST_Dump(the_geom)).geom)
-FROM (
- SELECT ST_LocateBetween(
- 'MULTILINESTRING M ((1 2 3, 3 4 2, 9 4 3),(1 2 3, 5 4 5))'),
- 1.5,
- 3
- ) As the_geom
-) As foo;
-
- st_asewkt
---------------------------------
- LINESTRING M (1 2 3,3 4 2,9 4 3)
- POINT M (1 2 3)</programlisting>
+</programlisting>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection>
<title>See Also</title>
- <para><xref linkend="ST_Dump" />, <xref linkend="ST_LocateAlong" />, <xref linkend="ST_LocateBetweenElevations" /></para>
+ <para><xref linkend="ST_LocateAlong" />, <xref linkend="ST_LocateBetweenElevations" /></para>
</refsection>
</refentry>
@@ -567,7 +553,7 @@ FROM (
<refname>ST_LocateBetweenElevations</refname>
<refpurpose>Returns the portions of a geometry
- that intersect an elevation range.</refpurpose>
+ that lie in an elevation (Z) range.</refpurpose>
</refnamediv>
<refsynopsisdiv>
@@ -585,8 +571,8 @@ FROM (
<refsection>
<title>Description</title>
- <para>Returns a geometry (collection) value with elements
- that intersect the specified range of elevations inclusively.</para>
+ <para>Returns a geometry (collection) with the portions of a geometry
+ that lie in an elevations (Z) range.</para>
<para>Clipping a non-convex POLYGON may produce invalid geometry.</para>
@@ -599,28 +585,23 @@ FROM (
<refsection>
<title>Examples</title>
- <programlisting>SELECT ST_AsEWKT(ST_LocateBetweenElevations(
- ST_GeomFromEWKT('LINESTRING(1 2 3, 4 5 6)'), 2, 4)) As ewelev;
- ewelev
-----------------------------------------------------------------
- MULTILINESTRING((1 2 3,2 3 4))
+<programlisting>SELECT ST_AsText(
+ ST_LocateBetweenElevations(
+ 'LINESTRING(1 2 3, 4 5 6)'::geometry,
+ 2, 4 ));
-SELECT ST_AsEWKT(ST_LocateBetweenElevations('LINESTRING(1 2 6, 4 5 -1, 7 8 9)', 6, 9)) As ewelev;
+ st_astext
+-----------------------------------
+ MULTILINESTRING Z ((1 2 3,2 3 4))
- ewelev
-----------------------------------------------------------------
-GEOMETRYCOLLECTION(POINT(1 2 6),LINESTRING(6.1 7.1 6,7 8 9))
+SELECT ST_AsText(
+ ST_LocateBetweenElevations(
+ 'LINESTRING(1 2 6, 4 5 -1, 7 8 9)',
+ 6, 9)) As ewelev;
--- Geometry collections are difficult animals so dump them
--- to make them more digestable
-SELECT ST_AsEWKT((ST_Dump(the_geom)).geom)
- FROM
- (SELECT ST_LocateBetweenElevations('LINESTRING(1 2 6, 4 5 -1, 7 8 9)', 6, 9) as the_geom) As foo;
-
- st_asewkt
---------------------------------
-POINT(1 2 6)
-LINESTRING(6.1 7.1 6,7 8 9)
+ ewelev
+-----------------------------------------------------------------------
+ GEOMETRYCOLLECTION Z (POINT Z (1 2 6),LINESTRING Z (6.1 7.1 6,7 8 9))
</programlisting>
</refsection>
@@ -667,7 +648,7 @@ LINESTRING(6.1 7.1 6,7 8 9)
<programlisting>SELECT ST_InterpolatePoint('LINESTRING M (0 0 0, 10 0 20)', 'POINT(5 5)');
st_interpolatepoint
---------------------
- 10
+ 10
</programlisting>
</refsection>
-----------------------------------------------------------------------
Summary of changes:
doc/reference_lrs.xml | 243 +++++++++++++++++++++++---------------------------
1 file changed, 112 insertions(+), 131 deletions(-)
hooks/post-receive
--
PostGIS
More information about the postgis-tickets
mailing list