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 given geometry that has exactly the specified measure of the given 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 given measure is not found, then an empty geometry is returned. For all other geometries, if the given 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 given geometry is null, then null is returned.

This function can also be called as a method.

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

db2gse.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.


SET CURRENT FUNCTION PATH = CURRENT FUNCTION PATH, db2gse 

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. The first row returns a point. However, the second row returns an empty point. 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.


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

Results:


ID     MEASURE_7
------ ---------------------------------------------
     1 POINT M ( 3.50000000 3.50000000 7.00000000)
     2 POINT EMPTY

Example 3

In the following SELECT statement and the corresponding result set, the ST_FindMeasure function returns a point and a multipoint. 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      POINT M ( 3.00000000 3.00000000 6.00000000) 
                                                          
2      MULTIPOINT M ( 3.00000000 3.00000000 6.00000000, 4.00000000 
        4.00000000 6.00000000, 5.00000000 5.00000000 6.00000000)