GEOS API — Django 文档

来自菜鸟教程
Django/docs/2.2.x/ref/contrib/gis/geos
跳转至:导航、​搜索

地理信息系统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'))

几何是 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_inputsrid 参数提供不同的 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
返回几何尺寸:
GEOSGeometry.empty
返回几何中的点集是否为空。
GEOSGeometry.geom_type

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

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

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

几何学

ID

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 对象如果与自身相交就不是简单的。 因此, LinearRingPolygon 对象总是很简单的,因为根据定义,它们确实不能相交。
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:{TF*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)

2.1 版中的新功能。

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)

给定距离(浮点数),返回该距离处几何图形(LineStringMultiLineString)内的点(或最近点)。 标准化版本将距离作为 0(原点)和 1(终点)之间的浮点数。

GEOSGeometry.project() 的反转。

GEOSGeometry.intersection(other)
返回一个 GEOSGeometry,代表这个几何体和其他几何体共享的点。
GEOSGeometry.project(point)
GEOSGeometry.project_normalized(point)

返回从几何原点(LineStringMultiLineString)到投影在几何上的点(即到最接近给定的线的点)的距离(浮点数)观点)。 标准化版本以 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

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

结果遵守以下约定:


其他属性和方法

GEOSGeometry.area
此属性返回几何的面积。
GEOSGeometry.extent
此属性返回此几何图形的范围作为 4 元组,由 (xmin, ymin, xmax, ymax) 组成。
GEOSGeometry.clone()
此方法返回一个 GEOSGeometry,它是原始的克隆。
GEOSGeometry.distance(geom)

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

笔记

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

GEOSGeometry.length
返回此几何的长度(例如,0 表示 PointLineString 的长度或 Polygon 的周长)。
GEOSGeometry.prepared
返回此几何内容的 GEOS PreparedGeometryPreparedGeometry 对象针对包含、相交、覆盖、交叉、不相交、重叠、触摸和内部操作进行了优化。 有关详细信息,请参阅 准备的几何图形 文档。
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))


准备好的几何图形

为了获得准备好的几何图形,只需访问 GEEOSGeometry.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.outdimtrimprecision 属性。

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 相关的错误。