GEOS APILink to this heading#

什么是 GEOS?Link to this heading#

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.

特性Link to this heading#

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 对象可以被修改。

• 跨平台测试。

创建几何对象Link to this heading#

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

几何对象是符合 Python 风格的Link to this heading#

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

GEOSGeometryLink to this heading#

class GEOSGeometry(geo_input, srid=None, *, max_geom_collections=198)Link to this definition#

参数:

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

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

• max_geom_collections -- maximum number of nested (WKT) or total (WKB) geometry collections accepted before parsing is refused

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 类型被接受：

对于 GeoJSON 格式，SRID 是根据 crs 成员设置的。如果没有提供 crs，SRID 默认为 4326。

classmethod GEOSGeometry.from_gml(gml_string)Link to this definition#

从给定的 GML 字符串构造一个 GEOSGeometry。

PointLink to this heading#

class Point(x=None, y=None, z=None, srid=None)Link to this definition#

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

Python console

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

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

Python console

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

LineStringLink to this heading#

class LineString(*args, **kwargs)Link to this definition#

可以使用坐标序列或 Point 对象作为参数来实例化 LineString 对象。例如，以下方式是等效的：

Python console

>>> ls = LineString((0, 0), (1, 1))
>>> ls = LineString(Point(0, 0), Point(1, 1))

此外，还可以通过传递单个坐标序列或 Point 对象的序列来创建 LineString 对象：

Python console

>>> ls = LineString(((0, 0), (1, 1)))
>>> ls = LineString([Point(0, 0), Point(1, 1)])

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

Python console

>>> ls = LineString()
>>> ls = LineString([])

closedLink to this definition#

返回此 LineString 是否闭合。

LinearRingLink to this heading#

class LinearRing(*args, **kwargs)Link to this definition#

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

Python console

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

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

is_counterclockwiseLink to this definition#

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

PolygonLink to this heading#

class Polygon(*args, **kwargs)Link to this definition#

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:

Python console

>>> 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)Link to this definition#

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

num_interior_ringsLink to this definition#

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

MultiPointLink to this heading#

class MultiPoint(*args, **kwargs)Link to this definition#

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

Python console

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

MultiLineStringLink to this heading#

class MultiLineString(*args, **kwargs)Link to this definition#

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

Python console

>>> ls1 = LineString((0, 0), (1, 1))
>>> ls2 = LineString((2, 2), (3, 3))
>>> mls = MultiLineString(ls1, ls2)
>>> mls = MultiLineString([ls1, ls2])

mergedLink to this definition#

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

closedLink to this definition#

只有当所有元素都闭合时返回 True。

MultiPolygonLink to this heading#

class MultiPolygon(*args, **kwargs)Link to this definition#

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

Python console

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

GeometryCollectionLink to this heading#

class GeometryCollection(*args, **kwargs)Link to this definition#

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

Python console

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

PreparedGeometryLink to this heading#

class PreparedGeometryLink to this definition#

PreparedGeometry 上的所有方法都接受一个 other 参数，该参数必须是一个 GEOSGeometry 实例。

contains(other)Link to this definition#

contains_properly(other)Link to this definition#

covers(other)Link to this definition#

crosses(other)Link to this definition#

disjoint(other)Link to this definition#

intersects(other)Link to this definition#

overlaps(other)Link to this definition#

touches(other)Link to this definition#

within(other)Link to this definition#

读取器对象Link to this heading#

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

class WKBReaderLink to this definition#

例如：

Python console

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

class WKTReaderLink to this definition#

例如：

Python console

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

写入器对象Link to this heading#

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)Link to this definition#

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)Link to this definition#

将给定几何对象的 WKB 返回为 Python 的 buffer 对象。示例：

Python console

>>> 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)Link to this definition#

Returns WKB of the geometry in hexadecimal. Example:

Python console

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

byteorderLink to this definition#

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

字节顺序值	描述
0	大端字节序（例如，与 RISC 系统兼容）
1	小端字节序（例如，与 x86 系统兼容）

例如：

Python console

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

outdimLink to this definition#

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。

例如：

Python console

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

sridLink to this definition#

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

Python console

>>> 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)Link to this definition#

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

write(geom)Link to this definition#

返回给定几何对象的 WKT。示例：

Python console

>>> from django.contrib.gis.geos import Point, WKTWriter
>>> pnt = Point(1, 1)
>>> wkt_w = WKTWriter()
>>> wkt_w.write(pnt)
'POINT (1.0000000000000000 1.0000000000000000)'

outdimLink to this definition#

查看 WKBWriter.outdim 。

trimLink to this definition#

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

Python console

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

precisionLink to this definition#

此属性控制坐标的四舍五入精度；如果设置为 None，则禁用四舍五入。

Code

>>> 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_PATHLink to this heading#

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