地理数据库函数¶

本页所描述的函数允许用户访问地理数据库函数，以便在 Django 中使用注释、聚合或过滤器。

例如：

>>> from django.contrib.gis.db.models.functions import Length
>>> Track.objects.annotate(length=Length("line")).filter(length__gt=100)

并非所有的后端都支持所有的函数，所以请参考每个函数的文档，看看你的数据库后端是否支持你要使用的函数。如果你在一个不支持地理函数的后台调用该函数，你会得到一个 NotImplementedError 异常。

Measurements¶

`Area`¶

class Area(expression, **extra)[source]¶

Availability: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

接受单个地理字段或表达式，并将字段的面积作为一个 Area 测量返回。

在没有 LWGEOM/RTTOPO 支持的情况下，MySQL 和 SpatiaLite 不支持对地理 SRS（空间参考系统）进行面积计算。

`Distance`¶

class Distance(expr1, expr2, spheroid=None, **extra)[source]¶

可用性: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

接受两个地理字段或表达式，并返回它们之间的距离，作为一个 Distance 对象。在 MySQL 上，当坐标是大地测量时，会返回原始的浮点值。

在支持大地测量坐标距离计算的后端上，根据几何形状的 SRID 值，会自动选择合适的后端函数（例如，在 PostGIS 上使用 ST_DistanceSphere）。

当使用大地测量（角度）坐标计算距离时，例如默认的 WGS84 (4326) SRID，您可以设置 spheroid 关键字参数来决定计算是基于简单球体（精度较低，资源消耗较少）还是基于椭球体（精度较高，资源消耗较多）。

在以下示例中，计算了从霍巴特市到 AustraliaCity 查询集中的每个其他 PointField 的距离：

>>> from django.contrib.gis.db.models.functions import Distance
>>> pnt = AustraliaCity.objects.get(name="Hobart").point
>>> for city in AustraliaCity.objects.annotate(distance=Distance("point", pnt)):
...     print(city.name, city.distance)
...
Wollongong 990071.220408 m
Shellharbour 972804.613941 m
Thirroul 1002334.36351 m
...

Note

Because the distance attribute is a Distance object, you can easily express the value in the units of your choice. For example, city.distance.mi is the distance value in miles and city.distance.km is the distance value in kilometers. See 测量对象 for usage details and the list of 支持的单位.

`GeometryDistance`¶

class GeometryDistance(expr1, expr2, **extra)[source]¶

可用性: PostGIS

接受两个地理字段或表达式，并返回它们之间的距离。当在 order_by() 子句中使用时，它提供了辅助索引的最近邻结果集。

`Length`¶

class Length(expression, spheroid=True, **extra)[source]¶

可用性: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

接受单个地理线串或多线串字段或表达式，并将其长度返回为 Distance 测量。

在 PostGIS 和 SpatiaLite 上，当坐标是大地测量（角度）时，您可以使用 spheroid 关键字参数来指定计算是基于简单球体（精度较低，资源消耗较少）还是基于椭球体（精度较高，资源消耗较多）。

MySQL 不支持在地理 SRS 上进行长度计算。

`Perimeter`¶

class Perimeter(expression, **extra)[source]¶

可用性: PostGIS, Oracle, SpatiaLite

接受单个地理字段或表达式，并将几何字段的周长返回为 Distance 对象。

关系映射¶

`Azimuth`¶

class Azimuth(point_a, point_b, **extra)[source]¶

可用性：PostGIS, SpatiaLite (LWGEOM/RTTOPO)

返回由给定点几何形状定义的线段的方位角（以弧度表示），如果两个点重合，则返回 None。方位角是以北方为参考的角度，顺时针方向为正：north = 0; east = π/2; south = π; west = 3π/2。

`BoundingCircle`¶

class BoundingCircle(expression, num_seg=48, **extra)[source]¶

可用性：PostGIS、Oracle、SpatiaLite 5.1+

接受单个地理字段或表达式，并返回可以完全包含几何形状的最小圆形多边形。

num_seg 参数仅在 PostGIS 中使用。

`Centroid`¶

class Centroid(expression, **extra)[source]¶

可用性：MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

接受单个地理字段或表达式，并返回几何形状的 centroid 值。

