<?xml version="1.0" encoding="UTF-8"?>
<sect1 id="Linear_Referencing">
<title>Linear Referencing</title>
<refentry id="ST_LineInterpolatePoint">
<refnamediv>
<refname>ST_LineInterpolatePoint</refname>
<refpurpose>Returns a point interpolated along a line at a fractional location.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>geometry <function>ST_LineInterpolatePoint</function></funcdef>
<paramdef><type>geometry </type> <parameter>a_linestring</parameter></paramdef>
<paramdef><type>float8 </type> <parameter>a_fraction</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<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 float between 0 and 1
representing the fraction of line 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>
</note>
<para>Availability: 0.8.2, Z and M supported added in 1.1.1</para>
<para>Changed: 2.1.0. Up to 2.0.x this was called ST_Line_Interpolate_Point.</para>
<para>&Z_support;</para>
</refsection>
<refsection>
<title>Examples</title>
<informalfigure>
<mediaobject>
<imageobject>
<imagedata fileref="images/st_line_interpolate_point01.png" />
</imageobject>
<caption><para>A LineString with the interpolated point at 20% position (0.20) </para></caption>
</mediaobject>
</informalfigure>
<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>
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;
st_astext
------------
POINT(3 4)
</programlisting>
</refsection>
<refsection>
<title>See Also</title>
<para>
<xref linkend="ST_LineInterpolatePoints" />,
<xref linkend="ST_3DLineInterpolatePoint" />,
<xref linkend="ST_LineLocatePoint" />
</para>
</refsection>
</refentry>
<refentry id="ST_3DLineInterpolatePoint">
<refnamediv>
<refname>ST_3DLineInterpolatePoint</refname>
<refpurpose>Returns a point interpolated along a 3D line at a fractional location.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>geometry <function>ST_3DLineInterpolatePoint</function></funcdef>
<paramdef><type>geometry </type> <parameter>a_linestring</parameter></paramdef>
<paramdef><type>float8 </type> <parameter>a_fraction</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<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 float between 0 and 1
representing the point location as a fraction of line length.
The M value is interpolated if present.
</para>
<note>
<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>
</refsection>
<refsection>
<title>Examples</title>
<para>Return point 20% along 3D line</para>
<programlisting>
SELECT ST_AsText(
ST_3DLineInterpolatePoint('LINESTRING(25 50 70, 100 125 90, 150 190 200)',
0.20));
st_asetext
----------------
POINT Z (59.0675892910822 84.0675892910822 79.0846904776219)
</programlisting>
</refsection>
<refsection>
<title>See Also</title>
<para>
<xref linkend="ST_LineInterpolatePoint" />,
<xref linkend="ST_LineInterpolatePoints" />,
<xref linkend="ST_LineLocatePoint" />
</para>
</refsection>
</refentry>
<refentry id="ST_LineInterpolatePoints">
<refnamediv>
<refname>ST_LineInterpolatePoints</refname>
<refpurpose>
Returns points interpolated along a line at a fractional interval.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>geometry <function>ST_LineInterpolatePoints</function></funcdef>
<paramdef><type>geometry </type> <parameter>a_linestring</parameter></paramdef>
<paramdef><type>float8 </type> <parameter>a_fraction</parameter></paramdef>
<paramdef><type>boolean </type> <parameter>repeat</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Returns one or more points interpolated along a line at a fractional interval.
The first argument
must be a LINESTRING. The second argument is a float8 between 0 and 1
representing the spacing between the points as a fraction of
line length. If the third argument is false, at most one point
will be constructed (the function will be equivalent to <xref linkend="ST_LineInterpolatePoint" />.)
</para>
<para>
If the result has zero or one points, it will be returned as a POINT.
If it has two or more points, it will be returned as a MULTIPOINT.
</para>
<para>Availability: 2.5.0</para>
<para>&Z_support;</para>
<para>&M_support;</para>
</refsection>
<refsection>
<title>Examples</title>
<informalfigure>
<mediaobject>
<imageobject>
<imagedata fileref="images/st_line_interpolate_points01.png" />
</imageobject>
<caption><para>A LineString with the interpolated points every 20% </para></caption>
</mediaobject>
</informalfigure>
<programlisting>--Return points each 20% along a 2D line
SELECT ST_AsText(ST_LineInterpolatePoints('LINESTRING(25 50, 100 125, 150 190)', 0.20))
st_astext
----------------
MULTIPOINT(51.5974135047432 76.5974135047432,78.1948270094864 103.194827009486,104.132163186446 130.37181214238,127.066081593223 160.18590607119,150 190)
</programlisting>
</refsection>
<refsection>
<title>See Also</title>
<para>
<xref linkend="ST_LineInterpolatePoint" />
<xref linkend="ST_LineLocatePoint" />
</para>
</refsection>
</refentry>
<refentry id="ST_LineLocatePoint">
<refnamediv>
<refname>ST_LineLocatePoint</refname>
<refpurpose>Returns the fractional location of
the closest point on a line to a point.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>float8 <function>ST_LineLocatePoint</function></funcdef>
<paramdef><type>geometry </type> <parameter>a_linestring</parameter></paramdef>
<paramdef><type>geometry </type> <parameter>a_point</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Returns a float between 0 and 1 representing the location of
the closest point on a LineString to the given Point, as a fraction
of <link linkend="ST_Length2D">2d line</link> length.</para>
<para>You can use the returned location to extract a Point (<xref linkend="ST_LineInterpolatePoint" />) or
a substring (<xref linkend="ST_LineSubstring" />).</para>
<para>This is useful for approximating numbers of addresses</para>
<para>Availability: 1.1.0</para>
<para>Changed: 2.1.0. Up to 2.0.x this was called ST_Line_Locate_Point.</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>
--Rough approximation of finding the street number of a point along the street
--Note the whole foo thing is just to generate dummy data that looks
--like house centroids and street
--We use ST_DWithin to exclude
--houses too far away from the street to be considered on the street
SELECT ST_AsText(house_loc) As as_text_house_loc,
startstreet_num +
CAST( (endstreet_num - startstreet_num)
* ST_LineLocatePoint(street_line, house_loc) As integer) As street_num
FROM
(SELECT ST_GeomFromText('LINESTRING(1 2, 3 4)') As street_line,
ST_Point(x*1.01,y*1.03) As house_loc, 10 As startstreet_num,
20 As endstreet_num
FROM generate_series(1,3) x CROSS JOIN generate_series(2,4) As y)
As foo
WHERE ST_DWithin(street_line, house_loc, 0.2);
as_text_house_loc | street_num
-------------------+------------
POINT(1.01 2.06) | 10
POINT(2.02 3.09) | 15
POINT(3.03 4.12) | 20
--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
----------------
POINT(3 4)
</programlisting>
</refsection>
<refsection>
<title>See Also</title>
<para><xref linkend="ST_DWithin" />, <xref linkend="ST_Length2D" />, <xref linkend="ST_LineInterpolatePoint" />, <xref linkend="ST_LineSubstring" /></para>
</refsection>
</refentry>
<refentry id="ST_LineSubstring">
<refnamediv>
<refname>ST_LineSubstring</refname>
<refpurpose>Returns the part of a line between two fractional locations.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>geometry <function>ST_LineSubstring</function></funcdef>
<paramdef><type>geometry </type> <parameter>a_linestring</parameter></paramdef>
<paramdef><type>float8 </type> <parameter>startfraction</parameter></paramdef>
<paramdef><type>float8 </type> <parameter>endfraction</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Computes the line which is the section of the input line
starting and ending at the given fractional locations.
The first argument must be a LINESTRING.
The second and third arguments are values in the range [0, 1]
representing the start and end locations
as fractions of line length.
The Z and M values are interpolated for added endpoints if present.
</para>
<para>If <varname>startfraction</varname> and <varname>endfraction</varname>
have the same value this is equivalent
to <xref linkend="ST_LineInterpolatePoint" />.</para>
<note>
<para>This only works with LINESTRINGs.
To use on contiguous MULTILINESTRINGs
first join them with <xref linkend="ST_LineMerge" />.</para>
</note>
<note>
<para>Since release 1.1.1 this function interpolates M and
Z values. Prior releases set Z and M to
unspecified values.</para>
</note>
<para>Availability: 1.1.0, Z and M supported added in 1.1.1</para>
<para>Changed: 2.1.0. Up to 2.0.x this was called ST_Line_Substring.</para>
<para>&Z_support;</para>
</refsection>
<refsection>
<title>Examples</title>
<informalfigure>
<mediaobject>
<imageobject>
<imagedata fileref="images/st_line_substring01.png" />
</imageobject>
<caption><para>A LineString seen with 1/3 midrange overlaid (0.333, 0.666) </para></caption>
</mediaobject>
</informalfigure>
<programlisting>
SELECT ST_AsText(ST_LineSubstring( 'LINESTRING(25 50, 100 125, 150 190)', 0.333, 0.666));
st_astext
------------------------------------------------------------------------------------------------
LINESTRING(69.2846934853974 94.2846934853974,100 125,111.700356260683 140.210463138888)
</programlisting>
<para>
If start and end locations are the same, the result is a POINT.
</para>
<programlisting>
SELECT ST_AsText(ST_LineSubstring( 'LINESTRING(25 50, 100 125, 150 190)', 0.333, 0.333));
st_astext
------------------------------------------
POINT(69.2846934853974 94.2846934853974)
</programlisting>
<para>
A query to cut a LineString into sections of length 100 or shorter.
It uses <varname>generate_series()</varname> with a CROSS JOIN LATERAL
to produce the equivalent of a FOR loop.
</para>
<programlisting>
WITH data(id, geom) AS (VALUES
( 'A', 'LINESTRING( 0 0, 200 0)'::geometry ),
( 'B', 'LINESTRING( 0 100, 350 100)'::geometry ),
( 'C', 'LINESTRING( 0 200, 50 200)'::geometry )
)
SELECT id, i,
ST_AsText( ST_LineSubstring( geom, startfrac, LEAST( endfrac, 1 )) ) AS geom
FROM (
SELECT id, geom, ST_Length(geom) len, 100 sublen FROM data
) AS d
CROSS JOIN LATERAL (
SELECT i, (sublen * i) / len AS startfrac,
(sublen * (i+1)) / len AS endfrac
FROM generate_series(0, floor( len / sublen )::integer ) AS t(i)
-- skip last i if line length is exact multiple of sublen
WHERE (sublen * i) / len <> 1.0
) AS d2;
id | i | geom
----+---+-----------------------------
A | 0 | LINESTRING(0 0,100 0)
A | 1 | LINESTRING(100 0,200 0)
B | 0 | LINESTRING(0 100,100 100)
B | 1 | LINESTRING(100 100,200 100)
B | 2 | LINESTRING(200 100,300 100)
B | 3 | LINESTRING(300 100,350 100)
C | 0 | LINESTRING(0 200,50 200)
</programlisting>
</refsection>
<refsection>
<title>See Also</title>
<para><xref linkend="ST_Length" />, <xref linkend="ST_LineInterpolatePoint" />, <xref linkend="ST_LineMerge" /></para>
</refsection>
</refentry>
<refentry id="ST_LocateAlong">
<refnamediv>
<refname>ST_LocateAlong</refname>
<refpurpose>Returns the point(s) on a geometry that match a measure value.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>geometry <function>ST_LocateAlong</function></funcdef>
<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>
<refsection>
<title>Description</title>
<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>
<note><para>Use this function only for geometries with an M component</para></note>
<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>
<para>&M_support;</para>
</refsection>
<refsection>
<title>Examples</title>
<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>
<refsection>
<title>See Also</title>
<para><xref linkend="ST_LocateBetween" />, <xref linkend="ST_LocateBetweenElevations" /></para>
</refsection>
</refentry>
<refentry id="ST_LocateBetween">
<refnamediv>
<refname>ST_LocateBetween</refname>
<refpurpose>Returns the portions of a geometry that match a measure range.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>geometry <function>ST_LocateBetween</function></funcdef>
<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 = 0</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Return a geometry (collection) with the portions of the input measured geometry
that match the specified measure range (inclusively).</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>Clipping a non-convex POLYGON may produce invalid geometry.</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>
<para>Enhanced: 3.0.0 - added support for POLYGON, TIN, TRIANGLE.</para>
<para>&M_support;</para>
</refsection>
<refsection>
<title>Examples</title>
<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 ));
st_asewkt
------------------------------------------------------------------------
GEOMETRYCOLLECTION M (LINESTRING M (1 2 3,3 4 2,9 4 3),POINT M (1 2 3))
</programlisting>
</refsection>
<refsection>
<title>See Also</title>
<para><xref linkend="ST_LocateAlong" />, <xref linkend="ST_LocateBetweenElevations" /></para>
</refsection>
</refentry>
<refentry id="ST_LocateBetweenElevations">
<refnamediv>
<refname>ST_LocateBetweenElevations</refname>
<refpurpose>Returns the portions of a geometry
that lie in an elevation (Z) range.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>geometry <function>ST_LocateBetweenElevations</function></funcdef>
<paramdef><type>geometry </type> <parameter>geom</parameter></paramdef>
<paramdef><type>float8 </type> <parameter>elevation_start</parameter></paramdef>
<paramdef><type>float8 </type> <parameter>elevation_end</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<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>
<para>Availability: 1.4.0</para>
<para>Enhanced: 3.0.0 - added support for POLYGON, TIN, TRIANGLE.</para>
<para>&Z_support;</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>SELECT ST_AsText(
ST_LocateBetweenElevations(
'LINESTRING(1 2 3, 4 5 6)'::geometry,
2, 4 ));
st_astext
-----------------------------------
MULTILINESTRING Z ((1 2 3,2 3 4))
SELECT ST_AsText(
ST_LocateBetweenElevations(
'LINESTRING(1 2 6, 4 5 -1, 7 8 9)',
6, 9)) As ewelev;
ewelev
-----------------------------------------------------------------------
GEOMETRYCOLLECTION Z (POINT Z (1 2 6),LINESTRING Z (6.1 7.1 6,7 8 9))
</programlisting>
</refsection>
<refsection>
<title>See Also</title>
<para><xref linkend="ST_Dump" />, <xref linkend="ST_LocateBetween" /></para>
</refsection>
</refentry>
<refentry id="ST_InterpolatePoint">
<refnamediv>
<refname>ST_InterpolatePoint</refname>
<refpurpose>Returns the interpolated measure of a geometry closest to a point.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>float8 <function>ST_InterpolatePoint</function></funcdef>
<paramdef><type>geometry </type> <parameter>line</parameter></paramdef>
<paramdef><type>geometry </type> <parameter>point</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Returns the value of the measure dimension of a geometry at the point closed to the provided point.</para>
<para>Availability: 2.0.0</para>
<para>&Z_support;</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>SELECT ST_InterpolatePoint('LINESTRING M (0 0 0, 10 0 20)', 'POINT(5 5)');
st_interpolatepoint
---------------------
10
</programlisting>
</refsection>
<refsection>
<title>See Also</title>
<para><xref linkend="ST_AddMeasure" />, <xref linkend="ST_LocateAlong" />, <xref linkend="ST_LocateBetween" /></para>
</refsection>
</refentry>
<refentry id="ST_AddMeasure">
<refnamediv>
<refname>ST_AddMeasure</refname>
<refpurpose>Interpolates measures along a linear geometry.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>geometry <function>ST_AddMeasure</function></funcdef>
<paramdef><type>geometry </type> <parameter>geom_mline</parameter></paramdef>
<paramdef><type>float8 </type> <parameter>measure_start</parameter></paramdef>
<paramdef><type>float8 </type> <parameter>measure_end</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Return a derived geometry with measure values linearly interpolated between the start and end points. If the geometry has no measure dimension, one is added. If the geometry has a measure dimension, it is over-written with new values. Only LINESTRINGS and MULTILINESTRINGS are supported.</para>
<para>Availability: 1.5.0</para>
<para>&Z_support;</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>SELECT ST_AsText(ST_AddMeasure(
ST_GeomFromEWKT('LINESTRING(1 0, 2 0, 4 0)'),1,4)) As ewelev;
ewelev
--------------------------------
LINESTRINGM(1 0 1,2 0 2,4 0 4)
SELECT ST_AsText(ST_AddMeasure(
ST_GeomFromEWKT('LINESTRING(1 0 4, 2 0 4, 4 0 4)'),10,40)) As ewelev;
ewelev
----------------------------------------
LINESTRING(1 0 4 10,2 0 4 20,4 0 4 40)
SELECT ST_AsText(ST_AddMeasure(
ST_GeomFromEWKT('LINESTRINGM(1 0 4, 2 0 4, 4 0 4)'),10,40)) As ewelev;
ewelev
----------------------------------------
LINESTRINGM(1 0 10,2 0 20,4 0 40)
SELECT ST_AsText(ST_AddMeasure(
ST_GeomFromEWKT('MULTILINESTRINGM((1 0 4, 2 0 4, 4 0 4),(1 0 4, 2 0 4, 4 0 4))'),10,70)) As ewelev;
ewelev
-----------------------------------------------------------------
MULTILINESTRINGM((1 0 10,2 0 20,4 0 40),(1 0 40,2 0 50,4 0 70))
</programlisting>
</refsection>
</refentry>
</sect1>