GEOS API

Background

What is GEOS?

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

Features

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

  • 一个BSD许可的接口到GEOS几何例程，纯粹使用ctypes在Python中实现。
  • 松散耦合到GeoDjango。例如，GEOSGeometry对象可以在Django项目/应用程序之外使用。换句话说，无需设置DJANGO_SETTINGS_MODULE或使用数据库等。
  • 可变性：GEOSGeometry对象可以修改。
  • 跨平台和测试；兼容Windows，Linux，Solaris和Mac OS X平台。

Tutorial

本节包含使用GEOSGeometry对象的简要介绍和教程。

Creating a Geometry

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)

最后，有fromstr()和fromfile()工厂方法，它从输入字符串或文件返回一个GEOSGeometry

>>> from django.contrib.gis.geos import fromstr, fromfile
>>> pnt = fromstr('POINT(5 23)')
>>> pnt = fromfile('/path/to/pnt.wkt')
>>> pnt = fromfile(open('/path/to/pnt.wkt'))

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

Geometry Objects

GEOSGeometry

class GEOSGeometry(geo_input[, srid=None])
参数：
  • geo_input - 几何输入值（字符串或缓冲区）
  • srid（int） - 空间参考标识符

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

接受以下输入格式及其对应的Python类型：

格式输入类型
WKT / EWKTstr或unicode
HEX / HEXEWKBstr或unicode
WKB / EWKBbuffer
GeoJSONstr或unicode

注意

具有中间Z或M的新3D / 4D WKT符号（例如POINT Z （3， / t4> 5））仅支持使用GEOS 3.3.0或更高版本。

Properties

GEOSGeometry.coords

返回几何的坐标作为元组。

GEOSGeometry.empty

返回几何中的点集是否为空。

GEOSGeometry.geom_type

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

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

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

几何ID
Point0
LineString1
LinearRing2
Polygon3
MultiPoint4
MultiLineString5
MultiPolygon6
GeometryCollection7
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

Output Properties

此部分中的属性将GEOSGeometry对象导出为不同的对象。此输出可以是字符串，缓冲区或甚至另一个对象的形式。

GEOSGeometry.ewkt

返回几何的“扩展”已知文本。这种表示特定于PostGIS，是OGC WKT标准的超集。[1]实质上，SRID是在WKT表示之前的，例如SRID = 4326； POINT（5 23） t1>。

注意

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

GEOSGeometry.hex

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

GEOSGeometry.hexewkb

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

GEOSGeometry.json

返回几何的GeoJSON表示。

注意

需要GDAL。

GEOSGeometry.geojson

GEOSGeometry.json的别名。

GEOSGeometry.kml

返回几何的KML（锁孔标记语言）表示。这应该只适用于SRID为4326（WGS84）的几何，但不强制此限制。

GEOSGeometry.ogr

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

注意

需要GDAL。

GEOSGeometry.wkb

将此几何的WKB（Well-Known Binary）表示形式作为Python缓冲区。不包括SRID值，请改用GEOSGeometry.ewkb属性。

GEOSGeometry.ewkb

将此几何的EWKB表示形式作为Python缓冲区。这是WKB规范的扩展，包括作为此几何的一部分的任何SRID值。

GEOSGeometry.wkt

返回几何的已知文本（OGC标准）。

Spatial Predicate Methods

所有以下空间谓词方法都将另一个GEOSGeometry实例（other）作为参数，并返回布尔值。

GEOSGeometry.contains(other)

如果GEOSGeometry.within()为False，则返回True。

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） t4 >将比较等于一个单位的千分之一。

GEOSGeometry.intersects(other)

如果GEOSGeometry.disjoint()为False，则返回True。

GEOSGeometry.overlaps(other)

如果两个几何的DE-9IM交叉矩阵为T*T***T**（对于两个点或两个表面），则返回true 1*T***T**（两条曲线）。

GEOSGeometry.relate_pattern(other, pattern)

如果此几何的DE-9IM交叉矩阵中的元素与其他匹配给定的pattern - 字母表中的九个字符的字符串，则返回True：{T，F，*，0}。

GEOSGeometry.touches(other)

Returns True if the DE-9IM intersection matrix for the two geometries is FT*******, F**T***** or F***T****.

GEOSGeometry.within(other)

如果两个几何的DE-9IM交集矩阵为T*F**F***，则返回True。

Topological Methods

GEOSGeometry.buffer(width, quadsegs=8)

返回GEOSGeometry，表示与该几何的距离小于或等于给定width的所有点。可选的quadsegs关键字设置用于近似四分之一圆的分段数（默认值为8）。

GEOSGeometry.difference(other)

返回GEOSGeometry，表示构成此几何的点，而不构成其他点。

GEOSGeometry.interpolate(distance)
GEOSGeometry.interpolate_normalized(distance)

给定距离（float），返回几何中的点（或最近点）（LineString或MultiLineString）。归一化版本将距离作为0（原点）和1（端点）之间的浮点。

反转GEOSGeometry.project()。

GEOSGeometry：intersection（other）

返回GEOSGeometry，表示由此几何和其他共享的点。

GEOSGeometry.project(point)
GEOSGeometry.project_normalized(point)

