金仓数据库 KingbaseGIS 使用手册（6.18. 线性参考函数）

6.18. 线性参考函数

6.18.1. ST_LineInterpolatePoint

ST_LineInterpolatePoint — 返回在一个 LINESTRING 对象上面在指定位置上插入（获取）的一个点的几何对象。第二个参数范围是 0 到 1 内的 float8 类型，表示被插入的点在整个 LINESTRING 的位置。

用法

geometry ST_LineInterpolatePoint(geometry a_linestring, float a_fraction);

描述

返回在一个 LINESTRING 对象上面在指定位置上插入（获取）的一个点的几何对象。第二个参数范围是 0 到 1 内的 float8 类型，表示被插入的点在整个 LINESTRING 的位置。参考 ST_LineLocatePoint 计算离 LINESTRING 最近的 Point 对象。

注意

该函数也可以处理带 M 和 Z 值的坐标，而之前的版本只把这两个坐标值都设置为 0.0。

• 这个函数支持 3D 对象，并且不会删除 z 坐标。

样例

--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)

参考

ST_AsText, ST_AsEWKT, ST_Length, ST_LineLocatePoint

6.18.2. ST_3DLineInterpolatePoint

ST_3DLineInterpolatePoint — 返回线上指定比例处的一个点的坐标。

用法

geometry ST_3DLineInterpolatePoint(geometry a_linestring, float8 a_fraction);

描述

返回线上指定比例处的一个点的坐标。 第一个参数必须是一个 LineString。 第二个参数必须是一个 float8 型的数字，取值在 0 到 1 之间，代表所需的点在线上所处位置的比例。

注意

ST_LineInterpolatePoint 在 2D 空间中计算结果，并对 Z 和 M 坐标取中值，而 ST_3DLineInterpolatePoint 直接计算 3D 坐标，仅对 M 坐标取中值。

样例

获取线上 20% 位置处点的坐标

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)

相关参考

ST_AsText, ST_AsEWKT, ST_Length, ST_LineInterpolatePoint , ST_LineInterpolatePoints , ST_LineLocatePoint

6.18.3. ST_LineInterpolatePoints

ST_LineInterpolatePoints — 返回线上指定比例处的一个点的坐标。

用法

geometry ST_LineInterpolatePoints(geometry a_linestring, float8 a_fraction, boolean repeat);

描述

返回线对象上的一个或多个点。 第一个参数必须为 LineString， 第二个参数是 0 到 1 之间的 float8 浮点数，代表点与点之间的间距在线对象总长度上的占比。

如果第三个参数为 false， 则最多找出一个点。如果结果为 0 个点或 1 个点，将返回 Point 类型的对象。如果返回 2 个甚至更多的点，则返回 MultiPoint 对象。

• 该函数支持 3D 对象，并且不会丢弃 Z 坐标。

• 该函数支持 M 坐标

样例

在 linestring 对象上每隔 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)

参考

ST_LineInterpolatePoint ST_LineLocatePoint

6.18.4. ST_LineLocatePoint

ST_LineLocatePoint — 根据输入的点和 LINESTRING，返回这个点在 LINESTRING 上的位置（如果点不在这个 LINESTRING 上， 就返回最近的）

用法

float ST_LineLocatePoint(geometry a_linestring, geometry a_point);

描述

根据输入的点和 LINESTRING，返回这个点在 LINESTRING 上的位置（如果点不在这个 LINESTRING 上，就返回最近的）

可以用得到的位置，反过来用函数 (ST_LineInterpolatePoint) 来获得插值点，或者函数 (ST_LineSubstring) 来截取一部分 LINESTRING.

样例

--Rough approximation of finding the street number of a point along the street
--注意 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 end street_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)

相关参考

ST_DWithin, ST_Length2D, ST_LineInterpolatePoint, ST_LineSubstring

6.18.5. ST_LineSubstring

ST_LineSubstring — 从一个 LINESTRING 钟返回一个从输入的 LINESTRING 提取指定起点和终点的片段，第二个和第三个参数都是 float8 类型，值范围在 0 到 1。

用法

geometry ST_LineSubstring(geometry a_linestring, float startfraction, float endfraction);

描述

从一个 LINESTRING 钟返回一个从输入的 LINESTRING 提取指定起点和终点的片段，第二个和第三个参数都是 float8 类型，值范围在 0 到 1。该函数只适用于 LINESTRING 类型对象，如果想对连续的 MULTILINESTRING 类型对象使用，需要与函数 ST_LineMerge 一起使用。如果参数的起始点和终点一样，那么返回值和 ST_LineInterpolatePoint 返回值一样。

