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.

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