Returns the distance (float) from the origin of the geometry (LineString or MultiLineString) to the point projected on the geometry (that is to a point of the line the closest to the given point). 标准化版本返回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，表示此几何中的所有点和其他点。

Topological Properties

GEOSGeometry.boundary

将边界返回为新分配的几何对象。

GEOSGeometry.centroid

返回表示几何的几何中心的Point对象。该点不能保证在几何体的内部。

GEOSGeometry.convex_hull

返回包含几何中所有点的最小的Polygon。

GEOSGeometry.envelope

返回表示此几何的边界包络的Polygon。请注意，如果输入几何是点，它也可以返回Point。

GEOSGeometry.point_on_surface

计算并返回Point保证位于此几何体的内部。

Other Properties & Methods

GEOSGeometry.area

此属性返回几何的面积。

GEOSGeometry.extent

这个属性返回这个几何的范围作为一个4元组，由（xmin， ymin， xmax， ymax）。

GEOSGeometry.clone()

此方法返回一个GEOSGeometry，它是原始的克隆。

GEOSGeometry.distance(geom)

返回此几何图形上最接近的点与给定geom（另一个GEOSGeometry对象）之间的距离。

注意

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

GEOSGeometry.length

返回此几何的长度（例如，对于Point为0，LineString的长度或Polygon的圆周）。

GEOSGeometry.prepared

返回此几何的内容的GEOS PreparedGeometry。PreparedGeometry对象针对包含，相交，覆盖，交叉，不相交，重叠，触摸和在操作中进行了优化。有关详细信息，请参阅Prepared Geometries文档。

GEOSGeometry.srs

返回与几何的SRID或None对应的SpatialReference对象。

注意

需要GDAL。

GEOSGeometry.transform(ct, clone=False)

根据给定的坐标变换参数（ct）变换几何，其可以是整数SRID，空间参考WKT字符串，PROJ.4字符串，SpatialReference或CoordTransform对象。默认情况下，几何将原位转换，不返回任何内容。但是，如果设置了clone关键字，则不会修改几何，而是返回几何的转换克隆。

注意

需要GDAL。如果GDAL不可用或如果SRID为None或小于0，则提升GEOSException。

Point

class Point(x, y, z=None, srid=None)

Point对象使用表示点的组件坐标或使用单个序列坐标的参数进行实例化。例如，以下是等效的：

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

LineString

class LineString(*args, **kwargs)

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

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

num_interior_rings

返回此几何中的内环数。

比较多边形

注意，可以直接将Polygon对象与<或>进行比较，但是通过Polygon的LineString，这并不意味着太多（但是一致和快速）。您随时可以使用area属性强制比较：

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

Geometry Collections

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中所有组件的线合并。

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

返回Polygon，它是此集合中所有组件面的联合。所使用的算法显着地比单独地将几何结合在一起更有效（更快）。[2]

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

Prepared Geometries

要获取准备好的几何图形，只需访问GEOSGeometry.prepared属性。一旦您拥有PreparedGeometry实例，其空间谓词方法（如下所列）可与其他GEOSGeometry对象一起使用。具有准备好的几何的操作可以快几个数量级 - 准备的几何越复杂，操作中的加速越大。有关详细信息，请参阅准备好的几何体上的GEOS wiki页面。

例如：

>>> 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)
Django 1.7中的新功能。

注意

要使用此谓词，需要必需。

disjoint(other)
Django 1.7中的新功能。

注意

要使用此谓词，需要必需。

intersects(other)
overlaps(other)
Django 1.7中的新功能。

注意

要使用此谓词，需要必需。

touches(other)
Django 1.7中的新功能。

注意

要使用此谓词，需要必需。

within(other)
Django 1.7中的新功能。

注意

要使用此谓词，需要必需。

Geometry Factories

fromfile(file_h)
参数：file_h（Python file对象或文件的字符串路径） - 包含空间数据的输入文件
返回类型：a GEOSGeometry对应于文件中的空间数据

例：

>>> from django.contrib.gis.geos import fromfile
>>> g = fromfile('/home/bob/geom.wkt')
fromstr(string[, srid=None])
参数：
  • string（string） - 包含空间数据的字符串
  • srid（int） - 空间参考标识符
返回类型：

a GEOSGeometry对应于字符串中的空间数据

例：

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

I/O Objects

Reader Objects

读取器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>

Writer Objects

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

class WKBWriter

WKBWriter提供对其输出的最大控制。默认情况下，当调用write方法时，它返回符合OGC的WKB。但是，它具有允许创建EWKB的属性，EWKB是包括附加信息的WKB标准的超集。

WKBWriter.write(geom)

以Python buffer对象的形式返回给定几何的WKB。例：

>>> 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>
WKBWriter.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'
WKBWriter.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'
WKBWriter.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'
WKBWriter.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
WKTWriter.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)'

脚注

[1]请参阅 PostGIS EWKB，EWKT和规范表单，PostGIS文档。4.1.2.
[2]有关详细信息，请参阅Paul Ramsey的博客文章：PostgIS 1.4中的（Much）Faster Unions和Martin Davis在使用Cascaded Union在JTS中快速合并多边形的博客。

Settings

GEOS_LIBRARY_PATH

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

注意

The setting must be the full path to the C shared library; in other words you want to use libgeos_c.so, not libgeos.so.

Exceptions

exception GEOSException

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