GEOS API

背景

什么是 GEOS?

GEOS stands for Geometry Engine - Open Source, and is a C++ library, ported from the Java Topology Suite. GEOS implements the OpenGIS Simple Features for SQL spatial predicate functions and spatial operators. GEOS, now an OSGeo project, was initially developed and maintained by Refractions Research of Victoria, Canada.

特性

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

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

• Loosely-coupled to GeoDjango. For example, GEOSGeometry objects may be used outside of a Django project/application. In other words, no need to have DJANGO_SETTINGS_MODULE set or use a database, etc.

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

• 跨平台测试。

教程

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

创建几何对象

GEOSGeometry objects may be created in a few ways. The first is to simply instantiate the object on some spatial input -- the following are examples of creating the same geometry from WKT, HEX, WKB, and 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

Another option is to use the constructor for the specific geometry type that you wish to create. For example, a Point object may be created by passing in the X and Y coordinates into its constructor:

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

You can get/set geometry components using standard Python indexing techniques. However, what is returned depends on the geometry type of the object. For example, indexing on a LineString returns a coordinate tuple:

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

参数:

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

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

This is the base class for all GEOS geometry objects. It initializes on the given geo_input argument, and then assumes the proper geometry subclass (e.g., GEOSGeometry('POINT(1 1)') will create a Point object).

如果提供了 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 类型被接受：

格式	输入类型
WKT / EWKT	str
HEX / HEXEWKB	str
WKB / EWKB	memoryview
GeoJSON	str

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

Returns a string corresponding to the type of geometry. For example:

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

GEOSGeometry.geom_typeid

Returns the GEOS geometry type identification number. The following table shows the value for each geometry type:

几何	ID
Point	0
LineString	1
LinearRing	2
Polygon	3
MultiPoint	4
MultiLineString	5
MultiPolygon	6
GeometryCollection	7

GEOSGeometry.num_coords

返回几何中坐标的数量。

GEOSGeometry.num_geom

Returns the number of geometries in this geometry. In other words, will return 1 on anything but geometry collections.

GEOSGeometry.hasz

Returns a boolean indicating whether the geometry has the Z dimension.

GEOSGeometry.hasm

New in Django 6.0.

Returns a boolean indicating whether the geometry has the M dimension. Requires GEOS 3.12.

GEOSGeometry.ring

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

GEOSGeometry.simple

Returns a boolean indicating whether the geometry is 'simple'. A geometry is simple if and only if it does not intersect itself (except at boundary points). For example, a LineString object is not simple if it intersects itself. Thus, LinearRing and Polygon objects are always simple because they cannot intersect themselves, by definition.

GEOSGeometry.valid

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

GEOSGeometry.valid_reason

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

GEOSGeometry.srid

Property that may be used to retrieve or set the SRID associated with the geometry. For example:

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

输出属性

The properties in this section export the GEOSGeometry object into a different. This output may be in the form of a string, buffer, or even another object.

GEOSGeometry.ewkt

Returns the "extended" Well-Known Text of the geometry. This representation is specific to PostGIS and is a superset of the OGC WKT standard. [1] Essentially the SRID is prepended to the WKT representation, for example SRID=4326;POINT(5 23).

Note

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

GEOSGeometry.hex

Returns the WKB of this Geometry in hexadecimal form. Please note that the SRID value is not included in this representation because it is not a part of the OGC specification (use the GEOSGeometry.hexewkb property instead).

GEOSGeometry.hexewkb

Returns the EWKB of this Geometry in hexadecimal form. This is an extension of the WKB specification that includes the SRID value that are a part of this geometry.

GEOSGeometry.json

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

GEOSGeometry.geojson

是 GEOSGeometry.json 的别名。

GEOSGeometry.kml

Returns a KML (Keyhole Markup Language) representation of the geometry. This should only be used for geometries with an SRID of 4326 (WGS84), but this restriction is not enforced.

GEOSGeometry.ogr

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

GEOSGeometry.wkb

