# Linear Referencing

ST_LineInterpolatePoint

Returns a point interpolated along a line. Second argument is a float8 between 0 and 1 representing fraction of total length of linestring the point has to be located.

    				geometry ST_LineInterpolatePoint
    				geometry  a_linestring
    				float8  a_fraction

### Description

Returns a point interpolated along a line. First argument must be a LINESTRING. Second argument is a float8 between 0 and 1 representing fraction of total linestring length the point has to be located.

See ST_LineLocatePoint for computing the line location nearest to a Point.

Since release 1.1.1 this function also interpolates M and Z values (when present), while prior releases set them to 0.0.

Availability: 0.8.2, Z and M supported added in 1.1.1

Changed: 2.1.0. Up to 2.0.x this was called ST_Line_Interpolate_Point.

&Z_support;

### Examples

A linestring with the interpolated point at 20% position (0.20)

    --Return point 20% along 2d line
    SELECT ST_AsEWKT(ST_LineInterpolatePoint(the_line, 0.20))
    	FROM (SELECT ST_GeomFromEWKT('LINESTRING(25 50, 100 125, 150 190)') as the_line) As foo;
       st_asewkt
    ----------------
     POINT(51.5974135047432 76.5974135047432)

    --Return point mid-way of 3d line
    SELECT ST_AsEWKT(ST_LineInterpolatePoint(the_line, 0.5))
    	FROM (SELECT ST_GeomFromEWKT('LINESTRING(1 2 3, 4 5 6, 6 7 8)') as the_line) As foo;

    	st_asewkt
    --------------------
     POINT(3.5 4.5 5.5)

    --find closest point on a line to a point or other geometry
     SELECT ST_AsText(ST_LineInterpolatePoint(foo.the_line, ST_LineLocatePoint(foo.the_line, ST_GeomFromText('POINT(4 3)'))))
    FROM (SELECT ST_GeomFromText('LINESTRING(1 2, 4 5, 6 7)') As the_line) As foo;
       st_astext
    ----------------
     POINT(3 4)

### See Also

ST_AsText, ST_AsEWKT, ST_Length, ST_LineInterpolatePoints ST_3DLineInterpolatePoint ST_LineLocatePoint O

ST_3DLineInterpolatePoint

Returns a point interpolated along a line in 3D. Second argument is a float8 between 0 and 1 representing fraction of total length of linestring the point has to be located.

    				geometry ST_LineInterpolatePoint
    				geometry  a_linestring
    				float8  a_fraction

### Description

Returns a point interpolated along a line. First argument must be a LINESTRING. Second argument is a float8 between 0 and 1 representing fraction of total linestring length the point has to be located.

ST_LineInterpolatePoint computes resulting point in 2D and then interpolates value for Z and M, while ST_3DLineInterpolatePoint computes directly point in 3D and only M value is interpolated then.

Availability: 3.0.0

### Examples

Return point 20% along 3D line

    SELECT ST_AsEWKT(ST_3DLineInterpolatePoint(the_line, 0.20))
    	FROM (SELECT ST_GeomFromEWKT('LINESTRING(25 50 70, 100 125 90, 150 190 200)') as the_line) As foo;
       st_asewkt
    ----------------
     POINT(59.0675892910822 84.0675892910822 79.0846904776219)

### See Also

ST_AsText, ST_AsEWKT, ST_Length, ST_LineInterpolatePoint ST_LineInterpolatePoints ST_LineLocatePoint

ST_LineInterpolatePoints

Returns one or more points interpolated along a line.

    				geometry ST_LineInterpolatePoints
    				geometry  a_linestring
    				float8  a_fraction
    				boolean  repeat

### Description

Returns one or more points interpolated along a line. First argument must be a LINESTRING. Second argument is a float8 between 0 and 1 representing the spacing between the points as a fraction of total LineString length. If the third argument is false, at most one point will be constructed (the function will be equivalent to ST_LineInterpolatePoint.)

If the result has zero or one points, it will be returned as a POINT. If it has two or more points, it will be returned as a MULTIPOINT.

Availability: 2.5.0

&Z_support;

&M_support;

### Examples

A linestring with the interpolated points every 20%

    --Return points each 20% along a 2D line
    SELECT ST_AsText(ST_LineInterpolatePoints('LINESTRING(25 50, 100 125, 150 190)', 0.20))
       st_astext
    ----------------
     MULTIPOINT(51.5974135047432 76.5974135047432,78.1948270094864 103.194827009486,104.132163186446 130.37181214238,127.066081593223 160.18590607119,150 190)

