GEOS API

背景

什么是 GEOS?

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

特性

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

• 一个使用 ctypes 纯粹在 Python 中实现的，对 GEOS 几何例程提供的 BSD 许可接口。
• 与 GeoDjango 松散耦合。例如，可以在 Django 项目/应用程序之外使用 GEOSGeometry 对象。换句话说，无需设置 DJANGO_SETTINGS_MODULE 或使用数据库等。
• 可变性：GEOSGeometry 对象可以被修改。
• 跨平台并经过测试；兼容 Windows、Linux、Solaris 和 macOS 平台。

教程

这个部分包含了使用 GEOSGeometry 对象的简要介绍和教程。

创建几何对象

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

我的日志中充满了与 GEOS 相关的错误。

你在 Web 服务器的日志文件中发现了许多 TypeError 或 AttributeError 异常。这通常意味着你在一些 Python 模块的顶层创建了 GEOS 对象。然后，由于垃圾收集器中的竞态条件，你的模块在 GEOS 对象之前被垃圾回收。为了防止这种情况发生，请在你的函数/方法的局部范围内创建 GEOSGeometry 对象。

几何对象是符合 Python 风格的

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

等号运算符不检查空间相等性

GEOSGeometry 的等号运算符使用的是 equals_exact()，而不是 equals()，也就是说，它要求比较的几何对象在相同的位置具有相同的坐标和相同的 SRID：

>>> from django.contrib.gis.geos import LineString
>>> ls1 = LineString((0, 0), (1, 1))
>>> ls2 = LineString((1, 1), (0, 0))
>>> ls3 = LineString((1, 1), (0, 0), srid=4326)
>>> ls1.equals(ls2)
True
>>> ls1 == ls2
False
>>> ls3 == ls2  # different SRIDs
False

几何对象

GEOSGeometry

class GEOSGeometry(geo_input, srid=None)

这是所有 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)

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

属性

GEOSGeometry.coords

返回几何的坐标作为一个元组。

GEOSGeometry.dims

返回几何的维度：

• 对于 Point 和 MultiPoint，返回值为 0
• 对于 LineString 和 MultiLineString，返回值为 1
• 对于 Polygon 和 MultiPolygon，返回值为 2
• 对于空的 GeometryCollection，返回值为 -1
• 对于非空的 GeometryCollection，返回其元素的最大维度。

GEOSGeometry.empty

返回几何中的点集是否为空。

GEOSGeometry.geom_type

返回与几何类型相对应的字符串。例如：

>>> pnt = GEOSGeometry("POINT(5 23)")
>>> pnt.geom_type
'Point'

GEOSGeometry.geom_typeid

返回 GEOS 几何类型的识别号码。以下表格显示了每种几何类型的值：

GEOSGeometry.num_coords

返回几何中坐标的数量。

GEOSGeometry.num_geom

返回此几何中的几何数量。换句话说，在几何集合之外的任何几何对象上都会返回 1。

GEOSGeometry.hasz

返回一个布尔值，指示几何是否是三维的。

GEOSGeometry.ring

返回一个布尔值，指示几何是否是 LinearRing。

GEOSGeometry.simple

返回一个布尔值，指示几何是否是 ‘simple’。只有当几何不与自身相交（除了边界点）时，几何才被认为是 simple。例如，如果 LineString 对象与自身相交，则它不是 simple。因此，LinearRing 和 Polygon 对象总是 simple，因为根据定义它们不能与自身相交。

GEOSGeometry.valid

返回一个布尔值，指示几何是否有效。

GEOSGeometry.valid_reason

返回一个描述几何无效的原因的字符串。

GEOSGeometry.srid

用于检索或设置与几何相关联的 SRID 的属性。例如：

>>> pnt = Point(5, 23)
>>> print(pnt.srid)
None
>>> pnt.srid = 4326
>>> pnt.srid
4326

输出属性

此部分中的属性将 GEOSGeometry 对象导出为不同的格式。输出可以是字符串、缓冲区，甚至是另一个对象的形式。

GEOSGeometry.ewkt

返回几何的 “扩展” Well-Known Text（WKT）。此表示形式特定于 PostGIS，并且是 OGC WKT 标准的超集。[1] 基本上，SRID 被添加到 WKT 表示中，例如 SRID=4326;POINT(5 23)。

备注

此属性的输出不包括 PostGIS 在其 EWKT 表示中支持的 3dm、3dz 和 4d 信息。

GEOSGeometry.hex