`ClosestPoint`¶

class ClosestPoint(expr1, expr2, **extra)[source]¶

可用性: PostGIS, SpatiaLite

接受两个地理字段或表达式，并返回在几何体 A 上最接近几何体 B 的二维点。

`Envelope`¶

class Envelope(expression, **extra)[source]¶

可用性: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

接受单个地理字段或表达式，并返回表示几何形状的边界框的几何形状。

`LineLocatePoint`¶

class LineLocatePoint(linestring, point, **extra)[source]¶

可用性: PostGIS, SpatiaLite

返回一个介于 0 和 1 之间的浮点数，表示最接近给定的 point 在 linestring 上的位置，作为 2D 线长度的一部分。

`PointOnSurface`¶

class PointOnSurface(expression, **extra)[source]¶

可用性: PostGIS, MariaDB, Oracle, SpatiaLite

接受单个地理字段或表达式，并返回一个保证位于字段表面上的 Point 几何形状；否则返回 None。

操作¶

`Difference`¶

class Difference(expr1, expr2, **extra)[source]¶

可用性: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

接受两个地理字段或表达式，并返回几何差异，即几何 A 中与几何 B 不相交的部分。

`Intersection`¶

class Intersection(expr1, expr2, **extra)[source]¶

可用性: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

接受两个地理字段或表达式，并返回它们之间的几何交集。

`SymDifference`¶

class SymDifference(expr1, expr2, **extra)[source]¶

可用性: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

接受两个地理字段或表达式，并返回给定参数之间的几何对称差异（联合而不包括交集）。

`Union`¶

class Union(expr1, expr2, **extra)[source]¶

可用性: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

接受两个地理字段或表达式，并返回两个几何形状的联合。

编辑器¶

`ForcePolygonCW`¶

class ForcePolygonCW(expression, **extra)[source]¶

可用性: PostGIS, SpatiaLite

接受单个地理字段或表达式，并返回多边形/多多边形的修改版本，其中所有外部环都按顺时针方向排列，所有内部环都按逆时针方向排列。非多边形几何形状保持不变。

`MakeValid`¶

class MakeValid(expr)[source]¶

可用性: PostGIS, SpatiaLite (LWGEOM/RTTOPO)

接受地理字段或表达式，并尝试将值转换为有效的几何形状，同时不丢失任何输入顶点。已经有效的几何形状将保持不变。简单多边形可能会变成多重多边形，结果的维度可能比输入低。

`Reverse`¶

class Reverse(expression, **extra)[source]¶

可用性: PostGIS, Oracle, SpatiaLite

接受单个地理字段或表达式，并返回具有颠倒坐标的几何形状。

`Rotate`¶

New in Django 6.0.

class Rotate(expression, angle, origin=None, **extra)[source]¶

Availability: PostGIS

Rotates a geometry by a specified angle around the origin. Optionally, the rotation can be performed around a point, defined by the origin parameter.

`Scale`¶

class Scale(expression, x, y, z=0.0, **extra)[source]¶

可用性: PostGIS, SpatiaLite

接受单个地理字段或表达式，并返回通过将坐标与 x、y 和可选的 z 参数相乘来缩放坐标的几何形状。

`SnapToGrid`¶

class SnapToGrid(expression, *args, **extra)[source]¶

可用性: PostGIS, SpatiaLite

Accepts a single geographic field or expression and returns a geometry with all points snapped to the given grid. How the geometry is snapped to the grid depends on how many numeric (either float, integer, or long) arguments are given.

参数数量：	描述
1	一个单独的大小，用于捕捉 X 和 Y 网格。
2	捕捉网格的 X 和 Y 大小。
4	X、Y 大小以及相应的 X、Y 起始点。

`Transform`¶

class Transform(expression, srid, **extra)[source]¶

可用性: PostGIS, Oracle, SpatiaLite

接受一个地理字段或表达式以及一个 SRID 整数代码，并将几何形状转换为由 srid 参数指定的空间参考系统。

Note

What spatial reference system an integer SRID corresponds to may depend on the spatial database used. In other words, the SRID numbers used for Oracle are not necessarily the same as those used by PostGIS.

`Translate`¶

class Translate(expression, x, y, z=0.0, **extra)[source]¶