### See Also

ST_LineInterpolatePoint ST_LineLocatePoint

ST_LineLocatePoint

Returns a float between 0 and 1 representing the location of the closest point on LineString to the given Point, as a fraction of total 2d line length.

    				float8 ST_LineLocatePoint
    				geometry  a_linestring
    				geometry  a_point

### Description

Returns a float between 0 and 1 representing the location of the closest point on LineString to the given Point, as a fraction of total 2d line length.

You can use the returned location to extract a Point (ST_LineInterpolatePoint) or a substring (ST_LineSubstring).

This is useful for approximating numbers of addresses

Availability: 1.1.0

Changed: 2.1.0. Up to 2.0.x this was called ST_Line_Locate_Point.

### Examples

    --Rough approximation of finding the street number of a point along the street
    --Note the whole foo thing is just to generate dummy data that looks
    --like house centroids and street
    --We use ST_DWithin to exclude
    --houses too far away from the street to be considered on the street
    SELECT ST_AsText(house_loc) As as_text_house_loc,
    	startstreet_num +
    		CAST( (endstreet_num - startstreet_num)
    			* ST_LineLocatePoint(street_line, house_loc) As integer) As street_num
    FROM
    (SELECT ST_GeomFromText('LINESTRING(1 2, 3 4)') As street_line,
    	ST_MakePoint(x*1.01,y*1.03) As house_loc, 10 As startstreet_num,
    		20 As endstreet_num
    FROM generate_series(1,3) x CROSS JOIN generate_series(2,4) As y)
    As foo
    WHERE ST_DWithin(street_line, house_loc, 0.2);

     as_text_house_loc | street_num
    -------------------+------------
     POINT(1.01 2.06)  |         10
     POINT(2.02 3.09)  |         15
     POINT(3.03 4.12)  |         20

     --find closest point on a line to a point or other geometry
     SELECT ST_AsText(ST_LineInterpolatePoint(foo.the_line, ST_LineLocatePoint(foo.the_line, ST_GeomFromText('POINT(4 3)'))))
    FROM (SELECT ST_GeomFromText('LINESTRING(1 2, 4 5, 6 7)') As the_line) As foo;
       st_astext
    ----------------
     POINT(3 4)

### See Also

ST_DWithin, ST_Length2D, ST_LineInterpolatePoint, ST_LineSubstring

ST_LineSubstring

Return a linestring being a substring of the input one starting and ending at the given fractions of total 2d length. Second and third arguments are float8 values between 0 and 1.

    				geometry ST_LineSubstring
    				geometry  a_linestring
    				float8  startfraction
    				float8  endfraction

### Description

Return a linestring being a substring of the input one starting and ending at the given fractions of total 2d length. Second and third arguments are float8 values between 0 and 1. This only works with LINESTRINGs. To use with contiguous MULTILINESTRINGs use in conjunction with ST_LineMerge.

If 'start' and 'end' have the same value this is equivalent to ST_LineInterpolatePoint.

See ST_LineLocatePoint for computing the line location nearest to a Point.

Since release 1.1.1 this function also interpolates M and Z values (when present), while prior releases set them to unspecified values.

Availability: 1.1.0, Z and M supported added in 1.1.1

Changed: 2.1.0. Up to 2.0.x this was called ST_Line_Substring.

&Z_support;

### Examples

A linestring seen with 1/3 midrange overlaid (0.333, 0.666)

    --Return the approximate 1/3 mid-range part of a linestring
    SELECT ST_AsText(ST_Line_SubString(ST_GeomFromText('LINESTRING(25 50, 100 125, 150 190)'), 0.333, 0.666));

    										   st_astext
    ------------------------------------------------------------------------------------------------
    LINESTRING(69.2846934853974 94.2846934853974,100 125,111.700356260683 140.210463138888)

    --The below example simulates a while loop in
    --SQL using PostgreSQL generate_series() to cut all
    --linestrings in a table to 100 unit segments
    -- of which no segment is longer than 100 units
    -- units are measured in the SRID units of measurement
    -- It also assumes all geometries are LINESTRING or contiguous MULTILINESTRING
    --and no geometry is longer than 100 units*10000
    --for better performance you can reduce the 10000
    --to match max number of segments you expect

    SELECT field1, field2, ST_LineSubstring(the_geom, 100.00*n/length,
      CASE
    	WHEN 100.00*(n+1) < length THEN 100.00*(n+1)/length
    	ELSE 1
      END) As the_geom
    FROM
      (SELECT sometable.field1, sometable.field2,
      ST_LineMerge(sometable.the_geom) AS the_geom,
      ST_Length(sometable.the_geom) As length
      FROM sometable
      ) AS t
    CROSS JOIN generate_series(0,10000) AS n
    WHERE n*100.00/length < 1;