以十六进制形式返回此几何的 WKB。请注意，SRID 值不包括在此表示中，因为它不是 OGC 规范的一部分（请使用 GEOSGeometry.hexewkb 属性）。

GEOSGeometry.hexewkb

以十六进制形式返回此几何的 EWKB。这是 WKB 规范的扩展，包括与此几何对象相关的 SRID 值。

GEOSGeometry.json

返回几何的 GeoJSON 表示。请注意，结果不是完整的 GeoJSON 结构，而只是 GeoJSON 结构中 geometry 键的内容。还请参阅 GeoJSON 序列化器。

GEOSGeometry.geojson

是 GEOSGeometry.json 的别名。

GEOSGeometry.kml

返回几何的 KML （Keyhole Markup Language）表示。这应该仅用于具有 SRID 4326（WGS84）的几何对象，但此限制不受强制执行。

GEOSGeometry.ogr

返回与 GEOS 几何对应的 OGRGeometry 对象。

GEOSGeometry.wkb

以 Python 缓冲区的形式返回此几何的 WKB（Well-Known Binary）表示。不包括 SRID 值，请使用 GEOSGeometry.ewkb 属性代替。

GEOSGeometry.ewkb

以 Python 缓冲区的形式返回此几何的 EWKB 表示。这是 WKB 规范的扩展，包括与此几何对象相关的任何 SRID 值。

GEOSGeometry.wkt

返回几何的 Well-Known Text（OGC 标准）。

空间谓词方法

以下所有的空间谓词方法都以另一个 GEOSGeometry 实例（other）作为参数，并返回一个布尔值。

GEOSGeometry.contains(other)

如果 other.within(this) 返回 True，则返回 True。

GEOSGeometry.covers(other)

如果此几何覆盖指定的几何，则返回 True。

covers 谓词具有以下等价定义：

• 其他几何的每个点都是此几何的点。
• 两个几何对象的 DE-9IM 交集矩阵为 T*****FF*, *T****FF*, ***T**FF*, 或 ****T*FF*。

如果其中一个几何为空，则返回 False。

此谓词类似于 GEOSGeometry.contains()，但更加包容性（即对更多情况返回 True）。特别地，与 contains() 不同，它不区分边界和几何内部的点。在大多数情况下，应该首选使用 covers() 而不是 contains()。作为额外的好处，covers() 更容易进行优化，因此应该优于 contains()。

GEOSGeometry.crosses(other)

如果两个几何对象的 DE-9IM 交集矩阵为 T*T****** （对于点和曲线、点和区域或线和区域）或 0******** （对于两个曲线），则返回 True。

GEOSGeometry.disjoint(other)

如果两个几何对象的 DE-9IM 交集矩阵为 FF*FF****，则返回 True。

GEOSGeometry.equals(other)

如果两个几何对象的 DE-9IM 交集矩阵为 T*F**FFF*，则返回 True。

GEOSGeometry.equals_exact(other, tolerance=0)

如果两个几何对象在指定的容差范围内完全相等，则返回 True。tolerance 值应该是一个浮点数，表示比较中的误差容差，例如，poly1.equals_exact(poly2, 0.001) 将在千分之一的单位内进行比较相等。

GEOSGeometry.intersects(other)

如果 GEOSGeometry.disjoint() 为 False，则返回 True。

GEOSGeometry.overlaps(other)

如果两个几何对象的 DE-9IM 交集矩阵为 T*T***T** （对于两个点或两个表面）或 1*T***T** （对于两个曲线），则返回 True。

GEOSGeometry.relate_pattern(other, pattern)

如果此几何对象和其他几何对象的 DE-9IM 交集矩阵中的元素与给定的 pattern 匹配（一个由字母 {T, F, *, 0} 组成的九个字符的字符串），则返回 True。

GEOSGeometry.touches(other)

如果两个几何对象的 DE-9IM 交集矩阵为 FT*******、F**T***** 或 F***T****，则返回 True。

GEOSGeometry.within(other)

如果两个几何对象的 DE-9IM 交集矩阵为 T*F**F***，则返回 True。

拓扑方法

GEOSGeometry.buffer(width, quadsegs=8)

返回一个 GEOSGeometry，表示距离此几何对象小于或等于给定的 width 的所有点。可选的 quadsegs 关键字设置用于近似一个四分之一圆的段数（默认值为 8）。

GEOSGeometry.buffer_with_style(width, quadsegs=8, end_cap_style=1, join_style=1, mitre_limit=5.0)

