地理信息系统API

背景

GEOS是什么？

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

特点

GeoDjango 为 GEOS 库实现了一个高级 Python 包装器，其功能包括：

GEOS 几何例程的 BSD 许可接口，使用 ctypes 完全在 Python 中实现。
与 GeoDjango 松散耦合。例如， GEOSGeometry 对象可以在 Django 项目/应用程序之外使用。换句话说，不需要设置 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(buffer('\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x14@\x00\x00\x00\x00\x00\x007@'))
>>> 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 相关的错误

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

几何是 Pythonic

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

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

GEEOSGeometry 相等运算符使用 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): ;; 参数

;;* geo_input – 几何输入值（字符串或缓冲区）

srid (int) – 空间参考标识符

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

如果 geo_input 没有 SRID，则 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 类型：

格式	输入类型
WKT / EWKT	`str`
十六进制 / HEXEWKB	`str`
WKB / EWKB	`buffer`
GeoJSON	`str`

对于 GeoJSON 格式，根据 crs 成员设置 SRID。如果未提供 crs，则 SRID 默认为 4326。

classmethod GEOSGeometry.from_gml(gml_string): 从给定的 GML 字符串构造一个 GEOSGeometry。

属性

GEOSGeometry.coords: 以元组形式返回几何的坐标。

GEOSGeometry.dims: 返回几何尺寸：

0 用于 Points 和 MultiPoints 1 用于 LineStrings 和 MultiLineStrings 2 用于 Polygons 和 MultiPolygons -1 为空 GeometryCollections 非空 GeometryCollections 元素的最大尺寸

GEOSGeometry.empty: 返回几何中的点集是否为空。

GEOSGeometry.geom_type

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

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

GEOSGeometry.geom_typeid

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

几何	身份证
`Point`	0
`LineString`	1
`LinearRing`	2
`Polygon`	3
`MultiPoint`	4
`MultiLineString`	5
`MultiPolygon`	6
`GeometryCollection`	7

GEOSGeometry.num_coords: 返回几何中的坐标数。

GEOSGeometry.num_geom: 返回此几何图形中的几何图形数量。换句话说，除了几何集合之外的任何东西都将返回 1。

GEOSGeometry.hasz: 返回一个布尔值，指示几何图形是否是三维的。

GEOSGeometry.ring: 返回一个布尔值，指示几何图形是否为 LinearRing。

GEOSGeometry.simple: 返回一个布尔值，指示几何图形是否“简单”。一个几何体是简单的，当且仅当它不与自身相交（除了在边界点处）。例如，LineString 对象如果与自身相交就不是简单的。因此， LinearRing 和 Polygon 对象总是很简单的，因为根据定义，它们确实不能相交。

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: 返回几何体的“扩展”众所周知的文本。此表示特定于 PostGIS，并且是 OGC WKT 标准的超集。 1 本质上，SRID 被添加到 WKT 表示之前，例如 SRID=4326;POINT(5 23)。

笔记

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

GEOSGeometry.hex: 以十六进制形式返回此 Geometry 的 WKB。请注意，此表示中不包含 SRID 值，因为它不是 OGC 规范的一部分（请改用 GEEOSGeometry.hexewkb 属性）。

GEOSGeometry.hexewkb: 以十六进制形式返回此 Geometry 的 EWKB。这是 WKB 规范的扩展，其中包括作为此几何体一部分的 SRID 值。

GEOSGeometry.json: 返回几何的 GeoJSON 表示。请注意，结果不是完整的 GeoJSON 结构，而只是 GeoJSON 结构的 geometry 键内容。另见 GeoJSON 序列化器。

GEOSGeometry.geojson: GEOSGeometry.json 的别名。

GEOSGeometry.kml: 返回几何的 KML（Keyhole 标记语言）表示。这应该仅用于 SRID 为 4326 (WGS84) 的几何图形，但不强制执行此限制。

GEOSGeometry.ogr: 返回对应于 GEOS 几何的 OGRGeometry 对象。

GEOSGeometry.wkb: 将此几何的 WKB（众所周知的二进制）表示返回为 Python 缓冲区。不包括 SRID 值，请改用 GEOSGeometry.ewkb 属性。

