什么是 GEOS？¶

GEOS 代表几何引擎 - 开源，是一个 C++ 库，移植自 Java 拓扑套件。GEOS 实现了 OpenGIS SQL 简单要素 空间谓词函数和空间运算符。GEOS 现在是 OSGeo 项目，最初由加拿大维多利亚的 Refractions Research 开发和维护。

功能¶

GeoDjango 为 GEOS 库实现了高级 Python 封装，其功能包括

• 使用 ctypes 纯 Python 实现的、面向 GEOS 几何例程的 BSD 许可接口。
• 与 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)¶

参数	geo_input – 几何输入值（字符串或 memoryview） srid (int) – 空间参考标识符

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

如果给出了 srid 参数，则将其设置为创建的几何的 SRID（如果 geo_input 没有 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)¶

使用表示点分量坐标的参数或使用单个序列坐标实例化 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 对象完全相同，但坐标必须是闭合的，换句话说，第一个坐标必须与最后一个坐标相同。例如

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

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

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

MultiPolygon¶

类 多边形(*参数, **关键字参数)¶

多边形对象可以通过传递 多边形 对象作为参数，或 多边形 对象的单个序列来实例化

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

几何集合¶

类 几何集合(*参数, **关键字参数)¶

几何集合对象可以通过传递其他 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¶

PreparedGeometry 上的所有方法都采用 other 参数，该参数必须是 GEOSGeometry 实例。

contains(other)¶

contains_properly(other)¶

covers(other)¶

crosses(other)¶

disjoint(other)¶

intersects(other)¶

overlaps(other)¶

touches(other)¶

within(other)¶

读取器对象¶

读取器 I/O 类从 WKB 和/或 WKT 输入返回一个 GEOSGeometry 实例，该输入提供给其 read(geom) 方法。

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>

写入器对象¶

所有 writer 对象都具有 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	大端序（例如，与 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¶

此属性可设置为更改几何表示的输出维度。换句话说，如果你有一个 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¶

使用布尔值设置此属性以指示几何的 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）时才使用此设置。