什么是 GEOS？¶

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

特性¶

GeoDjango 实现了一个 GEOS 库的高级 Python 包装器，其特性包括

• 一个 BSD 许可的 GEOS 几何例程接口，使用 ctypes 纯 Python 实现。

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

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

• 跨平台且经过测试；兼容 Windows、Linux、Solaris 和 macOS 平台。

创建几何图形¶

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

几何图形是 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))

>>> 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) – 空间参考标识符

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

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

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

>>> 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 对象可以通过传入表示多边形环的参数来实例化。这些参数必须是 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)[source]¶

根据给定的边界框返回一个多边形对象，边界框是一个包含 (xmin, ymin, xmax, ymax) 的 4 元组。

num_interior_rings[source]¶

返回此几何图形中内部环的数量。

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

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

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

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

读取器对象¶

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

写入器对象¶

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

class WKBWriter(dim=2)[source]¶

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

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

以十六进制形式返回几何图形的 WKB。示例

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

可以设置此属性以更改几何图形表示的输出维度。换句话说，如果您有 3D 几何图形，则将其设置为 3，以便 Z 值包含在 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]¶

使用布尔值设置此属性以指示是否应将几何图形的 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)[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)'

脚注

GEOS_LIBRARY_PATH¶

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