ST_FindMeasure or ST_LocateAlong function

The ST_FindMeasure or ST_LocateAlong function takes a geometry and a measure as input parameters and returns a multipoint or multicurve of that part of the specified geometry that has exactly the specified measure of the specified geometry that contains the specified measure.

For points and multipoints, all the points with the specified measure are returned. For curves, multicurves, surfaces, and multisurfaces, interpolation is performed to compute the result. The computation for surfaces and multisurfaces is performed on the boundary of the geometry.

For points and multipoints, if the specified measure is not found, then an empty geometry is returned. For all other geometries, if the specified measure is lower than the lowest measure in the geometry or higher than the highest measure in the geometry, then an empty geometry is returned. If the specified geometry is null, then null is returned.

Syntax

Parameter

geometry: A value of type ST_Geometry or one of its subtypes that represents the geometry in which to search for parts whose M coordinates (measures) contain measure.
measure: A value of type DOUBLE that is the measure that the parts of geometry must be included in the result.

Return type

ST_Geometry

Examples

Example 1

The following CREATE TABLE statement creates the SAMPLE_GEOMETRIES table. SAMPLE_GEOMETRIES has two columns: the ID column, which uniquely identifies each row, and the GEOMETRY ST_Geometry column, which stores sample geometry.


CREATE TABLE sample_geometries(id SMALLINT, geometry ST_GEOMETRY)

The following INSERT statements insert two rows. The first is a linestring; the second is a multipoint.


INSERT INTO sample_geometries(id, geometry)
VALUES
  (1, ST_LineString('linestring m (2 2 3, 3 5 3, 3 3 6, 4 4 8)', 1)),
  (2, ST_MultiPoint('multipoint m 
      (2 2 3, 3 5 3, 3 3 6, 4 4 6, 5 5 6, 6 6 8)', 1))

Example 2

In the following SELECT statement and the corresponding result set, the ST_FindMeasure function is directed to find points whose measure is 7. For linear features (geometry with a dimension greater than 0), ST_FindMeasure can interpolate the point; however, for multipoints, the target measure must match exactly. The second result is therefore an empty point.


SELECT id, cast(ST_AsText(ST_FindMeasure(geometry, 7)) 
   AS varchar(45)) AS measure_7
FROM   sample_geometries

Results:


ID     MEASURE_7
------ ---------------------------------------------
     1 MULTIPOINT M(3.500000 3.500000 7)
     2 POINT EMPTY

Example 3

In the following SELECT statement and the corresponding result set, the target measure of 6 matches the measures in both the ST_FindMeasure and multipoint source data.


SELECT id, cast(ST_AsText(ST_FindMeasure(geometry, 6))
   AS varchar(120)) AS measure_6
FROM   sample_geometries

Results:


ID     MEASURE_6                                                                                            
------ --------------------------------------------------------------     
     1 MULTIPOINT M(3.000000 3.000000 6)                                          
     2 MULTIPOINT M(3.000000 3.000000 6, 4.000000 4.000000 6, 
        5.000000 5.000000 6)