---
title: "GEOS API"
version: 6.0
locale: zh-hans
source: https://docs.djangoproject.com/zh-hans/6.0/ref/contrib/gis/geos/
canonical: https://djangodocs.dev/zh-hans/6.0/ref/contrib/gis/geos/
---
# GEOS API

## 背景

### 什么是 GEOS?

[GEOS](https://libgeos.org/) stands for **Geometry Engine - Open Source**,
and is a C++ library, ported from the  [Java Topology Suite](https://sourceforge.net/projects/jts-topo-suite/). GEOS
implements the OpenGIS [Simple Features for SQL](https://www.ogc.org/standard/sfs/) spatial predicate functions
and spatial operators. GEOS, now an OSGeo project, was initially developed and
maintained by [Refractions Research](http://www.refractions.net/) of Victoria, Canada.

### 特性

GeoDjango 实现了一个高级的 Python 封装，用于 GEOS 库，其特点包括：

- 一个使用 `ctypes` 纯粹在 Python 中实现的，对 GEOS 几何例程提供的 BSD 许可接口。
- Loosely-coupled to GeoDjango. For example, [`GEOSGeometry`](#django.contrib.gis.geos.GEOSGeometry) objects
  may be used outside of a Django project/application. In other words,
  no need to have [`DJANGO_SETTINGS_MODULE`](/zh-hans/6.0/topics/settings/#envvar-DJANGO_SETTINGS_MODULE) set or use a database, etc.
- 可变性：[`GEOSGeometry`](#django.contrib.gis.geos.GEOSGeometry) 对象可以被修改。
- 跨平台测试。

## 教程

这个部分包含了使用 [`GEOSGeometry`](#django.contrib.gis.geos.GEOSGeometry) 对象的简要介绍和教程。

### 创建几何对象

[`GEOSGeometry`](#django.contrib.gis.geos.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:

```pycon
>>> 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`](#django.contrib.gis.geos.Point) object may be
created by passing in the X and Y coordinates into its constructor:

```pycon
>>> from django.contrib.gis.geos import Point
>>> pnt = Point(5, 23)
```

所有这些构造函数都接受关键字参数 `srid`。例如：

```pycon
>>> 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()`](#django.contrib.gis.geos.fromfile) 工厂方法，它可以从文件返回一个 [`GEOSGeometry`](#django.contrib.gis.geos.GEOSGeometry) 对象：

```pycon
>>> from django.contrib.gis.geos import fromfile
>>> pnt = fromfile("/path/to/pnt.wkt")
>>> pnt = fromfile(open("/path/to/pnt.wkt"))
```

> **我的日志中充满了与 GEOS 相关的错误。**
>
> 你在 Web 服务器的日志文件中发现了许多 `TypeError` 或 `AttributeError` 异常。这通常意味着你在一些 Python 模块的顶层创建了 GEOS 对象。然后，由于垃圾收集器中的竞态条件，你的模块在 GEOS 对象之前被垃圾回收。为了防止这种情况发生，请在你的函数/方法的局部范围内创建 [`GEOSGeometry`](#django.contrib.gis.geos.GEOSGeometry) 对象。

### 几何对象是符合 Python 风格的

[`GEOSGeometry`](#django.contrib.gis.geos.GEOSGeometry) 对象是 'Pythonic' 的，换句话说，可以使用标准的 Python 惯例访问、修改和迭代其组件。例如，你可以迭代 [`Point`](#django.contrib.gis.geos.Point) 中的坐标：

```pycon
>>> pnt = Point(5, 23)
>>> [coord for coord in pnt]
[5.0, 23.0]
```

对于任何几何对象，可以使用 [`GEOSGeometry.coords`](#django.contrib.gis.geos.GEOSGeometry.coords) 属性将几何坐标作为 Python 元组获取：

```pycon
>>> 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`](#django.contrib.gis.geos.LineString)
returns a coordinate tuple:

```pycon
>>> 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`](#django.contrib.gis.geos.Polygon) 上进行索引将返回与索引对应的环（一个 [`LinearRing`](#django.contrib.gis.geos.LinearRing) 对象）：

```pycon
>>> 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 列表一样添加或修改：

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

几何对象支持类似集合的运算符：

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

> **等号运算符不检查空间相等性**
>
> [`GEOSGeometry`](#django.contrib.gis.geos.GEOSGeometry) 的等号运算符使用的是 [`equals_exact()`](#django.contrib.gis.geos.GEOSGeometry.equals_exact)，而不是 [`equals()`](#django.contrib.gis.geos.GEOSGeometry.equals)，也就是说，它要求比较的几何对象在相同的位置具有相同的坐标和相同的 SRID：
>
> ```pycon
> >>> 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, * (Keyword-only parameters separator (PEP 3102)), max_geom_collections=198)`

**参数:** - `geo_input` -- 几何输入值（字符串或 [`memoryview`](https://docs.python.org/3/library/stdtypes.html#memoryview)）
- `srid` ([`int`](https://docs.python.org/3/library/functions.html#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`](#django.contrib.gis.geos.Point) object).

如果提供了 `srid` 参数，并且 `geo_input` 没有 SRID，则将其设置为创建的几何对象的 SRID。如果通过 `geo_input` 和 `srid` 参数提供了不同的 SRID，则会引发 `ValueError`：

```pycon
>>> 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` |
| HEX / HEXEWKB | `str` |
| WKB / EWKB | `memoryview` |
| [**GeoJSON**](https://datatracker.ietf.org/doc/html/rfc7946.html) | `str` |

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

> **Changed in Django 5.2.17**
>
> The `max_geom_collections` parameter was added.

#### `classmethod GEOSGeometry.from_gml(gml_string)`

从给定的 GML 字符串构造一个 [`GEOSGeometry`](#django.contrib.gis.geos.GEOSGeometry)。

#### 属性

#### `GEOSGeometry.coords`

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

#### `GEOSGeometry.dims`

返回几何的维度：

- 对于 [`Point`](#django.contrib.gis.geos.Point) 和 [`MultiPoint`](#django.contrib.gis.geos.MultiPoint)，返回值为 `0`
- 对于 [`LineString`](#django.contrib.gis.geos.LineString) 和 [`MultiLineString`](#django.contrib.gis.geos.MultiLineString)，返回值为 `1`
- 对于 [`Polygon`](#django.contrib.gis.geos.Polygon) 和 [`MultiPolygon`](#django.contrib.gis.geos.MultiPolygon)，返回值为 `2`
- 对于空的 [`GeometryCollection`](#django.contrib.gis.geos.GeometryCollection)，返回值为 `-1`
- 对于非空的 [`GeometryCollection`](#django.contrib.gis.geos.GeometryCollection)，返回其元素的最大维度。

#### `GEOSGeometry.empty`

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

#### `GEOSGeometry.geom_type`

Returns a string corresponding to the type of geometry. For example:

```pycon
>>> pnt = GEOSGeometry("POINT(5 23)")
>>> pnt.geom_type
'Point'
```

#### `GEOSGeometry.geom_typeid`

Returns the GEOS geometry type identification number. The following table
shows the value for each geometry type:

| 几何 | ID |
| --- | --- |
| [`Point`](#django.contrib.gis.geos.Point) | 0 |
| [`LineString`](#django.contrib.gis.geos.LineString) | 1 |
| [`LinearRing`](#django.contrib.gis.geos.LinearRing) | 2 |
| [`Polygon`](#django.contrib.gis.geos.Polygon) | 3 |
| [`MultiPoint`](#django.contrib.gis.geos.MultiPoint) | 4 |
| [`MultiLineString`](#django.contrib.gis.geos.MultiLineString) | 5 |
| [`MultiPolygon`](#django.contrib.gis.geos.MultiPolygon) | 6 |
| [`GeometryCollection`](#django.contrib.gis.geos.GeometryCollection) | 7 |

#### `GEOSGeometry.num_coords`

返回几何中坐标的数量。

#### `GEOSGeometry.num_geom`

Returns the number of geometries in this geometry. In other words, will
return 1 on anything but geometry collections.

#### `GEOSGeometry.hasz`

Returns a boolean indicating whether the geometry has the Z dimension.

#### `GEOSGeometry.hasm`

> **New in Django 6.0**

Returns a boolean indicating whether the geometry has the M dimension.
Requires GEOS 3.12.

#### `GEOSGeometry.ring`

返回一个布尔值，指示几何是否是 `LinearRing`。

#### `GEOSGeometry.simple`

Returns a boolean indicating whether the geometry is 'simple'. A geometry
is simple if and only if it does not intersect itself (except at boundary
points). For example, a [`LineString`](#django.contrib.gis.geos.LineString) object is not simple if it
intersects itself. Thus, [`LinearRing`](#django.contrib.gis.geos.LinearRing) and [`Polygon`](#django.contrib.gis.geos.Polygon) objects
are always simple because they cannot intersect themselves, by definition.

#### `GEOSGeometry.valid`

返回一个布尔值，指示几何是否有效。

#### `GEOSGeometry.valid_reason`

返回一个描述几何无效的原因的字符串。

#### `GEOSGeometry.srid`

Property that may be used to retrieve or set the SRID associated with the
geometry. For example:

```pycon
>>> pnt = Point(5, 23)
>>> print(pnt.srid)
None
>>> pnt.srid = 4326
>>> pnt.srid
4326
```

#### 输出属性

The properties in this section export the [`GEOSGeometry`](#django.contrib.gis.geos.GEOSGeometry) object into
a different. This output may be in the form of a string, buffer, or even
another object.

#### `GEOSGeometry.ewkt`

Returns the "extended" Well-Known Text of the geometry. This representation
is specific to PostGIS and is a superset of the OGC WKT standard. [^1]
Essentially the SRID is prepended to the WKT representation, for example
`SRID=4326;POINT(5 23)`.

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

#### `GEOSGeometry.hex`

Returns the WKB of this Geometry in hexadecimal form. Please note
that the SRID value is not included in this representation
because it is not a part of the OGC specification (use the
[`GEOSGeometry.hexewkb`](#django.contrib.gis.geos.GEOSGeometry.hexewkb) property instead).

#### `GEOSGeometry.hexewkb`

Returns the EWKB of this Geometry in hexadecimal form. This is an
extension of the WKB specification that includes the SRID value
that are a part of this geometry.

#### `GEOSGeometry.json`

返回几何的 GeoJSON 表示。请注意，结果不是完整的 GeoJSON 结构，而只是 GeoJSON 结构中 `geometry` 键的内容。还请参阅 [GeoJSON 序列化器](/zh-hans/6.0/ref/contrib/gis/serializers/)。

#### `GEOSGeometry.geojson`

是 [`GEOSGeometry.json`](#django.contrib.gis.geos.GEOSGeometry.json) 的别名。

#### `GEOSGeometry.kml`

Returns a [KML](https://developers.google.com/kml/documentation/) (Keyhole Markup Language) representation of the
geometry. This should only be used for geometries with an SRID of
4326 (WGS84), but this restriction is not enforced.

#### `GEOSGeometry.ogr`

返回与 GEOS 几何对应的 [`OGRGeometry`](/zh-hans/6.0/ref/contrib/gis/gdal/#django.contrib.gis.gdal.OGRGeometry) 对象。

#### `GEOSGeometry.wkb`

Returns the WKB (Well-Known Binary) representation of this Geometry
as a Python buffer. SRID value is not included, use the
[`GEOSGeometry.ewkb`](#django.contrib.gis.geos.GEOSGeometry.ewkb) property instead.

#### `GEOSGeometry.ewkb`

以 Python 缓冲区的形式返回此几何的 EWKB 表示。这是 WKB 规范的扩展，包括与此几何对象相关的任何 SRID 值。

#### `GEOSGeometry.wkt`

返回几何的 Well-Known Text（OGC 标准）。

#### 空间谓词方法

以下所有的空间谓词方法都以另一个 [`GEOSGeometry`](#django.contrib.gis.geos.GEOSGeometry) 实例（`other`）作为参数，并返回一个布尔值。

#### `GEOSGeometry.contains(other)`

如果 [`other.within(this)`](#django.contrib.gis.geos.GEOSGeometry.within) 返回 `True`，则返回 `True`。

#### `GEOSGeometry.covers(other)`

如果此几何覆盖指定的几何，则返回 `True`。

`covers` 谓词具有以下等价定义：

- 其他几何的每个点都是此几何的点。
- 两个几何对象的 [DE-9IM](https://en.wikipedia.org/wiki/DE-9IM) 交集矩阵为 `T*****FF*`, `*T****FF*`, `***T**FF*`, 或 `****T*FF*`。

如果其中一个几何为空，则返回 `False`。

此谓词类似于 [`GEOSGeometry.contains()`](#django.contrib.gis.geos.GEOSGeometry.contains)，但更加包容性（即对更多情况返回 `True`）。特别地，与 [`contains()`](#django.contrib.gis.geos.GEOSGeometry.contains) 不同，它不区分边界和几何内部的点。在大多数情况下，应该首选使用 `covers()` 而不是 [`contains()`](#django.contrib.gis.geos.GEOSGeometry.contains)。作为额外的好处，`covers()` 更容易进行优化，因此应该优于 [`contains()`](#django.contrib.gis.geos.GEOSGeometry.contains)。

#### `GEOSGeometry.crosses(other)`

如果两个几何对象的 DE-9IM 交集矩阵为 `T*T******` （对于点和曲线、点和区域或线和区域）或 `0********` （对于两个曲线），则返回 `True`。

#### `GEOSGeometry.disjoint(other)`

如果两个几何对象的 DE-9IM 交集矩阵为 `FF*FF****`，则返回 `True`。

#### `GEOSGeometry.equals(other)`

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

#### `GEOSGeometry.equals_exact(other, tolerance=0)`

Returns true if the two geometries are exactly equal, up to a
specified tolerance. The `tolerance` value should be a floating
point number representing the error tolerance in the comparison, e.g.,
`poly1.equals_exact(poly2, 0.001)` will compare equality to within
one thousandth of a unit.

#### `GEOSGeometry.equals_identical(other)`

如果两个几何图形在所有维度中的结构、顺序和顶点的值都完全相同，返回 `True`。`NaN` 值被视为与其他 `NaN` 值相等。需要 GEOS 3.12。

#### `GEOSGeometry.intersects(other)`

如果 [`GEOSGeometry.disjoint()`](#django.contrib.gis.geos.GEOSGeometry.disjoint) 为 `False`，则返回 `True`。

#### `GEOSGeometry.overlaps(other)`

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

#### `GEOSGeometry.relate_pattern(other, pattern)`

如果此几何对象和其他几何对象的 DE-9IM 交集矩阵中的元素与给定的 `pattern` 匹配（一个由字母 {`T`, `F`, `*`, `0`} 组成的九个字符的字符串），则返回 `True`。

#### `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`](#django.contrib.gis.geos.GEOSGeometry)，表示距离此几何对象小于或等于给定的 `width` 的所有点。可选的 `quadsegs` 关键字设置用于近似一个四分之一圆的段数（默认值为 8）。

#### `GEOSGeometry.buffer_with_style(width, quadsegs=8, end_cap_style=1, join_style=1, mitre_limit=5.0)`

与 [`buffer()`](#django.contrib.gis.geos.GEOSGeometry.buffer) 相同，但允许自定义缓冲区的样式。

- `end_cap_style` 可以是 round（`1`）、flat（`2`）或 square（`3`）。
- `join_style` 可以是 round（`1`）、mitre（`2`）或 bevel（`3`）。
- Mitre ratio limit（`mitre_limit`）仅影响 mitred join style。

#### `GEOSGeometry.difference(other)`

返回一个表示构成此几何的点但不构成其他几何的 [`GEOSGeometry`](#django.contrib.gis.geos.GEOSGeometry)。

#### `GEOSGeometry.interpolate(distance)`

#### `GEOSGeometry.interpolate_normalized(distance)`

给定一个距离（浮点数），返回几何对象（[`LineString`](#django.contrib.gis.geos.LineString) 或 [`MultiLineString`](#django.contrib.gis.geos.MultiLineString)）中距离最近的点（或最近的点）。标准化版本将距离作为介于 0（起点）和 1（终点）之间的浮点数。

与 [`GEOSGeometry.project()`](#django.contrib.gis.geos.GEOSGeometry.project) 的相反操作。

#### `GEOSGeometry.intersection(other)`

返回一个表示此几何对象和其他几何对象共享的点的 [`GEOSGeometry`](#django.contrib.gis.geos.GEOSGeometry)。

#### `GEOSGeometry.project(point)`

#### `GEOSGeometry.project_normalized(point)`

返回从几何对象（[`LineString`](#django.contrib.gis.geos.LineString) 或 [`MultiLineString`](#django.contrib.gis.geos.MultiLineString)）的起点到在几何对象上投影的点（即距离给定点最近的线上的点）的距离（浮点数）。标准化版本将距离作为介于 0（起点）和 1（终点）之间的浮点数返回。

与 [`GEOSGeometry.interpolate()`](#django.contrib.gis.geos.GEOSGeometry.interpolate) 的相反操作。

#### `GEOSGeometry.relate(other)`

返回表示此几何对象与其他几何对象之间拓扑关系的 DE-9IM 交集矩阵（字符串）。

#### `GEOSGeometry.simplify(tolerance=0.0, preserve_topology=False)`

返回一个新的 [`GEOSGeometry`](#django.contrib.gis.geos.GEOSGeometry)，使用 Douglas-Peucker 算法简化到指定的容差。较高的容差值意味着输出中的点较少。如果没有提供容差，则默认为 0。

默认情况下，此函数不保持拓扑关系。例如，[`Polygon`](#django.contrib.gis.geos.Polygon) 对象可以被分割，折叠成线，或消失。[`Polygon`](#django.contrib.gis.geos.Polygon) 的孔可以被创建或消失，线可能会相交。通过指定 `preserve_topology=True`，结果将具有与输入相同的维度和组件数量；然而，这会显著减慢处理速度。

#### `GEOSGeometry.sym_difference(other)`

返回一个 [`GEOSGeometry`](#django.contrib.gis.geos.GEOSGeometry)，其中包含此几何对象中不在其他几何中的点以及其他几何中不在此几何中的点。

#### `GEOSGeometry.union(other)`

返回一个 [`GEOSGeometry`](#django.contrib.gis.geos.GEOSGeometry)，表示此几何对象和其他几何对象中的所有点。

#### 拓扑属性

#### `GEOSGeometry.boundary`

返回边界作为一个新分配的几何对象。

#### `GEOSGeometry.centroid`

Returns a [`Point`](#django.contrib.gis.geos.Point) object representing the geometric center of
the geometry. The point is not guaranteed to be on the interior
of the geometry.

#### `GEOSGeometry.convex_hull`

返回包含几何中所有点的最小 [`Polygon`](#django.contrib.gis.geos.Polygon)。

#### `GEOSGeometry.envelope`

返回一个表示此几何的边界包围框的 [`Polygon`](#django.contrib.gis.geos.Polygon)。请注意，如果输入几何对象是一个点，它也可以返回一个 [`Point`](#django.contrib.gis.geos.Point)。

#### `GEOSGeometry.point_on_surface`

计算并返回一个保证位于此几何对象内部的 [`Point`](#django.contrib.gis.geos.Point)。

#### `GEOSGeometry.unary_union`

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

结果遵循以下约定：

- 对一组 [`LineString`](#django.contrib.gis.geos.LineString) 进行并集操作将完全节点化和融合线段。
- 对一组 [`Polygon`](#django.contrib.gis.geos.Polygon) 进行并集操作将始终返回一个 [`Polygon`](#django.contrib.gis.geos.Polygon) 或 [`MultiPolygon`](#django.contrib.gis.geos.MultiPolygon) 几何对象（与 [`GEOSGeometry.union()`](#django.contrib.gis.geos.GEOSGeometry.union) 不同，如果拓扑崩溃发生，可能返回较低维度的几何对象）。

#### 其他属性和方法

#### `GEOSGeometry.area`

此属性返回几何对象的面积。

#### `GEOSGeometry.extent`

此属性返回几何对象的范围，以 4 元组形式表示，包括 `(xmin, ymin, xmax, ymax)`。

#### `GEOSGeometry.clone()`

此方法返回原始几何对象的克隆 [`GEOSGeometry`](#django.contrib.gis.geos.GEOSGeometry)。

#### `GEOSGeometry.distance(geom)`

返回此几何对象与给定的 `geom` （另一个 [`GEOSGeometry`](#django.contrib.gis.geos.GEOSGeometry) 对象）之间的最近点之间的距离。

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

#### `GEOSGeometry.length`

返回此几何对象的长度（例如，对于 [`Point`](#django.contrib.gis.geos.Point)，长度为 0，对于 [`LineString`](#django.contrib.gis.geos.LineString)，长度为线段的长度，对于 [`Polygon`](#django.contrib.gis.geos.Polygon)，长度为多边形的周长）。

#### `GEOSGeometry.prepared`

返回此几何对象内容的 GEOS `PreparedGeometry`。`PreparedGeometry` 对象针对 contains、intersects、covers、crosses、disjoint、overlaps、touches 和 within 操作进行了优化。有关更多信息，请参阅 [准备好的几何对象](#prepared-geometries) 文档。

#### `GEOSGeometry.srs`

返回与几何对象的 SRID 对应的 [`SpatialReference`](/zh-hans/6.0/ref/contrib/gis/gdal/#django.contrib.gis.gdal.SpatialReference) 对象，如果没有则返回 `None`。

#### `GEOSGeometry.transform(ct, clone=False)`

根据给定的坐标转换参数（`ct`）来转换几何对象，参数可以是整数 SRID、空间参考 WKT 字符串、PROJ 字符串、[`SpatialReference`](/zh-hans/6.0/ref/contrib/gis/gdal/#django.contrib.gis.gdal.SpatialReference) 对象或 [`CoordTransform`](/zh-hans/6.0/ref/contrib/gis/gdal/#django.contrib.gis.gdal.CoordTransform) 对象。默认情况下，几何对象会原地转换，不返回任何内容。但是如果设置了 `clone` 关键字参数，则不会修改几何对象，而是返回一个经过转换的几何对象的克隆。

> **Note**
>
> 如果没有安装 GDAL，或者几何对象的 SRID 为 `None` 或小于 0，则会引发 [`GEOSException`](#django.contrib.gis.geos.GEOSException)。如果使用 [`CoordTransform`](/zh-hans/6.0/ref/contrib/gis/gdal/#django.contrib.gis.gdal.CoordTransform) 对象调用，则不会对几何对象的 SRID 强加任何约束。

#### `GEOSGeometry.make_valid()`

返回一个有效的 [`GEOSGeometry`](#django.contrib.gis.geos.GEOSGeometry) 等效对象，尽量不丢失输入的顶点。如果几何对象已经有效，则原样返回。这类似于数据库函数 [`MakeValid`](/zh-hans/6.0/ref/contrib/gis/functions/#django.contrib.gis.db.models.functions.MakeValid)。需要 GEOS 3.8。

#### `GEOSGeometry.normalize(clone=False)`

将此几何对象转换为规范形式。如果设置了 `clone` 关键字参数，则不会修改几何对象，而是返回一个规范化的几何对象的克隆：

```pycon
>>> 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` 对象。例如，以下方式是等效的：

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

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

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

### `LineString`

#### `class LineString(*args, **kwargs)`

可以使用坐标序列或 [`Point`](#django.contrib.gis.geos.Point) 对象作为参数来实例化 `LineString` 对象。例如，以下方式是等效的：

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

此外，还可以通过传递单个坐标序列或 [`Point`](#django.contrib.gis.geos.Point) 对象的序列来创建 `LineString` 对象：

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

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

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

#### `closed`

返回此 `LineString` 是否闭合。

### `LinearRing`

#### `class LinearRing(*args, **kwargs)`

`LinearRing` 对象的构造方式与 [`LineString`](#django.contrib.gis.geos.LineString) 对象完全相同，但坐标必须是 *闭合* 的，也就是说，第一个坐标必须与最后一个坐标相同。例如：

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

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

#### `is_counterclockwise`

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

### `Polygon`

#### `class Polygon(*args, **kwargs)`

`Polygon` objects may be instantiated by passing in parameters that
represent the rings of the polygon. The parameters must either be
[`LinearRing`](#django.contrib.gis.geos.LinearRing) instances, or a sequence that may be used to construct
a [`LinearRing`](#django.contrib.gis.geos.LinearRing):

```pycon
>>> 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` 对象，但由于比较是通过多边形的 [`LineString`](#django.contrib.gis.geos.LineString) 进行的，所以意义不大（但是一致且快速）。您始终可以使用 [`area`](#django.contrib.gis.geos.GEOSGeometry.area) 属性强制进行比较：
>
> ```pycon
> >>> if poly_1.area > poly_2.area:
> ...     pass
> ...
> ```

## 几何集合

### `MultiPoint`

#### `class MultiPoint(*args, **kwargs)`

`MultiPoint` 对象可以通过传入 [`Point`](#django.contrib.gis.geos.Point) 对象作为参数，或者传入包含 [`Point`](#django.contrib.gis.geos.Point) 对象的单个序列来实例化：

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

### `MultiLineString`

#### `class MultiLineString(*args, **kwargs)`

`MultiLineString` 对象可以通过传入 [`LineString`](#django.contrib.gis.geos.LineString) 对象作为参数，或者传入包含 [`LineString`](#django.contrib.gis.geos.LineString) 对象的单个序列来实例化：

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

#### `merged`

返回一个代表此 `MultiLineString` 中所有组件线合并的 [`LineString`](#django.contrib.gis.geos.LineString)。

#### `closed`

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

### `MultiPolygon`

#### `class MultiPolygon(*args, **kwargs)`

`MultiPolygon` 对象可以通过传入 [`Polygon`](#django.contrib.gis.geos.Polygon) 对象作为参数，或者传入包含 [`Polygon`](#django.contrib.gis.geos.Polygon) 对象的单个序列来实例化：

```pycon
>>> 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`](#django.contrib.gis.geos.GEOSGeometry) 作为参数，或者传入包含 [`GEOSGeometry`](#django.contrib.gis.geos.GEOSGeometry) 对象的单个序列来实例化：

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

## 准备好的几何对象

In order to obtain a prepared geometry, access the
[`GEOSGeometry.prepared`](#django.contrib.gis.geos.GEOSGeometry.prepared) property. Once you have a `PreparedGeometry`
instance its spatial predicate methods, listed below, may be used with other
`GEOSGeometry` objects. An operation with a prepared geometry can be orders
of magnitude faster -- the more complex the geometry that is prepared, the
larger the speedup in the operation. For more information, please consult the
[GEOS wiki page on prepared geometries](https://trac.osgeo.org/geos/wiki/PreparedGeometry).

例如：

```pycon
>>> 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`](#django.contrib.gis.geos.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` (a Python `file` object or a string path to the file) -- 包含空间数据的输入文件

**返回类型:** 一个对应于文件中空间数据的 [`GEOSGeometry`](#django.contrib.gis.geos.GEOSGeometry)

例如：

```pycon
>>> from django.contrib.gis.geos import fromfile
>>> g = fromfile("/home/bob/geom.wkt")
```

#### `fromstr(string, srid=None)`

**参数:** - `string` ([`str`](https://docs.python.org/3/library/stdtypes.html#str)) -- 包含空间数据的字符串
- `srid` ([`int`](https://docs.python.org/3/library/functions.html#int)) -- 空间参考标识符（SRID）

**返回类型:** 一个对应于字符串中空间数据的 [`GEOSGeometry`](#django.contrib.gis.geos.GEOSGeometry)

`fromstr(string, srid)` 等价于 [`GEOSGeometry(string, srid)`](#django.contrib.gis.geos.GEOSGeometry)。

例如：

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

## I/O 对象

### 读取器对象

读取器 I/O 类从给定给它们的 WKB 和/或 WKT 输入中的 `read(geom)` 方法返回一个 [`GEOSGeometry`](#django.contrib.gis.geos.GEOSGeometry) 实例。

#### `class WKBReader`

例如：

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

#### `class WKTReader`

例如：

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

### 写入器对象

All writer objects have a `write(geom)` method that returns either the
WKB or WKT of the given geometry. In addition, [`WKBWriter`](#django.contrib.gis.geos.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)`

`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`](#django.contrib.gis.geos.WKBWriter.outdim) documentation for more details about the `dim`
argument.

#### `write(geom)`

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

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

Returns WKB of the geometry in hexadecimal. Example:

```pycon
>>> 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 系统兼容） |

例如：

```pycon
>>> 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`

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

例如：

```pycon
>>> 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`

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

```pycon
>>> 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`](#django.contrib.gis.geos.WKBWriter.outdim)、[`trim`](#django.contrib.gis.geos.WKTWriter.trim) 和 [`precision`](#django.contrib.gis.geos.WKTWriter.precision) 属性。

#### `write(geom)`

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

```pycon
>>> 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`](#django.contrib.gis.geos.WKBWriter.outdim) 。

#### `trim`

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

```pycon
>>> 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 和规范形式](https://postgis.net/docs/using_postgis_dbmanagement.html#EWKB_EWKT)，PostGIS 文档第 4.1.2 章。

## 配置

### `GEOS_LIBRARY_PATH`

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

> **Note**
>
> 这个配置必须是 **C** 共享库的 *完整* 路径；换句话说，你要使用 `libgeos_c.so`，而不是 `libgeos.so`。

## 异常

#### `exception GEOSException`

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