GEOS APILink to this heading#

什么是 GEOS?Link to this heading#

GEOS 代表 Geometry Engine - Open Source，是一个 C++ 库，从 Java Topology Suite 移植而来。GEOS 实现了 OpenGIS Simple Features for SQL 空间谓词函数和空间操作符。GEOS，现在是一个 OSGeo 项目，最初由加拿大维多利亚的 Refractions Research 开发和维护。

特性Link to this heading#

GeoDjango 实现了一个高级的 Python 封装，用于 GEOS 库，其特点包括：

• 一个使用 ctypes 纯粹在 Python 中实现的，对 GEOS 几何例程提供的 BSD 许可接口。

• 与 GeoDjango 松散耦合。例如，可以在 Django 项目/应用程序之外使用 GEOSGeometry 对象。换句话说，无需设置 DJANGO_SETTINGS_MODULE 或使用数据库等。

• 可变性：GEOSGeometry 对象可以被修改。

• 跨平台测试。

创建几何对象Link to this heading#

GEOSGeometry 对象可以以几种方式创建。首先，可以简单地在某些空间输入上实例化对象，以下是从 WKT、HEX、WKB 和 GeoJSON 创建相同几何的示例：

>>> from django.contrib.gis.geos import GEOSGeometry
>>> pnt = GEOSGeometry("POINT(5 23)")  # WKT
>>> pnt = GEOSGeometry("010100000000000000000014400000000000003740")  # HEX
>>> pnt = GEOSGeometry(
...     memoryview(
...         b"\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x14@\x00\x00\x00\x00\x00\x007@"
...     )
... )  # WKB
>>> pnt = GEOSGeometry(
...     '{ "type": "Point", "coordinates": [ 5.000000, 23.000000 ] }'
... )  # GeoJSON

另一个选项是使用特定几何类型的构造函数来创建您希望创建的几何对象。例如，可以通过将 X 和 Y 坐标传递到其构造函数中来创建一个 Point 对象：

>>> from django.contrib.gis.geos import Point
>>> pnt = Point(5, 23)

所有这些构造函数都接受关键字参数 srid。例如：

>>> from django.contrib.gis.geos import GEOSGeometry, LineString, Point
>>> print(GEOSGeometry("POINT (0 0)", srid=4326))
SRID=4326;POINT (0 0)
>>> print(LineString((0, 0), (1, 1), srid=4326))
SRID=4326;LINESTRING (0 0, 1 1)
>>> print(Point(0, 0, srid=32140))
SRID=32140;POINT (0 0)

最后，还有一个 fromfile() 工厂方法，它可以从文件返回一个 GEOSGeometry 对象：

>>> from django.contrib.gis.geos import fromfile
>>> pnt = fromfile("/path/to/pnt.wkt")
>>> pnt = fromfile(open("/path/to/pnt.wkt"))

几何对象是符合 Python 风格的Link to this heading#

GEOSGeometry 对象是 'Pythonic' 的，换句话说，可以使用标准的 Python 惯例访问、修改和迭代其组件。例如，你可以迭代 Point 中的坐标：

>>> pnt = Point(5, 23)
>>> [coord for coord in pnt]
[5.0, 23.0]

对于任何几何对象，可以使用 GEOSGeometry.coords 属性将几何坐标作为 Python 元组获取：

>>> pnt.coords
(5.0, 23.0)

可以使用标准的 Python 索引技术来获取/设置几何组件。但是，返回的内容取决于对象的几何类型。例如，在 LineString 上进行索引返回一个坐标元组：

>>> from django.contrib.gis.geos import LineString
>>> line = LineString((0, 0), (0, 50), (50, 50), (50, 0), (0, 0))
>>> line[0]
(0.0, 0.0)
>>> line[-2]
(50.0, 0.0)

而在 Polygon 上进行索引将返回与索引对应的环（一个 LinearRing 对象）：

>>> from django.contrib.gis.geos import Polygon
>>> poly = Polygon(((0.0, 0.0), (0.0, 50.0), (50.0, 50.0), (50.0, 0.0), (0.0, 0.0)))
>>> poly[0]
<LinearRing object at 0x1044395b0>
>>> poly[0][-2]  # second-to-last coordinate of external ring
(50.0, 0.0)

此外，几何的坐标/组件可以像 Python 列表一样添加或修改：

>>> line[0] = (1.0, 1.0)
>>> line.pop()
(0.0, 0.0)
>>> line.append((1.0, 1.0))
>>> line.coords
((1.0, 1.0), (0.0, 50.0), (50.0, 50.0), (50.0, 0.0), (1.0, 1.0))

几何对象支持类似集合的运算符：