参考 ST_LineLocatePoint 返回距离一个点最近的位置

• 这个函数支持 3D 对象，并且不会删除 z 坐标。

样例

--Return the approximate 1/3 mid-range part of a linestring
SELECT ST_AsText(ST_LineSubString(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 KingbaseES 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;

参考

ST_Length, ST_LineInterpolatePoint, ST_LineMerge

6.18.6. ST_LocateAlong

ST_LocateAlong — 返回几何对象的 M 值与给定的 M 值一样的几何对象，目前不支持多边形类的几何对象

用法

geometry ST_LocateAlong(geometry ageom_with_measure, float a_measure, float offset);

描述

返回几何对象的 M 值与给定的 M 值一样的几何对象，目前不支持多边形类的几何对象

如果已经提供了偏移单位，根据提供的偏移单位，在输入的 LINESTRING 上向左或向右偏移。偏移值为正，则向左偏移，偏移值为负，则向右偏移。

语法定义规范如下: ISO/IEC CD 13249-3:200x (E) - Text for Continuation CD Editing Meeting

注意

该函数只适用于带 M 坐标的几何对象

• 该函数支持 M 坐标.

样例

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)

参考

ST_Dump, ST_LocateBetween

6.18.7. ST_LocateBetween

ST_LocateBetween — 根据指定的测量值范围，返回一个在输入几何对象的 M 坐标能匹配的的 geometry collection 对象，不支持 Polygon 对象

用法

geometry ST_LocateBetween(geometry geomA, float measure_start, float measure_end, float offset);

描述

根据指定的测量值范围，返回一个在输入几何对象的 M 坐标能匹配的的 geometry collection 对象，不支持 Polygon 对象

语义定义如下: ISO/IEC CD 13249-3:200x (E) - Text for Continuation CD Editing Meeting

在之前的版本，该函数被称作 ST_Locate_Between_Measures，旧的函数名不推荐使用，将来也会移除，但当前为了保持后向兼容，依然可用该函数支持 M 坐标.

样例

SELECT ST_AsText(the_geom)
FROM
(SELECT ST_LocateBetween(
ST_GeomFromText('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(
ST_GeomFromText('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)

参考

ST_Dump, ST_LocateAlong

6.18.8. ST_LocateBetweenElevations

ST_LocateBetweenElevations — 返回高度值在指定范围内的几何对象（collection）。目前只支持 3D, 4D LINESTRINGS 和 MULTILINESTRINGS

用法

geometry ST_LocateBetweenElevations(geometry geom_mline, float elevation_start, float elevation_end);

描述

返回高度值在指定范围内的几何对象（collection）。目前只支持 3D, 4D LINESTRINGS 和 MULTILINESTRINGS

• 这个函数支持 3D 对象，并且不会删除 z 坐标。

样例

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(
ST_GeomFromEWKT('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(
ST_GeomFromEWKT('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)

相关参考

ST_Dump

6.18.9. ST_InterpolatePoint

ST_InterpolatePoint — 根据提供的点，返回输入几何对象离提供的点最近的点的 M 值

用法

float ST_InterpolatePoint(geometry line, geometry point);

描述

根据提供的点，返回输入几何对象离提供的点最近的点的 M 值

• 这个函数支持 3D 对象，并且不会删除 z 坐标。

样例

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

st_interpolatepoint
---------------------
10

相关参考

ST_AddMeasure, ST_LocateAlong, ST_LocateBetween

6.18.10. ST_AddMeasure

ST_AddMeasure — 在输入几何对象的起点和终点之间进行线性插值，返回一个新的带有 M 值的几何对象，如果输入的几何对象没有测量维度的 M 值，那么就自动驾驶。如果输入的几何对象有 M 值，那么会覆盖掉。目前该函数只支持 LINESTRINGS 和 MULTILINESTRINGS

用法

geometry ST_AddMeasure(geometry geom_mline, float measure_start, float measure_end);

描述

ST_AddMeasure — 在输入几何对象的起点和终点之间进行线性插值，返回一个新的带有 M 值的几何对象，如果输入的几何对象没有测量维度的 M 值，那么就自动驾驶。如果输入的几何对象有 M 值，那么会覆盖掉。

目前该函数只支持 LINESTRINGS 和 MULTILINESTRINGS

• 这个函数支持 3D 对象，并且不会删除 z 坐标。

样例

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))