金仓数据库 KingbaseGIS 使用手册（6.13. Overlay函数）

6.13. Overlay函数

6.13.1. ST_ClipByBox2D

ST_ClipByBox2D — 用一种快速、 有容差， 但可能无效的方式用一个 2D 盒形框裁剪一个几何对象。

用法

geometry ST_ClipByBox2D(geometry geom, box2d box);

描述

用一种快速、有容差，但可能无效的方式用一个 2D 盒形框裁剪一个几何对象。 一个拓扑上不合法的输入几何对象不一定会引发该函数抛出异常。输出几何对象也不保证是合法的。 （具体点说，有可能返回一个自相交的多边形）。

样例

第二个参数依赖从 geometry 类型到 box2d 类型的隐式转换：

SELECT ST_ClipByBox2D(the_geom, ST_MakeEnvelope(0,0,10,10)) FROM mytab;

参考

ST_Intersection, ST_MakeBox2D, ST_MakeEnvelope

6.13.2. ST_Difference

ST_Difference — 根据输入的几何对象A和B，返回一个几何对象A的除了和几何对象B相交的剩余部分

用法

geometry ST_Intersection( geometry geomA , geometry geomB, float8 gridSize = -1 );
geography ST_Intersection( geography geogA , geography geogB );

描述

返回两个几何对象相交的点集对应的 geometry 对象。 换句话说，返回的几何对象是输入的两个几何对象的公共部分。 如果输入的几何对象没有任何公共的部分或者不相交（ disjoint） ， 那么该函数将返回一个空的 GeometryCollection 对象在设定边界框、缓冲区分析和区域查询等只需要裁剪并返回几何对象位于用户感兴趣的国家或区域内的部分时， 联合使用 ST_Intersection 函数和 ST_Intersect 函数通常会非常方便。

如果提供的可选的 gridSize 参数， 输入几何对象将被贴靠到指定大小的网格上，其所有顶点也会被推挤到网格上。

注意

对于 geography 类型对象： 由于 geography 类型只是对 geometry 实现的简单包装。 该函数会首先判断最适合这两个 geography 对象边界框的 SRID（如果 geography 对象有一半落在通用墨卡托投影（UTM） 区域内， 但又不在同一个投影区域时，会选择其中一个）（该函数倾向于在南/北极地区采用兰伯特等角投影 LAES， 在其他区域选择通用墨卡托投影，并在最坏情况下退化为一般的墨卡托投影）， 在平面空间坐标系中计算出的交集图形，再转换回 WGS84 参考系，变成 geography 类型对象。

注意

该函数会丢弃 M 坐标。 在处理 3D 几何对象时，你也许更愿意使用基于 SFCGAL 的 ST_3DIntersection 函数， 因为它能正确处理 3D 几何对象的 3D 交集。 尽管本函数也能处理 z 轴坐标，但它仅仅是对 z 轴坐标取平均值。

该函数由GEOS模块支持

注意

该函数不支持GeometryCollection参数

• 该函数方法实现了规范 OpenGIS Simple Features Implementation Specification for SQL 1.1. s2.1.1.3

• 该函数方法实现了规范 SQL/MM specification. SQL-MM 3: 5.1.20

• 这个函数支持3D对象，并且不会删除z坐标。然而似乎该函数处理时候只考虑x，y坐标，但返回时候会将原有的Z坐标加上

样例

对二维的情况而言是安全的。这个几何对象与 st_symdifference 样例中的几何对象相同：

SELECT ST_AsText(
ST_Difference(
ST_GeomFromText('LINESTRING(50 100, 50 200)'),
ST_GeomFromText('LINESTRING(50 50, 50 150)')
)
);

st_astext
---------
LINESTRING(50 150,50 200)

在三维的情况下，结果就不太正确：

