地理数据库函数 — Django 文档
地理数据库功能
此页面上记录的函数允许用户访问要在 Django 中的注释、聚合或过滤器中使用的地理数据库函数。
例子：
>>> from django.contrib.gis.db.models.functions import Length
>>> Track.objects.annotate(length=Length('line')).filter(length__gt=100)并非所有后端都支持所有功能，因此请参阅每个功能的文档，看看您的数据库后端是否支持您要使用的功能。 如果您在不支持的后端调用地理函数，您将收到 NotImplementedError 异常。
功能总结：
Area
- class Area(expression, **extra)
可用性：MariaDB、MySQL、Oracle、PostGIS、SpatiaLite
接受单个地理字段或表达式，并将该字段的面积作为 Area 度量返回。
没有 LWGEOM 的 MySQL 和 SpatiaLite 不支持地理 SRS 上的面积计算。
AsGeoJSON
- class AsGeoJSON(expression, bbox=False, crs=False, precision=8, **extra)
可用性：MariaDB (≥ 10.2.4)、MySQL (≥ 5.7.5)、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 上忽略。 |
3.1 版更改： 添加了 Oracle 支持。
AsGML
- class AsGML(expression, version=2, precision=8, **extra)
可用性：Oracle、PostGIS、SpatiaLite
接受单个地理字段或表达式并返回几何的 地理标记语言 (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)
可用性：PostGIS，SpatiaLite
接受单个地理字段或表达式并返回几何的 Keyhole 标记语言 (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。 |
3.1 版更改： 未记录的 version 参数已删除。
AsSVG
- class AsSVG(expression, relative=False, precision=8, **extra)
可用性：PostGIS，SpatiaLite
接受单个地理字段或表达式并返回几何图形的 可缩放矢量图形 (SVG) 表示。
| 关键字参数 | 说明 |
|---|---|
relative
|
如果设置为True，路径数据将按照相对移动来实现。 默认为 False，表示使用绝对移动。
|
precision
|
此关键字可用于指定 SVG 表示中坐标的有效位数 - 默认值为 8。 |
AsWKB
- class AsWKB(expression, **extra)
3.1 版中的新功能。
可用性：MariaDB、MySQL、Oracle、PostGIS、SpatiaLite
接受单个地理字段或表达式并返回几何的 众所周知的二进制 (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)
3.1 版中的新功能。
可用性：MariaDB、MySQL、Oracle、PostGIS、SpatiaLite
接受单个地理字段或表达式并返回几何的 众所周知的文本 (WKT) 表示。
例子：
>>> City.objects.annotate(wkt=AsWKT('point')).get(name='Chelyabinsk').wkt
'POINT (55.137555 61.451728)'Azimuth
- class Azimuth(point_a, point_b, **extra)
可用性：PostGIS，SpatiaLite (LWGEOM)
返回由给定点几何定义的线段的弧度方位角，如果两个点重合，则返回 None。 方位角是以北为参考的角度，顺时针为正：北 = 0； 东 = π/2; 南 = π; 西 = 3π/2。
BoundingCircle
- class BoundingCircle(expression, num_seg=48, **extra)
接受单个地理字段或表达式并返回可以完全包含几何的最小圆形多边形。
num_seg 参数仅用于 PostGIS。
Centroid
- class Centroid(expression, **extra)
可用性：MariaDB、MySQL、PostGIS、Oracle、SpatiaLite
接受单个地理字段或表达式并返回几何的 centroid 值。
Difference
- class Difference(expr1, expr2, **extra)
可用性：MariaDB、MySQL、PostGIS、Oracle、SpatiaLite
接受两个地理字段或表达式并返回几何差异，即几何 A 与几何 B 不相交的部分。
Distance
- class Distance(expr1, expr2, spheroid=None, **extra)
可用性：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
...Envelope
- class Envelope(expression, **extra)
可用性：MariaDB、MySQL、Oracle、PostGIS、SpatiaLite
接受单个地理字段或表达式并返回表示几何边界框的几何。
ForcePolygonCW
- class ForcePolygonCW(expression, **extra)
可用性：PostGIS，SpatiaLite
接受单个地理字段或表达式，并返回多边形/多多边形的修改版本，其中所有外环顺时针方向，所有内环逆时针方向。 非多边形几何图形返回不变。
GeoHash
- class GeoHash(expression, precision=None, **extra)
可用性：MySQL (≥ 5.7.5)、PostGIS、SpatiaLite (LWGEOM)
接受单个地理字段或表达式并返回几何的 GeoHash 表示。
precision 关键字参数控制结果中的字符数。
GeometryDistance
- class GeometryDistance(expr1, expr2, **extra)
3.0 版中的新功能。
可用性：PostGIS
接受两个地理字段或表达式并返回它们之间的距离。 在 order_by() 子句中使用时，它提供索引辅助的最近邻结果集。
Intersection
- class Intersection(expr1, expr2, **extra)
可用性：MariaDB、MySQL、PostGIS、Oracle、SpatiaLite
接受两个地理字段或表达式并返回它们之间的几何交集。
IsValid
- class IsValid(expr)
可用性：MySQL (≥ 5.7.5)、PostGIS、Oracle、SpatiaLite (LWGEOM)
接受地理字段或表达式并测试该值是否格式正确。 如果其值为有效几何，则返回 True，否则返回 False。
Length
- class Length(expression, spheroid=True, **extra)
可用性：MariaDB、MySQL、Oracle、PostGIS、SpatiaLite
接受单个地理线串或多线串字段或表达式，并将其长度作为 距离 度量返回。
在 PostGIS 和 SpatiaLite 上，当坐标为大地测量（角度）时，您可以指定计算是基于简单球体（精度较低，资源密集型较少）还是基于椭球体（更准确，资源密集型）与spheroid 关键字参数。
MySQL 不支持地理 SRS 的长度计算。
LineLocatePoint
- class LineLocatePoint(linestring, point, **extra)
可用性：PostGIS，SpatiaLite
返回一个介于 0 和 1 之间的浮点数，表示 linestring 上到给定 point 上最近点的位置，作为二维线长度的一部分。
MakeValid
- class MakeValid(expr)
可用性：PostGIS，SpatiaLite (LWGEOM)
接受地理字段或表达式，并尝试将值转换为有效的几何图形，而不会丢失任何输入顶点。 已有效的几何图形将原样返回。 简单的多边形可能会变成多多边形，结果的维度可能低于输入。
NumGeometries
- class NumGeometries(expression, **extra)
可用性：MariaDB、MySQL、PostGIS、Oracle、SpatiaLite
如果几何字段是一个集合（例如，GEOMETRYCOLLECTION 或 MULTI* 字段），则接受单个地理字段或表达式并返回几何的数量。 对于单个几何图形返回 1。
在 MySQL 上，为单个几何返回 None。
NumPoints
- class NumPoints(expression, **extra)
可用性：MariaDB、MySQL、PostGIS、Oracle、SpatiaLite
接受单个地理字段或表达式并返回几何中的点数。
在 MySQL 上，为任何非 LINESTRING 几何返回 None。
Perimeter
- class Perimeter(expression, **extra)
可用性：PostGIS、Oracle、SpatiaLite
接受单个地理字段或表达式，并将几何字段的周长作为 Distance 对象返回。
PointOnSurface
- class PointOnSurface(expression, **extra)
可用性：PostGIS、MariaDB、Oracle、SpatiaLite
接受单个地理字段或表达式，并返回一个 Point 几何图形，保证位于该字段的表面上； 否则返回 None。
Reverse
- class Reverse(expression, **extra)
可用性：PostGIS、Oracle、SpatiaLite
接受单个地理字段或表达式并返回具有反向坐标的几何图形。
Scale
- class Scale(expression, x, y, z=0.0, **extra)
可用性：PostGIS，SpatiaLite
接受单个地理字段或表达式，并通过将它们与 x、y 和可选的 z 参数相乘，返回带有缩放坐标的几何图形。
SnapToGrid
- class SnapToGrid(expression, *args, **extra)
可用性：PostGIS，SpatiaLite
接受单个地理字段或表达式，并返回所有点都对齐到给定网格的几何图形。 几何体如何捕捉到网格取决于给出的数字（浮点数、整数或长整型）参数的数量。
| 参数数量 | 说明 |
|---|---|
| 1 | 将 X 和 Y 网格捕捉到的单一尺寸。 |
| 2 | 将网格捕捉到的 X 和 Y 尺寸。 |
| 4 | X、Y 尺寸和相应的 X、Y 原点。 |
SymDifference
- class SymDifference(expr1, expr2, **extra)
可用性：MariaDB、MySQL、PostGIS、Oracle、SpatiaLite
接受两个地理字段或表达式，并返回给定参数之间的几何对称差异（没有交集的联合）。
Transform
- class Transform(expression, srid, **extra)
可用性：PostGIS、Oracle、SpatiaLite
接受地理字段或表达式以及 SRID 整数代码，并将转换后的几何返回到由 srid 参数指定的空间参考系统。
笔记
整数 SRID 对应的空间参考系统可能取决于所使用的空间数据库。 换句话说，Oracle 使用的 SRID 编号不一定与 PostGIS 使用的编号相同。
Translate
- class Translate(expression, x, y, z=0.0, **extra)
可用性：PostGIS，SpatiaLite
接受单个地理字段或表达式，并返回其坐标偏移 x、y 和可选的 z 数字参数的几何。