与 buffer() 相同，但允许自定义缓冲区的样式。

• end_cap_style 可以是 round（1）、flat（2）或 square（3）。
• join_style 可以是 round（1）、mitre（2）或 bevel（3）。
• Mitre ratio limit（mitre_limit）仅影响 mitred join style。

GEOSGeometry.difference(other)

返回一个表示构成此几何的点但不构成其他几何的 GEOSGeometry。

GEOSGeometry.interpolate(distance)

GEOSGeometry.interpolate_normalized(distance)

给定一个距离（浮点数），返回几何对象（LineString 或 MultiLineString）中距离最近的点（或最近的点）。标准化版本将距离作为介于 0（起点）和 1（终点）之间的浮点数。

与 GEOSGeometry.project() 的相反操作。

GEOSGeometry.intersection(other)

返回一个表示此几何对象和其他几何对象共享的点的 GEOSGeometry。

GEOSGeometry.project(point)

GEOSGeometry.project_normalized(point)

返回从几何对象（LineString 或 MultiLineString）的起点到在几何对象上投影的点（即距离给定点最近的线上的点）的距离（浮点数）。标准化版本将距离作为介于 0（起点）和 1（终点）之间的浮点数返回。

与 GEOSGeometry.interpolate() 的相反操作。

GEOSGeometry.relate(other)

返回表示此几何对象与其他几何对象之间拓扑关系的 DE-9IM 交集矩阵（字符串）。

GEOSGeometry.simplify(tolerance=0.0, preserve_topology=False)

返回一个新的 GEOSGeometry，使用 Douglas-Peucker 算法简化到指定的容差。较高的容差值意味着输出中的点较少。如果没有提供容差，则默认为 0。

默认情况下，此函数不保持拓扑关系。例如，Polygon 对象可以被分割，折叠成线，或消失。Polygon 的孔可以被创建或消失，线可能会相交。通过指定 preserve_topology=True，结果将具有与输入相同的维度和组件数量；然而，这会显著减慢处理速度。

GEOSGeometry.sym_difference(other)

返回一个 GEOSGeometry，其中包含此几何对象中不在其他几何中的点以及其他几何中不在此几何中的点。

GEOSGeometry.union(other)

返回一个 GEOSGeometry，表示此几何对象和其他几何对象中的所有点。

拓扑属性

GEOSGeometry.boundary

返回边界作为一个新分配的几何对象。

GEOSGeometry.centroid

返回一个 Point 对象，表示几何对象的几何中心。不能保证该点位于几何对象的内部。

GEOSGeometry.convex_hull

返回包含几何中所有点的最小 Polygon。

GEOSGeometry.envelope

返回一个表示此几何的边界包围框的 Polygon。请注意，如果输入几何对象是一个点，它也可以返回一个 Point。

GEOSGeometry.point_on_surface

计算并返回一个保证位于此几何对象内部的 Point。

GEOSGeometry.unary_union

计算此几何对象的所有元素的并集。

结果遵循以下约定：

• 对一组 LineString 进行并集操作将完全节点化和融合线段。
• 对一组 Polygon 进行并集操作将始终返回一个 Polygon 或 MultiPolygon 几何对象（与 GEOSGeometry.union() 不同，如果拓扑崩溃发生，可能返回较低维度的几何对象）。

其他属性和方法

GEOSGeometry.area

此属性返回几何对象的面积。

GEOSGeometry.extent

此属性返回几何对象的范围，以 4 元组形式表示，包括 (xmin, ymin, xmax, ymax)。

GEOSGeometry.clone()

此方法返回原始几何对象的克隆 GEOSGeometry。

GEOSGeometry.distance(geom)

返回此几何对象与给定的 geom （另一个 GEOSGeometry 对象）之间的最近点之间的距离。

备注

GEOS 距离计算是线性的，换句话说，即使 SRID 指定地理坐标系，GEOS 不会执行球面计算。

GEOSGeometry.length

返回此几何对象的长度（例如，对于 Point，长度为 0，对于 LineString，长度为线段的长度，对于 Polygon，长度为多边形的周长）。

GEOSGeometry.prepared

返回此几何对象内容的 GEOS PreparedGeometry。PreparedGeometry 对象针对 contains、intersects、covers、crosses、disjoint、overlaps、touches 和 within 操作进行了优化。有关更多信息，请参阅 准备好的几何对象 文档。

GEOSGeometry.srs

返回与几何对象的 SRID 对应的 SpatialReference 对象，如果没有则返回 None。