>>> from django.contrib.gis.geos import LineString
>>> ls1 = LineString((0, 0), (2, 2))
>>> ls2 = LineString((1, 1), (3, 3))
>>> print(ls1 | ls2)  # equivalent to `ls1.union(ls2)`
MULTILINESTRING ((0 0, 1 1), (1 1, 2 2), (2 2, 3 3))
>>> print(ls1 & ls2)  # equivalent to `ls1.intersection(ls2)`
LINESTRING (1 1, 2 2)
>>> print(ls1 - ls2)  # equivalent to `ls1.difference(ls2)`
LINESTRING(0 0, 1 1)
>>> print(ls1 ^ ls2)  # equivalent to `ls1.sym_difference(ls2)`
MULTILINESTRING ((0 0, 1 1), (2 2, 3 3))

GEOSGeometryLink to this heading#

class GEOSGeometry(geo_input, srid=None, *, max_geom_collections=198)Link to this definition#

参数:

• geo_input -- 几何输入值（字符串或 memoryview）

• srid (int) -- 空间参考标识符（SRID）

• max_geom_collections -- maximum number of nested (WKT) or total (WKB) geometry collections accepted before parsing is refused

这是所有 GEOS 几何对象的基类。它根据给定的 geo_input 参数进行初始化，然后假定适当的几何子类（例如，GEOSGeometry('POINT(1 1)') 将创建一个 Point 对象）。

如果提供了 srid 参数，并且 geo_input 没有 SRID，则将其设置为创建的几何对象的 SRID。如果通过 geo_input 和 srid 参数提供了不同的 SRID，则会引发 ValueError：

>>> from django.contrib.gis.geos import GEOSGeometry
>>> GEOSGeometry("POINT EMPTY", srid=4326).ewkt
'SRID=4326;POINT EMPTY'
>>> GEOSGeometry("SRID=4326;POINT EMPTY", srid=4326).ewkt
'SRID=4326;POINT EMPTY'
>>> GEOSGeometry("SRID=1;POINT EMPTY", srid=4326)
Traceback (most recent call last):
...
ValueError: Input geometry already has SRID: 1.

以下输入格式以及它们对应的 Python 类型被接受：

对于 GeoJSON 格式，SRID 是根据 crs 成员设置的。如果没有提供 crs，SRID 默认为 4326。

classmethod GEOSGeometry.from_gml(gml_string)Link to this definition#

从给定的 GML 字符串构造一个 GEOSGeometry。

PointLink to this heading#

class Point(x=None, y=None, z=None, srid=None)Link to this definition#

可以使用表示点的组件坐标或单个坐标序列来实例化 Point 对象。例如，以下方式是等效的：

Python console

>>> pnt = Point(5, 23)
>>> pnt = Point([5, 23])

可以通过不传递参数或传递一个空序列来实例化空的 Point 对象。以下方式是等效的：

Python console

>>> pnt = Point()
>>> pnt = Point([])

LineStringLink to this heading#

class LineString(*args, **kwargs)Link to this definition#

可以使用坐标序列或 Point 对象作为参数来实例化 LineString 对象。例如，以下方式是等效的：

Python console

>>> ls = LineString((0, 0), (1, 1))
>>> ls = LineString(Point(0, 0), Point(1, 1))

此外，还可以通过传递单个坐标序列或 Point 对象的序列来创建 LineString 对象：

Python console

>>> ls = LineString(((0, 0), (1, 1)))
>>> ls = LineString([Point(0, 0), Point(1, 1)])

可以通过不传递参数或传递一个空序列来实例化空的 LineString 对象。以下方式是等效的：

Python console

>>> ls = LineString()
>>> ls = LineString([])

closedLink to this definition#

返回此 LineString 是否闭合。

LinearRingLink to this heading#

class LinearRing(*args, **kwargs)Link to this definition#

LinearRing 对象的构造方式与 LineString 对象完全相同，但坐标必须是 闭合 的，也就是说，第一个坐标必须与最后一个坐标相同。例如：

Python console

>>> ls = LinearRing((0, 0), (0, 1), (1, 1), (0, 0))

请注意，(0, 0) 是第一个和最后一个坐标 -- 如果它们不相等，就会引发错误。

is_counterclockwiseLink to this definition#

返回此 LinearRing 是否为逆时针方向。

PolygonLink to this heading#

class Polygon(*args, **kwargs)Link to this definition#

Polygon 对象可以通过传入代表多边形环的参数来实例化。这些参数必须要么是 LinearRing 实例，要么是用于构建 LinearRing 的序列：

Python console