可用性: PostGIS, SpatiaLite

接受单个地理字段或表达式，并返回其坐标根据 x、y 和可选的 z 数值参数进行偏移的几何形状。

输入格式：¶

`FromWKB`¶

class FromWKB(expression, srid=0, **extra)[source]¶

可用性: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

从 Well-known binary (WKB) 表示创建几何。可选的 srid 参数允许指定结果几何的 SRID。在 Oracle 上忽略 srid。

`FromWKT`¶

class FromWKT(expression, srid=0, **extra)[source]¶

可用性: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

从 Well-known text (WKT) 表示创建几何。可选的 srid 参数允许指定结果几何的 SRID。在 Oracle 上忽略 srid。

输出格式¶

`AsGeoJSON`¶

class AsGeoJSON(expression, bbox=False, crs=False, precision=8, **extra)[source]¶

可用性：MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

接受单个地理字段或表达式，并返回几何形状的 GeoJSON 表示。请注意，结果不是完整的 GeoJSON 结构，而只是 GeoJSON 结构中 geometry 键的内容。另请参阅 GeoJSON 序列化器。

例如：

>>> City.objects.annotate(json=AsGeoJSON("point")).get(name="Chicago").json
{"type":"Point","coordinates":[-87.65018,41.85039]}

关键字参数	描述
`bbox`	如果希望包含返回的 GeoJSON 中的边界框，请将其设置为 `True`。在 Oracle 中会被忽略。
`crs`	如果希望在返回的 GeoJSON 中包含坐标参考系统，请将其设置为 `True`。在 MySQL 和 Oracle 中会被忽略。
`precision`	可以用来指定 GeoJSON 表示中坐标的有效数字位数，其默认值为 8。在 Oracle 中会被忽略。

`AsGML`¶

class AsGML(expression, version=2, precision=8, **extra)[source]¶

可用性：Oracle, PostGIS, SpatiaLite

接受单个地理字段或表达式，并返回几何形状的 Geographic Markup Language (GML) 表示。

例如：

>>> qs = Zipcode.objects.annotate(gml=AsGML("poly"))
>>> print(qs[0].gml)
<gml:Polygon srsName="EPSG:4326"><gml:OuterBoundaryIs>-147.78711,70.245363 ...
-147.78711,70.245363</gml:OuterBoundaryIs></gml:Polygon>

关键字参数	描述
`precision`	指定在 GML 表示中坐标的有效数字位数，默认值为 8。在 Oracle 中会被忽略。
`version`	指定要使用的 GML 版本：2（默认）或 3。

`AsKML`¶

class AsKML(expression, precision=8, **extra)[source]¶

可用性：PostGIS, SpatiaLite

接受单个地理字段或表达式，并返回几何形状的 Keyhole Markup Language (KML) 表示。

例如：

>>> qs = Zipcode.objects.annotate(kml=AsKML("poly"))
>>> print(qs[0].kml)
<Polygon><outerBoundaryIs><LinearRing><coordinates>-103.04135,36.217596,0 ...
-103.04135,36.217596,0</coordinates></LinearRing></outerBoundaryIs></Polygon>

关键字参数	描述
`precision`	可以使用此关键字来指定 KML 表示中坐标的有效数字位数，其默认值为 8。

`AsSVG`¶

class AsSVG(expression, relative=False, precision=8, **extra)[source]¶

可用性：PostGIS, SpatiaLite

接受单个地理字段或表达式，并返回几何形状的 Scalable Vector Graphics (SVG) 表示。

关键字参数	描述
`relative`	如果设置为 `True`，路径数据将以相对移动的方式实现。默认为 `False`，表示使用绝对移动。
`precision`	可以使用此关键字来指定 SVG 表示中坐标的有效数字位数，其默认值为 8。

`AsWKB`¶

class AsWKB(expression, **extra)[source]¶

可用性：MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

接受单个地理字段或表达式，并返回几何形状的 Well-known binary (WKB) 表示。

例如：

>>> bytes(City.objects.annotate(wkb=AsWKB("point")).get(name="Chelyabinsk").wkb)
b'\x01\x01\x00\x00\x00]3\xf9f\x9b\x91K@\x00X\x1d9\xd2\xb9N@'

`AsWKT`¶

