This topic describes the ST_FilterByM function. This function filters out the vertexes of the input geometry object based on the m coordinates of the input geometry object and returns a new geometry object.

Syntax

geometry  ST_FilterByM(geometry  geom , double precision  min , double precision  max , boolean  returnM);

Parameters

Parameter Description
geom The geometry object that you want to specify.
min The minimum value of the m coordinate for the input geometry object. Default value: null.
max The maximum value of the m coordinate for the input geometry object. Default value: null.
returnM Specifies whether to return the m coordinates of the new geometry object. Default value: false.

Description

  • This function returns a new geometry object for which the m coordinate of a vertex is greater than or equal to the value of the min parameter and less than or equal to the value of the max parameter.

    If this function ignores the max parameter, only the min parameter takes effect.

  • If a small number of vertexes are generated after the filtering, this function returns an empty geometry object.
  • If you specify a GeometryCollection object, this function ignores the objects that do not contain enough points.
  • If the input geometry object does not contain enough points, the ST_SimplifyVW function returns a geometry object that contains enough points while the ST_FilterByM function returns an empty geometry object.
  • This function may return an invalid geometry object.
  • The returned geometry object includes all dimensions of the input geometry object, including z and m coordinates.

Examples

  • Results returned by using the default parameter settings:
    SELECT ST_AsText(ST_FilterByM('LINESTRINGM(0 0 0,1 1 1,2 2 2,3 3 3)'::geometry,2,4,true));
         st_astext
----------------------------
 LINESTRING M (2 2 2,3 3 3)
(1 row)
  • Results returned when the function cannot return a geometry object:
    SELECT ST_AsText(ST_FilterByM('LINESTRINGM(0 0 0,1 1 1,2 2 2,3 3 3)'::geometry,3,4,true));
     st_astext
--------------------
 LINESTRING M EMPTY
(1 row)