Returns the WKB (Well-Known Binary) representation of this Geometry as a Python buffer. SRID value is not included, use the GEOSGeometry.ewkb property instead.

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)

Returns true if the two geometries are exactly equal, up to a specified tolerance. The tolerance value should be a floating point number representing the error tolerance in the comparison, e.g., poly1.equals_exact(poly2, 0.001) will compare equality to within one thousandth of a unit.

GEOSGeometry.equals_identical(other)

如果两个几何图形在所有维度中的结构、顺序和顶点的值都完全相同，返回 True。NaN 值被视为与其他 NaN 值相等。需要 GEOS 3.12。

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

Returns a Point object representing the geometric center of the geometry. The point is not guaranteed to be on the interior of the geometry.

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 对象）之间的最近点之间的距离。

Note

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 关键字参数，则不会修改几何对象，而是返回一个经过转换的几何对象的克隆。

Note

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

GEOSGeometry.make_valid()

返回一个有效的 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)

Point

class Point(x=None, y=None, z=None, srid=None)[source]

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

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

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

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

LineString

class LineString(*args, **kwargs)[source]

可以使用坐标序列或 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)[source]

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

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

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

is_counterclockwise[source]

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

Polygon

class Polygon(*args, **kwargs)[source]

Polygon objects may be instantiated by passing in parameters that represent the rings of the polygon. The parameters must either be LinearRing instances, or a sequence that may be used to construct a 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)[source]

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

num_interior_rings[source]

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

比较多边形

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

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

几何集合

MultiPoint

class MultiPoint(*args, **kwargs)[source]

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

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

MultiLineString

class MultiLineString(*args, **kwargs)[source]

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

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

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

准备好的几何对象

In order to obtain a prepared geometry, access the GEOSGeometry.prepared property. Once you have a PreparedGeometry instance its spatial predicate methods, listed below, may be used with other GEOSGeometry objects. An operation with a prepared geometry can be orders of magnitude faster -- the more complex the geometry that is prepared, the larger the speedup in the operation. For more information, please consult the GEOS wiki page on prepared geometries.

例如：

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

参数:

file_h (a Python file object or a string path to the file) -- 包含空间数据的输入文件

返回类型:

一个对应于文件中空间数据的 GEOSGeometry

例如：

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

fromstr(string, srid=None)[source]

参数:

• string (str) -- 包含空间数据的字符串

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

返回类型:

一个对应于字符串中空间数据的 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 对象

读取器对象

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

class WKBReader[source]

例如：

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

class WKTReader[source]

例如：

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

写入器对象

All writer objects have a write(geom) method that returns either the WKB or WKT of the given geometry. In addition, WKBWriter objects also have properties that may be used to change the byte order, and or include the SRID value (in other words, EWKB).

class WKBWriter(dim=2)[source]

WKBWriter provides the most control over its output. By default it returns OGC-compliant WKB when its write method is called. However, it has properties that allow for the creation of EWKB, a superset of the WKB standard that includes additional information. See the WKBWriter.outdim documentation for more details about the dim argument.

write(geom)[source]

将给定几何对象的 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)[source]

Returns WKB of the geometry in hexadecimal. Example:

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

byteorder

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

字节顺序值	描述
0	大端字节序（例如，与 RISC 系统兼容）
1	小端字节序（例如，与 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[source]

This property may be set to change the output dimension of the geometry representation. In other words, if you have a 3D geometry then set to 3 so that the Z value is included in the WKB.

Outdim 值	描述
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[source]

Set this property with a boolean to indicate whether the SRID of the geometry should be included with the WKB representation. Example:

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

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

write(geom)[source]

返回给定几何对象的 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[source]

查看 WKBWriter.outdim 。

trim[source]

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

>>> 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[source]

此属性控制坐标的四舍五入精度；如果设置为 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 文档第 4.1.2 章。

配置

GEOS_LIBRARY_PATH

A string specifying the location of the GEOS C library. Typically, this setting is only used if the GEOS C library is in a non-standard location (e.g., /home/bob/lib/libgeos_c.so).

Note

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

异常

exception GEOSException[source]

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