GEOSGeometry.ewkb: 将此 Geometry 的 EWKB 表示作为 Python 缓冲区返回。这是 WKB 规范的扩展，包括作为此几何体一部分的任何 SRID 值。

GEOSGeometry.wkt: 返回几何的众所周知的文本（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******（对于点和曲线、点和面积或线和面积），则返回 True 0******** ]（对于两条曲线）。

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 – 字母表中的九个字符的字符串，则返回 True：{T， F、*、0}。

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 可以是圆形 (1)、平面 (2) 或方形 (3)。 join_style 可以是圆形 (1)、斜接 (2) 或斜角 (3)。 斜接比率限制 (mitre_limit) 仅影响斜接连接样式。

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 对象可以被拆分、折叠成线或消失。多边形孔可以创建或消失，线可以交叉。通过指定 preserve_topology=True，结果将具有与输入相同的维度和分量数；但是，这要慢得多。

GEOSGeometry.sym_difference(other): 返回一个 GEOSGeometry 组合此几何体中不在其他几何体中的点，以及其他几何体中不在此几何体中的点。

GEOSGeometry.union(other): 返回一个 GEOSGeometry，代表这个几何图形和另一个几何图形中的所有点。

拓扑性质

GEOSGeometry.boundary: 将边界作为新分配的 Geometry 对象返回。

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: 返回此几何的长度（例如，0 表示 Point、LineString 的长度或 Polygon 的周长）。

GEOSGeometry.prepared: 返回此几何内容的 GEOS PreparedGeometry。 PreparedGeometry 对象针对包含、相交、覆盖、交叉、不相交、重叠、触摸和内部操作进行了优化。有关详细信息，请参阅准备的几何图形文档。

GEOSGeometry.srs: 返回与几何体的 SRID 或 None 对应的 SpatialReference 对象。

GEOSGeometry.transform(ct, clone=False): 根据给定的坐标变换参数 (ct) 变换几何，该参数可以是整数 SRID、空间参考 WKT 字符串、PROJ.4 字符串、SpatialReference 对象或 [ X214X]CoordTransform 对象。默认情况下，几何体在原地转换并且不返回任何内容。但是，如果设置了 clone 关键字，则不会修改几何图形，而是返回几何图形的变换克隆。

笔记

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

GEOSGeometry.normalize()

将此几何转换为规范形式：

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

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)

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

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

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

>>> 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 对象完全相同，但坐标必须为 closed，即第一个坐标必须与最后坐标。例如：

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

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

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对象与<或>进行比较，但由于是通过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: 返回一个 LineString，表示此 MultiLineString 中所有组件的行合并。

closed: 当且仅当所有元素都关闭时返回 True。需要 GEOS 3.5。

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)

参数: file_h（Python file 对象或文件的字符串路径）——包含空间数据的输入文件
返回类型: 一个GEOSGeometry对应文件中的空间数据

例子：

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

fromstr(string, srid=None)

参数

string (str) – 包含空间数据的字符串
srid (int) – 空间参考标识符

返回类型

一个GEOSGeometry对应字符串中的空间数据

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

例子：

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

输入/输出对象

读者对象

读取器 I/O 类从提供给其 read(geom) 方法的 WKB 和/或 WKT 输入返回一个 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

可以设置此属性以更改几何表示的字节顺序。

字节顺序值	说明
0	Big Endian（例如，与 RISC 系统兼容）
1	Little Endian（例如，与 x86 系统兼容）

例子：

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

可以设置此属性以更改几何表示的输出尺寸。换句话说，如果您有一个 3D 几何体，则设置为 3，以便 Z 值包含在 WKB 中。

过时的价值	说明
2	默认情况下，输出 2D WKB。
3	输出 3D WKB。

例子：

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

脚注

1: 看 PostGIS EWKB、EWKT 和规范形式, PostGIS documentation at Ch. 4.1.2.

设置

GEOS_LIBRARY_PATH

指定 GEOS C 库位置的字符串。通常，仅当 GEOS C 库位于非标准位置（例如，/home/bob/lib/libgeos_c.so）时才使用此设置。

笔记

设置必须是C共享库的full路径；换句话说，您想使用 libgeos_c.so，而不是 libgeos.so。

例外

exception GEOSException: 基本 GEOS 异常表示与 GEOS 相关的错误。

GEOS API — Django 文档

目录