The ST_LocateAlong() function

The ST_LocateAlong() function takes a geometry object and a measure to return as an ST_MultiPoint the set of points found having that measure.

Syntax

ST_LocateAlong(g1 ST_Geometry, m1 double precision)

Usage

SE_LocateAlong() returns the location as an ST_MultiPoint.

If the source geometry's dimension is 0 (for ST_Point and ST_MultiPoint), only points with a matching measure value are returned as an ST_MultiPoint. However, for source geometries whose dimension is greater than 0, the location is interpolated. For example, if the requested measure value is 5.5 and the ST_LineString vertices have measures of 3, 4, 5, 6, and 7, an interpolated point that falls exactly halfway between the vertices with measure values 5 and 6 is returned.

SE_LocateAlong() locates a point on a linestring by interpolating the given measure value, if necessary. The following figure shows a case where a point with measure 5.5 is interpolated halfway between the vertices of the ST_LineString with measures 5 and 6. For ST_MultiPoints, an exact match is required. In the case of the above ST_MultiPoint, SE_LocateAlong() returns the point that has measure 5.5.
Figure 1: The SE_LocateAlong function

This graphic is described in the surrounding text.

Return type

ST_Geometry

Example

The locatealong_test table is created with two columns: the gid column uniquely identifies each row, and the g1 ST_Geometry column stores sample geometry: 
CREATE TABLE locatealong_test (gid integer,
                               g1  ST_Geometry);
The following INSERT statements insert two rows. The first is a multilinestring, while the second is a multipoint: 
INSERT INTO locatealong_test VALUES(
   1,
   ST_MLineFromText('multilinestring m ((10.29 19.23 5,23.82 20.29
6,30.19 18.47 7,45.98 20.74 8),(23.82 20.29 6,30.98 23.98 7,42.92
25.98 8))', 1000)
);

INSERT INTO locatealong_test VALUES(
   2,
   ST_MPointFromText('multipoint m (10.29 19.23 5,23.82 20.29
6,30.19 18.47 7,45.98 20.74 8,23.82 20.29 6,30.98 23.98 7,42.92
25.98 8)', 1000)
);
In this query, the ST_LocateAlong() function finds points whose measure is 6.5. The first row returns an ST_MultiPoint containing two points. However, the second row returns an empty point. For linear features (geometry with a dimension greater than 0), ST_LocateAlong() can interpolate the point, but for multipoints the target measure must match exactly: 
SELECT gid, SE_locatealong(g1,6.5) Geometry
   FROM locatealong_test;


gid       1
geometry  1000 MULTIPOINT M (27.005 19.38 6.5, 27.4 22.135 6.5) 

gid       2
geometry  1000 POINT M EMPTY
In this query, the ST_LocateAlong() function returns a multipoint for both rows. The target measure of 7 matches measures in the multilinestring and multipoint source data: 
SELECT gid, SE_locatealong(g1,7) Geometry
   FROM locatealong_test;


gid       1
geometry  1000 MULTIPOINT M (30.19 18.47 7, 30.98 23.98 7) 

gid       2
geometry  1000 MULTIPOINT M (30.19 18.47 7, 30.98 23.98 7)