SELECT ST_AsEWKT(ST_Difference(ST_GeomFromEWKT('MULTIPOINT(-118.58 38.38 5,-118.60 38.329
6,-118.614 38.281 7)'), ST_GeomFromEWKT('POINT(-118.614 38.281 5)')));

st_asewkt
---------
MULTIPOINT(-118.6 38.329 6,-118.58 38.38 5)

参考

ST_SymDifference

6.13.3. ST_Intersection

ST_Intersection — 返回几何对象相交的点集对应的geometry对象。对于geography类型对象，该函数会先将其转化成geometry类型对象，然后再转换成WGS84下的坐标

用法

geometry ST_Intersection( geometry geomA , geometry geomB, float8 gridSize = -1 );
geography ST_Intersection( geography geogA , geography geogB );

描述

返回两个几何对象相交的点集对应的 geometry 对象。 换句话说，返回的几何对象是输入的两个几何对象的公共部分。

如果输入的几何对象没有任何公共的部分或者不相交（ disjoint） ，那么该函数将返回一个空的 Geometry Collection 对象在设定边界框、缓冲区分析和区域查询等只需要裁剪并返回几何对象位于用户感兴趣的国家或区域内的部分时， 联合使用 ST_Intersection 函数和 ST_Intersect 函数通常会非常方便。

如果提供的可选的 gridSize 参数， 输入几何对象将被贴靠到指定大小的网格上，其所有顶点也会被推挤到网格上。

注意

对于 geography 类型对象： 由于 geography 类型只是对 geometry 实现的简单包装。该函数会首先判断最 适合这两个 geography 对象边界框的 SRID（如果 geography 对象有一半落在通用墨卡托投影（UTM） 区 域内，但又不在同一个投影区域时，会选择其中一个）（该函数倾向于在南/北极地区采用兰伯特等角投 影 LAES， 在其他区域选择通用墨卡托投影，并在最坏情况下退化为一般的墨卡托投影）， 在平面空间 坐标系中计算出的交集图形，再转换回 WGS84 参考系，变成 geography 类型对象。

注意

该函数会丢弃 M 坐标。

注意

在处理 3D 几何对象时，你也许更愿意使用基于 SFCGAL 的 ST_3DIntersection 函数， 因为它能正确处理 3D 几何对象的 3D 交集。 尽管本函数也能处理 z 轴坐标，但它仅仅是对 z 轴坐标取平均值。

• 该函数方法实现了规范 OpenGIS Simple Features Implementation Specification for SQL 1.1. s2.1.1.3

• 该函数方法实现了规范 SQL/MM specification. SQL-MM 3: 5.1.18

样例

SELECT ST_AsText(ST_Intersection('POINT(0 0)'::geometry, 'LINESTRING ( 2 0, 0 2 )':: geometry));

st_astext
---------------
GEOMETRYCOLLECTION EMPTY
(1 row)

SELECT ST_AsText(ST_Intersection('POINT(0 0)'::geometry, 'LINESTRING ( 0 0, 0 2 )'::
geometry));

st_astext
---------------
POINT(0 0)
(1 row)

用国家来裁剪所有的线（在这里，我们假设国家的几何图形是一个多边形或多边形集合）。 注意：我们只以线串或多线串的形式保留交集，因为我们不关心那些孤立的点。我们会将一个几何对象集合转变成一个多部分的几何对象。 下边这个例子相当常见，只需对 where 子句稍作修改，即对多边形等其他情况有效。

SELECT clipped.gid, clipped.f_name, clipped_geom
FROM (SELECT trails.gid, trails.f_name, (
   ST_Dump(ST_Intersection(country.the_geom, trails.the_geom))
   ).geom As clipped_geom
FROM country
INNER JOIN trails
ON ST_Intersects(country.the_geom, trails.the_geom))
WHERE ST_Dimension(clipped.clipped_geom) = 1 ;

对于多边形裁剪多边形的例子，我们有时也可以用一个更快速地窍门：为所有几何对象创建一个距离为 0.0 的缓冲区（除非结果是一个空的几何对象集合）。

SELECT poly.gid, ST_Multi(ST_Buffer(
ST_Intersection(country.the_geom, poly.the_geom),
0.0)
) As clipped_geom
FROM country
INNER JOIN poly
ON ST_Intersects(country.the_geom, poly.the_geom)
WHERE Not ST_IsEmpty(ST_Buffer(ST_Intersection(country.the_geom, poly.the_geom),0.0));

参考

ST_Difference, ST_Dimension, ST_Dump, ST_SymDifference, ST_Intersects, ST_Multi

6.13.4. ST_MemUnion

ST_MemUnion — 与函数ST_Union功能一样，但是会使用更少的内存以及更多的处理时间

用法

geometry ST_MemUnion(geometry set geomfield);

描述

注意

与函数ST_Union功能一样，但是会使用更少的内存以及更多的处理时间。这是一个把所有几何对象一次性union起来的聚合函数。与之前的ST_Union聚合结果相比，后者会先创建一个几何对象数组，然后再union他们

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

样例

参考 ST_Union

参考

ST_Union

6.13.5. ST_Node

ST_Node — 对LINESTRING对象添加节点进行分隔

用法

geometry ST_Node(geometry geom);

描述

在保持原有输入的几何对象的所有点情况下，添加最少的可能的节点到LINESTRING上

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

样例

SELECT ST_AsEWKT(
ST_Node('LINESTRINGZ(0 0 0, 10 10 10, 0 10 5, 10 0 3)'::geometry)
) As output;

output
-----------
MULTILINESTRING((0 0 0,5 5 4.5),(5 5 4.5,10 10 10,0 10 5,5 5 4.5),(5 5 4.5,10 0 3))

参考

ST_UnaryUnion

6.13.6. ST_Split

ST_Split — 通过切割一个几何对象，返回一个collection 几何对象。

用法

geometry ST_Split(geometry input, geometry blade);

描述

该函数会切割一个几何对象，用点切割线，用线切割线，用线切割多边形。返回一个collection类型对象。可以把该函数当做函数ST_Union的相反函数。理论上用ST_Union函数到函数ST_Split 返回的collection上面始终能够得到原始的几何对象

注意

为了提高函数ST_Split的鲁棒性，可以使用以一个非常低的误差用blade参数代表的几何对象来切割第一个参数代表的几何对象。

否则该函数使用内部网格时候可能会引起一些误差问题，即切割几何对象的坐标和被切割的机会对象坐标不能落在一起，导致输入对象不能被正确地切割。

样例 线切割多边形

这个例子将创建一个几何对象集合，包含两半多边形。 这与我们在 ST_BuildArea 中所举的例子相似。

SELECT ST_Split(circle, line)
FROM (SELECT
ST_MakeLine(ST_MakePoint(10, 10),ST_MakePoint(190, 190)) As line,
ST_Buffer(ST_GeomFromText('POINT(100 90)'), 50) As circle) As foo;

-- result --
GEOMETRYCOLLECTION(POLYGON((150 90,149.039264020162 80.2454838991936,146.193976625564 70.8658283817455,..), POLYGON(..)))

-- To convert to individual polygons, you can use ST_Dump or ST_GeometryN
SELECT ST_AsText((ST_Dump(ST_Split(circle, line))).geom) As wkt
FROM (SELECT
ST_MakeLine(ST_MakePoint(10, 10),ST_MakePoint(190, 190)) As line,
ST_Buffer(ST_GeomFromText('POINT(100 90)'), 50) As circle) As foo;
-- result --

wkt
---------------
POLYGON((150 90,149.039264020162 80.2454838991936,..))
POLYGON((60.1371179574584 60.1371179574584,58.4265193848728
62.2214883490198,53.8060233744357 ..))

Multilinestring Cut by point

SELECT ST_AsText(ST_Split(mline, pt)) As wktcut FROM (SELECT
ST_GeomFromText('MULTILINESTRING((10 10, 190 190), (15 15, 30 30, 100
90))') As mline,
ST_Point(30,30) As pt) As foo;

wktcut
------
GEOMETRYCOLLECTION(
LINESTRING(10 10,30 30), LINESTRING(30 30,190 190),LINESTRING(15 15,30
30), LINESTRING(30 30,100 90)
)

参考

ST_AsText, ST_BuildArea, ST_Dump, ST_GeometryN, ST_Union

6.13.7. ST_Subdivide

ST_Subdivide — 用平行于 x 或 y 轴的线段切分几何对象，直到每个部分的顶点数小于给定的最大顶点数。

用法

setof geometry ST_Subdivide(geometry geom, integer max_vertices=256, float8 gridSize = -1);

描述

用平行于 x 或 y 轴的线段切分几何对象，直到每个部分的顶点数小于给定的最大顶点数。 “判定点在多边形中” 和其他空间操作通常在已经被分割和索引过的数据集上更为快速： 不符合条件的部分可以被快速检测出来， 因为每个切片覆盖的范围通常小于原几何对象的边界框； 符合条件的部分也能够更快速地进行判定，因为其顶点数更少。 给定的最大顶点数必须大于等于 5， 因为至少要 5 个点才能围成一个封闭的盒形区域。 如果提供了可选的 gridSize 参数，输入几何对象将被贴靠到指定大小的网格上，其所有顶点也会被推挤到网格上。

样例

-- Subdivide complex geometries in table, in place
with complex_areas_to_subdivide as (
   delete from polygons_table
   where ST_NPoints(geom) > 255
   returning id, column1, column2, column3, geom
)
insert into polygons_table (fid, column1, column2, column3, geom)
   select
      fid, column1, column2, column3,
      ST_Subdivide(geom, 255) as geom
   from complex_areas_to_subdivide;

-- Create a new subdivided table suitable for joining to the original
CREATE TABLE subdivided_geoms AS
SELECT pkey, ST_Subdivide(geom) AS geom
FROM original_geoms;

按最大顶点数10进行切分

SELECT row_number() OVER() As rn, ST_AsText(geom) As wkt
FROM ( SELECT ST_SubDivide('POLYGON((132 10,119 23,85 35,68 29,66 28,49 42,32 56,22 64,32 110,40 119,36 150,
57 158,75 171,92 182,114 184,132 186,146 178,176 184,179 162,184 141,190 122,
190 100,185 79,186 56,186 52,178 34,168 18,147 13,132 10))'::geometry,10))  As f(geom);

rn │                                                      wkt
───┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 1 │ POLYGON((119 23,85 35,68 29,66 28,32 56,22 64,29.8260869565217 100,119 100,119 23))
 2 │ POLYGON((132 10,119 23,119 56,186 56,186 52,178 34,168 18,147 13,132 10))
 3 │ POLYGON((119 56,119 100,190 100,185 79,186 56,119 56))
 4 │ POLYGON((29.8260869565217 100,32 110,40 119,36 150,57 158,75 171,92 182,114 184,114 100,29.8260869565217 100))
 5 │ POLYGON((114 184,132 186,146 178,176 184,179 162,184 141,190 122,190 100,114 100,114 184))

与 ST_Segmentize(geography)联合使用，可以创建更多的顶点以便进行切分

SELECT ST_AsText(ST_Subdivide(ST_Segmentize('LINESTRING(0 0, 85 85)'::geography,1200000)::geometry,8));

LINESTRING(0 0,0.487578359029357 5.57659056746196,0.984542144675897 11.1527721155093,1.50101059639722 16.7281035483571,1.94532113630331 21.25)
LINESTRING(1.94532113630331 21.25,2.04869538062779 22.3020741387339,2.64204641967673 27.8740533545155,3.29994062412787 33.443216802941,4.04836719489742 39.0084282520239,4.59890468420694 42.5)
LINESTRING(4.59890468420694 42.5,4.92498503922732 44.5680389206321,5.98737409390639 50.1195229244701,7.3290919767674 55.6587646879025,8.79638749938413 60.1969505994924)
LINESTRING(8.79638749938413 60.1969505994924,9.11375579533779 61.1785363177625,11.6558166691368 66.6648504160202,15.642041247655 72.0867690601745,22.8716627200212 77.3609628116894,24.6991785131552 77.8939011989848)
LINESTRING(24.6991785131552 77.8939011989848,39.4046096622744 82.1822848017636,44.7994523421035 82.5156766227011)
LINESTRING(44.7994523421035 82.5156766227011,85 85)

参考

ST_AsText, ST_ClipByBox2D, ST_Segmentize, ST_Split, ST_NPoints

6.13.8. ST_SymDifference

ST_SymDifference —返回输入对象A和B union后再去除A和B相交的部分。该函数是一个对称性函数，因为下面等式成立 ST_SymDifference(A,B) = ST_SymDifference(B,A).

用法

geometry ST_SymDifference(geometry geomA, geometry geomB, float8 gridSize = -1);

描述

返回输入对象A和B union后再去除A和B相交的部分。

该函数是一个对称性函数，因为下面等式成立ST_SymDifference(A,B) = ST_SymDifference(B,A)。 可以认为该函数的返回值等于 ST_Union(geomA,geomB) - ST_Intersection(A,B).

如果提供了可选的 gridSize 参数， 输入几何对象将会贴靠到指定大小的网格上，其所有顶点也会被推挤到网格上。

该函数由GEOS模块支持

注意

该函数不支持GeometryCollection参数

• 该函数方法实现了规范 OpenGIS Simple Features Implementation Specification for SQL 1.1. s2.1.1.3

• 该函数方法实现了规范 SQL/MM specification. SQL-MM 3: 5.1.21

• 这个函数支持3D对象，并且不会删除z坐标。然而该函数在处理时候只考虑x,y坐标，并返回Z坐标

样例

--Safe for 2d - symmetric difference of 2 linestrings
SELECT ST_AsText(
ST_SymDifference(
ST_GeomFromText('LINESTRING(50 100, 50 200)'),
ST_GeomFromText('LINESTRING(50 50, 50 150)')
) );

st_astext
---------
MULTILINESTRING((50 150,50 200),(50 50,50 100))

--When used in 3d doesn't quite do the right thing
SELECT ST_AsEWKT(ST_SymDifference(ST_GeomFromEWKT('LINESTRING(1 2 1, 1 4
2)'), ST_GeomFromEWKT('LINESTRING(1 1 3, 1 3 4)')))

st_astext
------------
MULTILINESTRING((1 3 2.75,1 4 2),(1 1 3,1 2 2.25))

参考

ST_Difference, ST_Intersection, ST_Union

6.13.9. ST_Union

ST_Union — 返回一个代表一些几何对象的并集的几何对象

用法

geometry ST_Union(geometry set g1field);
geometry ST_Union(geometry set g1field, float8 gridSize);
geometry ST_Union(geometry g1, geometry g2);
geometry ST_Union(geometry g1, geometry g2, float8 gridSize);
geometry ST_Union(geometry[] g1_array);

描述

合并输入的多个几何对象，生成一个没有重叠的几何对象，其输出对象可以是 MULTI*、 单体几何对象或Geometry Collection 几何对象集合。 它有多种变体：

• 接收两个输入几何对象的变体： 返回两个输入几何对象的并集对应的几何对象。 如果两个几何对象中的任意一个为 NULL， 则结果也为 NULL。

• 数组参数变体：返回数组中所有对象取并集的结果。

• 聚合函数变体： 它根据一个几何对象记录集求并集。按照 KES 的术语， ST_Union 函数是一个聚合函数。这意味着它会操作多行数据，就像 SUM() 和 AVG() 等大多数聚合函数那样， 并且会忽略 NULL 几何对象。

与之类似的 ST_UnaryUnion 函数是一个单输入、非聚合的版本。

ST_Union 的数组变体和聚合函数变体采用 Fast Cascaded Union 算法。 该算法介绍如下 http://blog.cleverelephant.ca/2009/01/must-faster-unions-in-KingbaseES GIS-14.html 有个可选参数 gridSize 可用于指定一个固定精度的工作空间。输入几何对象会粘附到指定尺寸的网格，其所有顶点也都会被“ 推挤” 到网格上。

注意

函数 ST_Collect 和函数 ST_Union 经常可以互换使用。 如果并不要求结果不存在重叠， 函数 ST_Collect 一般来说要比函数 ST_Union 快，因为 ST_Collect 函数无需对输入几何对象本身进行操作。

该函数由GEOS模块支持.

处理线型对象时， ST_Union 会创建 MultiLineString 而不会将多个 LineString 拼接成一个 LineString 对象。如果需要拼合，应该使用 ST_LineMerge 函数。

注意

注意:该函数原先叫做 GeomUnion()， 而函数 GeomUnion()原先的名字是“UNION”，由于 UNION 是 SQL 的保留字，所以需要改名。

可用版本: ST_Union性能有所提升。引入了ST_Union(geomarray) 支持，在KingbaseES中运行得也更快。如果使用GEOS 3.1.0+版本，函数 ST_Union 会使用更快的Cascaded Union 算法。

• 该函数方法实现了规范 OpenGIS Simple Features Implementation Specification for SQL 1.1. s2.1.1.3

注意

聚合版本没有在OGC SPEC做明确的定义

• 该函数方法实现了规范 SQL/MM specification. SQL-MM 3: 5.1.19 the z-index (elevation) when polygons are involved.

样例 Aggregate example

SELECT stusps,
ST_Multi(ST_Union(f.the_geom)) as singlegeom
FROM sometable As f
GROUP BY stusps
Non-Aggregate example
SELECT ST_AsText(ST_Union(ST_GeomFromText('POINT(1 2)'),
ST_GeomFromText('POINT(-2 3)') ) )

st_astext
---------
MULTIPOINT(-2 3,1 2)

SELECT ST_AsText(ST_Union(ST_GeomFromText('POINT(1 2)'),
ST_GeomFromText('POINT(1 2)') ) );

st_astext
----------
POINT(1 2)

--3d example - sort of supports 3d (and with mixed dimensions!)
SELECT ST_AsEWKT(st_union(the_geom))
FROM
(SELECT ST_GeomFromEWKT('POLYGON((-7 4.2,-7.1 4.2,-7.1 4.3,
-7 4.2))') as the_geom
UNION ALL
SELECT ST_GeomFromEWKT('POINT(5 5 5)') as the_geom
UNION ALL
SELECT ST_GeomFromEWKT('POINT(-2 3 1)') as the_geom
UNION ALL
SELECT ST_GeomFromEWKT('LINESTRING(5 5 5, 10 10 10)') as the_geom ) as foo;

st_asewkt
---------
GEOMETRYCOLLECTION(POINT(-2 3 1),LINESTRING(5 5 5,10 10 10),POLYGON((-7 4.2 5,-7.1 4.2
5,-7.1 4.3 5,-7 4.2 5)));

--3d example not mixing dimensions
SELECT ST_AsEWKT(st_union(the_geom))
FROM
(SELECT ST_GeomFromEWKT('POLYGON((-7 4.2 2,-7.1 4.2 3,-7.1 4.3 2,
-7 4.2 2))') as the_geom
UNION ALL
SELECT ST_GeomFromEWKT('POINT(5 5 5)') as the_geom
UNION ALL
SELECT ST_GeomFromEWKT('POINT(-2 3 1)') as the_geom
UNION ALL
SELECT ST_GeomFromEWKT('LINESTRING(5 5 5, 10 10 10)') as the_geom ) as foo;

st_asewkt
---------
GEOMETRYCOLLECTION(POINT(-2 3 1),LINESTRING(5 5 5,10 10 10),POLYGON((-7
4.2 2,-7.1 4.2 3,-7.1 4.3 2,-7 4.2 2)))

样例 using new Array construct

SELECT ST_Union(ARRAY(SELECT the_geom FROM sometable));

SELECT ST_AsText(ST_Union(ARRAY[ST_GeomFromText('LINESTRING(1 2, 3 4)'),
ST_GeomFromText('LINESTRING(3 4, 4 5)')])) As wktunion;

--wktunion---
MULTILINESTRING((3 4,4 5),(1 2,3 4))

参考

ST_Collect ST_UnaryUnion

6.13.10. ST_UnaryUnion

ST_UnaryUnion — 与函数ST_Union类似，但处理geometry类型的对象

用法

geometry ST_UnaryUnion(geometry geom, float8 gridSize = -1);

描述

ST_Union 函数的单输入变体。 输入可以是一个单体、 Multi 几何对象或者 Geometry Collection。合并操作会作用在每个独立的输入组分上，这使得该函数可用于修复因为存在组分重叠而不合法的 Multi 几何对象。 （但有一个前提是：每个输入几何对象组分本身必须是合法的。如果存在非法组分，例如一个蝴蝶结形的多边形，将会导致错误）

该函数的另一个用途是将一个 LineString 集合节点化并分解（也可以用 ST_Node 函数实现）。 可以混合使用 ST_UnaryUnion 和 ST_Collect 函数来微调每次合并多少几何对象。这样可以获得内存占用量与计算时间之间的平衡， 尤其是使用 ST_Union 与使用 ST_MemUnion 之间的平衡。

如果提供了可选的参数 gridSize， 输入几何对象将被贴靠到制定大小的网格上，其所有顶点也会被推挤到网格上。

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

可用版本:需要GEOS版本>= 3.3.0.

参考

ST_Union , ST_MemUnion , ST_Collect