class AsWKT(expression, **extra)[source]¶

可用性：MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

接受单个地理字段或表达式，并返回几何形状的 Well-known text (WKT) 表示。

例如：

>>> City.objects.annotate(wkt=AsWKT("point")).get(name="Chelyabinsk").wkt
'POINT (55.137555 61.451728)'

`GeoHash`¶

class GeoHash(expression, precision=None, **extra)[source]¶

Availability: MariaDB, MySQL, PostGIS, SpatiaLite (LWGEOM/RTTOPO)

接受单个地理字段或表达式，并返回几何形状的 GeoHash 表示。

precision 关键字参数控制结果中的字符数。

Changed in Django 6.0:

MariaDB 12.0.1+ support was added.

杂项¶

`IsEmpty`¶

class IsEmpty(expr)[source]¶

可用性: PostGIS

接受地理字段或表达式，并测试其值是否为空几何形状。如果其值为空，则返回 True，否则返回 False。

`IsValid`¶

class IsValid(expr)[source]¶

Availability: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

接受地理字段或表达式，并测试其值是否格式正确。如果其值是有效的几何形状，则返回 True，否则返回 False。

Changed in Django 6.0:

MariaDB 12.0.1+ support was added.

`GeometryType`¶

New in Django 6.0.

class GeometryType(expr)[source]¶

Availability: PostGIS, Oracle 23c+, MariaDB, MySQL, SpatiaLite

Accepts a geographic field or expression and returns its geometry type.

`MemSize`¶

class MemSize(expression, **extra)[source]¶

可用性: PostGIS

接受单个地理字段或表达式，并返回几何字段占用的内存大小（字节数）。

`NumGeometries`¶

class NumGeometries(expression, **extra)[source]¶

可用性: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

接受单个地理字段或表达式，并返回如果几何字段是集合（例如 GEOMETRYCOLLECTION 或 MULTI* 字段）则包含的几何形状数量。对于单个几何形状，返回 1。

在 MySQL 上，对于单个几何形状，返回 None。

`NumPoints`¶

class NumPoints(expression, **extra)[source]¶

可用性: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

接受单个地理字段或表达式，并返回几何形状中点的数量。

在 MySQL 上，对于任何非 LINESTRING 几何形状，返回 None。

地理数据库函数¶

Measurements¶

Area¶

Distance¶

GeometryDistance¶

Length¶

Perimeter¶

关系映射¶

Azimuth¶

BoundingCircle¶

Centroid¶

ClosestPoint¶

Envelope¶

LineLocatePoint¶

PointOnSurface¶

操作¶

Difference¶

Intersection¶

SymDifference¶

Union¶

编辑器¶

ForcePolygonCW¶

MakeValid¶

Reverse¶

Rotate¶

Scale¶

SnapToGrid¶

Transform¶

Translate¶

输入格式：¶

FromWKB¶

FromWKT¶

输出格式¶

AsGeoJSON¶

AsGML¶

AsKML¶

AsSVG¶

AsWKB¶

AsWKT¶

GeoHash¶

杂项¶

IsEmpty¶

IsValid¶

GeometryType¶

MemSize¶

NumGeometries¶

NumPoints¶

附加信息

Support Django!

内容

获取帮助

下载：

Diamond and Platinum Members

`Area`¶

`Distance`¶

`GeometryDistance`¶

`Length`¶

`Perimeter`¶

`Azimuth`¶

`BoundingCircle`¶

`Centroid`¶

`ClosestPoint`¶

`Envelope`¶

`LineLocatePoint`¶

`PointOnSurface`¶

`Difference`¶

`Intersection`¶

`SymDifference`¶

`Union`¶

`ForcePolygonCW`¶

`MakeValid`¶

`Reverse`¶

`Rotate`¶

`Scale`¶

`SnapToGrid`¶

`Transform`¶

`Translate`¶

`FromWKB`¶

`FromWKT`¶

`AsGeoJSON`¶

`AsGML`¶

`AsKML`¶

`AsSVG`¶

`AsWKB`¶

`AsWKT`¶

`GeoHash`¶

`IsEmpty`¶

`IsValid`¶

`GeometryType`¶

`MemSize`¶

`NumGeometries`¶

`NumPoints`¶