>>> ext_coords = ((0, 0), (0, 1), (1, 1), (1, 0), (0, 0))
>>> int_coords = ((0.4, 0.4), (0.4, 0.6), (0.6, 0.6), (0.6, 0.4), (0.4, 0.4))
>>> poly = Polygon(ext_coords, int_coords)
>>> poly = Polygon(LinearRing(ext_coords), LinearRing(int_coords))

classmethod from_bbox(bbox)Link to this definition#

从给定的边界框返回一个多边形对象，边界框是由 (xmin, ymin, xmax, ymax) 组成的 4 元组。

num_interior_ringsLink to this definition#

返回此几何对象中内部环的数量。

MultiPointLink to this heading#

class MultiPoint(*args, **kwargs)Link to this definition#

MultiPoint 对象可以通过传入 Point 对象作为参数，或者传入包含 Point 对象的单个序列来实例化：

Python console

>>> mp = MultiPoint(Point(0, 0), Point(1, 1))
>>> mp = MultiPoint((Point(0, 0), Point(1, 1)))

MultiLineStringLink to this heading#

class MultiLineString(*args, **kwargs)Link to this definition#

MultiLineString 对象可以通过传入 LineString 对象作为参数，或者传入包含 LineString 对象的单个序列来实例化：

Python console

>>> ls1 = LineString((0, 0), (1, 1))
>>> ls2 = LineString((2, 2), (3, 3))
>>> mls = MultiLineString(ls1, ls2)
>>> mls = MultiLineString([ls1, ls2])

mergedLink to this definition#

返回一个代表此 MultiLineString 中所有组件线合并的 LineString。

closedLink to this definition#

只有当所有元素都闭合时返回 True。

MultiPolygonLink to this heading#

class MultiPolygon(*args, **kwargs)Link to this definition#

MultiPolygon 对象可以通过传入 Polygon 对象作为参数，或者传入包含 Polygon 对象的单个序列来实例化：

Python console

>>> p1 = Polygon(((0, 0), (0, 1), (1, 1), (0, 0)))
>>> p2 = Polygon(((1, 1), (1, 2), (2, 2), (1, 1)))
>>> mp = MultiPolygon(p1, p2)
>>> mp = MultiPolygon([p1, p2])

GeometryCollectionLink to this heading#

class GeometryCollection(*args, **kwargs)Link to this definition#

GeometryCollection 对象可以通过传入其他 GEOSGeometry 作为参数，或者传入包含 GEOSGeometry 对象的单个序列来实例化：

Python console

>>> poly = Polygon(((0, 0), (0, 1), (1, 1), (0, 0)))
>>> gc = GeometryCollection(Point(0, 0), MultiPoint(Point(0, 0), Point(1, 1)), poly)
>>> gc = GeometryCollection((Point(0, 0), MultiPoint(Point(0, 0), Point(1, 1)), poly))

PreparedGeometryLink to this heading#

class PreparedGeometryLink to this definition#

PreparedGeometry 上的所有方法都接受一个 other 参数，该参数必须是一个 GEOSGeometry 实例。

contains(other)Link to this definition#

contains_properly(other)Link to this definition#

covers(other)Link to this definition#

crosses(other)Link to this definition#

disjoint(other)Link to this definition#

intersects(other)Link to this definition#

overlaps(other)Link to this definition#

touches(other)Link to this definition#

within(other)Link to this definition#

读取器对象Link to this heading#

读取器 I/O 类从给定给它们的 WKB 和/或 WKT 输入中的 read(geom) 方法返回一个 GEOSGeometry 实例。

class WKBReaderLink to this definition#

例如：

Python console

>>> from django.contrib.gis.geos import WKBReader
>>> wkb_r = WKBReader()
>>> wkb_r.read("0101000000000000000000F03F000000000000F03F")
<Point object at 0x103a88910>

class WKTReaderLink to this definition#

例如：

Python console

>>> from django.contrib.gis.geos import WKTReader
>>> wkt_r = WKTReader()
>>> wkt_r.read("POINT(1 1)")
<Point object at 0x103a88b50>

写入器对象Link to this heading#

所有写入器对象都具有一个 write(geom) 方法，该方法返回给定几何对象的 WKB 或 WKT。此外，WKBWriter 对象还具有可用于更改字节顺序或包括 SRID 值的属性（即 EWKB）。

class WKBWriter(dim=2)Link to this definition#

WKBWriter 提供对其输出的最大控制。默认情况下，当调用其 write 方法时，它返回符合 OGC 标准的 WKB。然而，它具有允许创建 EWKB 的属性，这是 WKB 标准的一个超集，包含附加信息。有关 dim 参数的更多详细信息，请参阅 WKBWriter.outdim 文档。

write(geom)Link to this definition#

将给定几何对象的 WKB 返回为 Python 的 buffer 对象。示例：

Python console