### See Also

ST_Length, ST_LineInterpolatePoint, ST_LineMerge

ST_LocateAlong

Return a derived geometry collection value with elements that match the specified measure. Polygonal elements are not supported.

    			geometry ST_LocateAlong
    			geometry  ageom_with_measure
    			float8  a_measure
    			float8  offset

### Description

Return a derived geometry collection value with elements that match the specified measure. Polygonal elements are not supported.

If an offset is provided, the resultant will be offset to the left or right of the input line by the specified number of units. A positive offset will be to the left, and a negative one to the right.

Semantic is specified by: ISO/IEC CD 13249-3:200x(E) - Text for Continuation CD Editing Meeting

Availability: 1.1.0 by old name ST_Locate_Along_Measure.

Changed: 2.0.0 in prior versions this used to be called ST_Locate_Along_Measure. The old name has been deprecated and will be removed in the future but is still available.

Use this function only for geometries with an M component

&M_support;

### Examples

    SELECT ST_AsText(the_geom)
    		FROM
    		(SELECT ST_LocateAlong(
    			ST_GeomFromText('MULTILINESTRINGM((1 2 3, 3 4 2, 9 4 3),
    		(1 2 3, 5 4 5))'),3) As the_geom) As foo;

    						 st_asewkt
    -----------------------------------------------------------
     MULTIPOINT M (1 2 3)

    --Geometry collections are difficult animals so dump them
    --to make them more digestable
    SELECT ST_AsText((ST_Dump(the_geom)).geom)
    	FROM
    	(SELECT ST_LocateAlong(
    			ST_GeomFromText('MULTILINESTRINGM((1 2 3, 3 4 2, 9 4 3),
    	(1 2 3, 5 4 5))'),3) As the_geom) As foo;

       st_asewkt
    ---------------
     POINTM(1 2 3)
     POINTM(9 4 3)
     POINTM(1 2 3)

### See Also

ST_Dump, ST_LocateBetween, ST_LocateBetweenElevations

ST_LocateBetween

Return a derived geometry collection value with elements that match the specified range of measures inclusively.

    			geometry ST_LocateBetween
    			geometry  geom
    			float8  measure_start
    			float8  measure_end
    			float8  offset

### Description

Return a derived geometry collection with elements that match the specified range of measures inclusively.

Clipping a non-convex POLYGON may produce invalid geometry.

If an offset is provided, the resultant will be offset to the left or right of the input line by the specified number of units. A positive offset will be to the left, and a negative one to the right.

Semantic is specified by: ISO/IEC CD 13249-3:200x(E) - Text for Continuation CD Editing Meeting

Availability: 1.1.0 by old name ST_Locate_Between_Measures.

Changed: 2.0.0 - in prior versions this used to be called ST_Locate_Between_Measures. The old name has been deprecated and will be removed in the future but is still available for backward compatibility.

Enhanced: 3.0.0 - added support for POLYGON, TIN, TRIANGLE.

&M_support;

### Examples

    SELECT ST_AsText(the_geom)
    FROM (
        SELECT ST_LocateBetween(
           'MULTILINESTRING M ((1 2 3, 3 4 2, 9 4 3),(1 2 3, 5 4 5))'),
           1.5,
           3
        ) as the_geom
    ) As foo;

    							 st_asewkt
    ------------------------------------------------------------------------
     GEOMETRYCOLLECTION M (LINESTRING M (1 2 3,3 4 2,9 4 3),POINT M (1 2 3))

    --Geometry collections are difficult animals so dump them
    --to make them more digestable
    SELECT ST_AsText((ST_Dump(the_geom)).geom)
    FROM (
        SELECT ST_LocateBetween(
    	'MULTILINESTRING M ((1 2 3, 3 4 2, 9 4 3),(1 2 3, 5 4 5))'),
    	1.5,
    	3
        ) As the_geom
    ) As foo;

    		   st_asewkt
    --------------------------------
     LINESTRING M (1 2 3,3 4 2,9 4 3)
     POINT M (1 2 3)

### See Also

ST_Dump, ST_LocateAlong, ST_LocateBetweenElevations

ST_LocateBetweenElevations

Return a derived geometry (collection) value with elements that intersect the specified range of elevations inclusively.

    			geometry ST_LocateBetweenElevations
    			geometry  geom
    			float8  elevation_start
    			float8  elevation_end

### Description

Return a derived geometry (collection) value with elements that intersect the specified range of elevations inclusively.

Clipping a non-convex POLYGON may produce invalid geometry.

Availability: 1.4.0

Enhanced: 3.0.0 - added support for POLYGON, TIN, TRIANGLE.

&Z_support;

### Examples

    SELECT ST_AsEWKT(ST_LocateBetweenElevations(
    			ST_GeomFromEWKT('LINESTRING(1 2 3, 4 5 6)'), 2, 4)) As ewelev;
    								   ewelev
    ----------------------------------------------------------------
    	MULTILINESTRING((1 2 3,2 3 4))

    SELECT ST_AsEWKT(ST_LocateBetweenElevations('LINESTRING(1 2 6, 4 5 -1, 7 8 9)', 6, 9)) As ewelev;

    				ewelev
    ----------------------------------------------------------------
    GEOMETRYCOLLECTION(POINT(1 2 6),LINESTRING(6.1 7.1 6,7 8 9))

    -- Geometry collections are difficult animals so dump them
    -- to make them more digestable
    SELECT ST_AsEWKT((ST_Dump(the_geom)).geom)
    	FROM
    	(SELECT ST_LocateBetweenElevations('LINESTRING(1 2 6, 4 5 -1, 7 8 9)', 6, 9) as the_geom) As foo;

    		   st_asewkt
    --------------------------------
    POINT(1 2 6)
    LINESTRING(6.1 7.1 6,7 8 9)

### See Also

ST_Dump, ST_LocateBetween

ST_InterpolatePoint

Return the value of the measure dimension of a geometry at the point closed to the provided point.

    				float8 ST_InterpolatePoint
    				geometry  line
    				geometry  point

### Description

Return the value of the measure dimension of a geometry at the point closed to the provided point.

Availability: 2.0.0

&Z_support;

### Examples

    SELECT ST_InterpolatePoint('LINESTRING M (0 0 0, 10 0 20)', 'POINT(5 5)');
     st_interpolatepoint
     ---------------------
    			            10

### See Also

ST_AddMeasure, ST_LocateAlong, ST_LocateBetween

ST_AddMeasure

Return a derived geometry with measure elements linearly interpolated between the start and end points.

    			geometry ST_AddMeasure
    			geometry  geom_mline
    			float8  measure_start
    			float8  measure_end

### Description

Return a derived geometry with measure elements linearly interpolated between the start and end points. If the geometry has no measure dimension, one is added. If the geometry has a measure dimension, it is over-written with new values. Only LINESTRINGS and MULTILINESTRINGS are supported.

Availability: 1.5.0

&Z_support;

### Examples

    SELECT ST_AsText(ST_AddMeasure(
    ST_GeomFromEWKT('LINESTRING(1 0, 2 0, 4 0)'),1,4)) As ewelev;
               ewelev
    --------------------------------
     LINESTRINGM(1 0 1,2 0 2,4 0 4)

    SELECT ST_AsText(ST_AddMeasure(
    ST_GeomFromEWKT('LINESTRING(1 0 4, 2 0 4, 4 0 4)'),10,40)) As ewelev;
                     ewelev
    ----------------------------------------
     LINESTRING(1 0 4 10,2 0 4 20,4 0 4 40)

    SELECT ST_AsText(ST_AddMeasure(
    ST_GeomFromEWKT('LINESTRINGM(1 0 4, 2 0 4, 4 0 4)'),10,40)) As ewelev;
                     ewelev
    ----------------------------------------
     LINESTRINGM(1 0 10,2 0 20,4 0 40)

    SELECT ST_AsText(ST_AddMeasure(
    ST_GeomFromEWKT('MULTILINESTRINGM((1 0 4, 2 0 4, 4 0 4),(1 0 4, 2 0 4, 4 0 4))'),10,70)) As ewelev;
                                 ewelev
    -----------------------------------------------------------------
     MULTILINESTRINGM((1 0 10,2 0 20,4 0 40),(1 0 40,2 0 50,4 0 70))