GEOSGeometry.transform(ct, clone=False)

根据给定的坐标转换参数（ct）来转换几何对象，参数可以是整数 SRID、空间参考 WKT 字符串、PROJ 字符串、SpatialReference 对象或 CoordTransform 对象。默认情况下，几何对象会原地转换，不返回任何内容。但是如果设置了 clone 关键字参数，则不会修改几何对象，而是返回一个经过转换的几何对象的克隆。

备注

如果没有安装 GDAL，或者几何对象的 SRID 为 None 或小于 0，则会引发 GEOSException。如果使用 CoordTransform 对象调用，则不会对几何对象的 SRID 强加任何约束。

GEOSGeometry.make_valid()

New in Django 4.1.

返回一个有效的 GEOSGeometry 等效对象，尽量不丢失输入的顶点。如果几何对象已经有效，则原样返回。这类似于数据库函数 MakeValid。需要 GEOS 3.8。

GEOSGeometry.normalize(clone=False)

将此几何对象转换为规范形式。如果设置了 clone 关键字参数，则不会修改几何对象，而是返回一个规范化的几何对象的克隆：

>>> g = MultiPoint(Point(0, 0), Point(2, 2), Point(1, 1))
>>> print(g)
MULTIPOINT (0 0, 2 2, 1 1)
>>> g.normalize()
>>> print(g)
MULTIPOINT (2 2, 1 1, 0 0)

Changed in Django 4.1:

添加了 clone 参数。

Point

class Point(x=None, y=None, z=None, srid=None)

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

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

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

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

LineString

class LineString(*args, **kwargs)

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

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

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

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

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

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

• closed

  返回此 LineString 是否闭合。

LinearRing

class LinearRing(*args, **kwargs)

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

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

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

• is_counterclockwise

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

Polygon

class Polygon(*args, **kwargs)

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

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

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

• num_interior_rings

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

比较多边形

请注意，可以直接使用 < 或 > 比较 Polygon 对象，但由于比较是通过多边形的 LineString 进行的，所以意义不大（但是一致且快速）。您始终可以使用 area 属性强制进行比较：

>>> if poly_1.area > poly_2.area:
...     pass
...

几何集合

MultiPoint

class MultiPoint(*args, **kwargs)

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

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

MultiLineString

class MultiLineString(*args, **kwargs)

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

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

• merged

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

• closed

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

MultiPolygon

class MultiPolygon(*args, **kwargs)

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

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

GeometryCollection

class GeometryCollection(*args, **kwargs)

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

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

准备好的几何对象

要获得一个准备好的几何对象，请访问 GEOSGeometry.prepared 属性。一旦您有了一个 PreparedGeometry 实例，它下面列出的空间谓词方法可以与其他 GEOSGeometry 对象一起使用。使用准备好的几何对象进行操作可以快几个数量级 — 准备的几何越复杂，操作的速度提升就越大。有关更多信息，请参考 GEOS 准备好的几何页面。

例如：

>>> from django.contrib.gis.geos import Point, Polygon
>>> poly = Polygon.from_bbox((0, 0, 5, 5))
>>> prep_poly = poly.prepared
>>> prep_poly.contains(Point(2.5, 2.5))
True

PreparedGeometry

class PreparedGeometry

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

• contains(other)

• contains_properly(other)

• covers(other)

• crosses(other)

• disjoint(other)

• intersects(other)

• overlaps(other)

• touches(other)

• within(other)

几何工厂

fromfile(file_h)

例如：

>>> from django.contrib.gis.geos import fromfile
>>> g = fromfile("/home/bob/geom.wkt")

fromstr(string, srid=None)

fromstr(string, srid) 等价于 GEOSGeometry(string, srid)。

例如：

>>> from django.contrib.gis.geos import fromstr
>>> pnt = fromstr("POINT(-90.5 29.5)", srid=4326)

I/O 对象

读取器对象

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

class WKBReader

例如：

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

class WKTReader

例如：

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

写入器对象

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

class WKBWriter(dim=2)

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

• write(geom)

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

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

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

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

• byteorder

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

例如：

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

• outdim

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

例如：

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

• srid

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

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

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

• write(geom)

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

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

• outdim

  查看 WKBWriter.outdim 。

• trim

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

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

• precision

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

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

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

备注

这个配置必须是 C 共享库的 完整 路径；换句话说，你要使用 libgeos_c.so，而不是 libgeos.so。

异常

exception GEOSException

基本的 GEOS 异常，表示与 GEOS 相关的错误。