>>> from django.contrib.gis.geos import Point, WKBWriter
>>> pnt = Point(1, 1)
>>> wkb_w = WKBWriter()
>>> wkb_w.write(pnt)
<read-only buffer for 0x103a898f0, size -1, offset 0 at 0x103a89930>

write_hex(geom)Link to this definition#

以十六进制返回几何对象的 WKB。示例：

Python console

>>> from django.contrib.gis.geos import Point, WKBWriter
>>> pnt = Point(1, 1)
>>> wkb_w = WKBWriter()
>>> wkb_w.write_hex(pnt)
'0101000000000000000000F03F000000000000F03F'

byteorderLink to this definition#

这个属性可以设置来改变几何表示的字节顺序。

字节顺序值	描述
0	大端字节序（例如，与 RISC 系统兼容）
1	小端字节序（例如，与 x86 系统兼容）

例如：

Python console

>>> from django.contrib.gis.geos import Point, WKBWriter
>>> wkb_w = WKBWriter()
>>> pnt = Point(1, 1)
>>> wkb_w.write_hex(pnt)
'0101000000000000000000F03F000000000000F03F'
>>> wkb_w.byteorder = 0
'00000000013FF00000000000003FF0000000000000'

outdimLink to this definition#

此属性可以设置为更改几何表示的输出维度。换句话说，如果您有一个三维几何对象，可以将其设置为 3，以便在 WKB 中包含 Z 值。

Outdim 值	描述
2	默认情况下，输出 2D WKB。
3	输出 3D WKB。

例如：

Python console

>>> from django.contrib.gis.geos import Point, WKBWriter
>>> wkb_w = WKBWriter()
>>> wkb_w.outdim
2
>>> pnt = Point(1, 1, 1)
>>> wkb_w.write_hex(pnt)  # By default, no Z value included:
'0101000000000000000000F03F000000000000F03F'
>>> wkb_w.outdim = 3  # Tell writer to include Z values
>>> wkb_w.write_hex(pnt)
'0101000080000000000000F03F000000000000F03F000000000000F03F'

sridLink to this definition#

将此属性设置为布尔值，以指示几何对象的 SRID 是否应包含在 WKB 表示中。示例：

Python console

>>> from django.contrib.gis.geos import Point, WKBWriter
>>> wkb_w = WKBWriter()
>>> pnt = Point(1, 1, srid=4326)
>>> wkb_w.write_hex(pnt)  # By default, no SRID included:
'0101000000000000000000F03F000000000000F03F'
>>> wkb_w.srid = True  # Tell writer to include SRID
>>> wkb_w.write_hex(pnt)
'0101000020E6100000000000000000F03F000000000000F03F'

class WKTWriter(dim=2, trim=False, precision=None)Link to this definition#

这个类允许输出几何对象的 WKT 表示。有关构造函数参数的详细信息，请参阅 WKBWriter.outdim、trim 和 precision 属性。

write(geom)Link to this definition#

返回给定几何对象的 WKT。示例：

Python console

>>> from django.contrib.gis.geos import Point, WKTWriter
>>> pnt = Point(1, 1)
>>> wkt_w = WKTWriter()
>>> wkt_w.write(pnt)
'POINT (1.0000000000000000 1.0000000000000000)'

outdimLink to this definition#

查看 WKBWriter.outdim 。

trimLink to this definition#

此属性用于启用或禁用修剪不必要的小数位。

Python console

>>> from django.contrib.gis.geos import Point, WKTWriter
>>> pnt = Point(1, 1)
>>> wkt_w = WKTWriter()
>>> wkt_w.trim
False
>>> wkt_w.write(pnt)
'POINT (1.0000000000000000 1.0000000000000000)'
>>> wkt_w.trim = True
>>> wkt_w.write(pnt)
'POINT (1 1)'

precisionLink to this definition#

此属性控制坐标的四舍五入精度；如果设置为 None，则禁用四舍五入。

Code

>>> from django.contrib.gis.geos import Point, WKTWriter
>>> pnt = Point(1.44, 1.66)
>>> wkt_w = WKTWriter()
>>> print(wkt_w.precision)
None
>>> wkt_w.write(pnt)
'POINT (1.4399999999999999 1.6599999999999999)'
>>> wkt_w.precision = 0
>>> wkt_w.write(pnt)
'POINT (1 2)'
>>> wkt_w.precision = 1
>>> wkt_w.write(pnt)
'POINT (1.4 1.7)'

脚注

GEOS_LIBRARY_PATHLink to this heading#

一个字符串，指定 GEOS C 库的位置。通常情况下，只有在 GEOS C 库位于非标准位置时才使用此设置（例如，/home/bob/lib/libgeos_c.so）。