地理数据库函数¶
本页所描述的函数允许用户访问地理数据库函数，以便在 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/RTTOPO 支持的情况下，MySQL 和 SpatiaLite 不支持对地理 SRS（空间参考系统）进行面积计算。
AsGeoJSON¶
-
class
AsGeoJSON(expression, bbox=False, crs=False, precision=8, **extra)¶
可用性：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)¶
可用性：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)¶
可用性：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)¶
可用性：PostGIS, SpatiaLite
接受单个地理字段或表达式，并返回几何形状的 Scalable Vector Graphics (SVG) 表示。
| 关键字参数 | 描述 |
|---|---|
relative |
如果设置为 True，路径数据将以相对移动的方式实现。默认为 False，表示使用绝对移动。 |
precision |
可以使用此关键字来指定 SVG 表示中坐标的有效数字位数，其默认值为 8。 |
AsWKB¶
-
class
AsWKB(expression, **extra)¶
可用性：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)¶
可用性：MariaDB, MySQL, Oracle, PostGIS, SpatiaLite
接受单个地理字段或表达式，并返回几何形状的 Well-known text (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/RTTOPO)
返回由给定点几何形状定义的线段的方位角（以弧度表示），如果两个点重合，则返回 None。方位角是以北方为参考的角度，顺时针方向为正：north = 0; east = π/2; south = π; west = 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
接受单个地理字段或表达式，并返回多边形/多多边形的修改版本，其中所有外部环都按顺时针方向排列，所有内部环都按逆时针方向排列。非多边形几何形状保持不变。
FromWKB¶
-
class
FromWKB(expression, **extra)¶
可用性: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite
从 Well-known binary (WKB) 表示创建几何形状。
FromWKT¶
-
class
FromWKT(expression, **extra)¶
可用性: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite
从 Well-known text (WKT) 表示创建几何形状。
GeoHash¶
-
class
GeoHash(expression, precision=None, **extra)¶
可用性: MySQL, PostGIS, SpatiaLite (LWGEOM/RTTOPO)
接受单个地理字段或表达式，并返回几何形状的 GeoHash 表示。
precision 关键字参数控制结果中的字符数。
GeometryDistance¶
-
class
GeometryDistance(expr1, expr2, **extra)¶
可用性: PostGIS
接受两个地理字段或表达式，并返回它们之间的距离。当在 order_by() 子句中使用时，它提供了辅助索引的最近邻结果集。
Intersection¶
-
class
Intersection(expr1, expr2, **extra)¶
可用性: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite
接受两个地理字段或表达式，并返回它们之间的几何交集。
IsEmpty¶
-
class
IsEmpty(expr)¶
可用性: PostGIS
接受地理字段或表达式，并测试其值是否为空几何形状。如果其值为空，则返回 True，否则返回 False。
IsValid¶
-
class
IsValid(expr)¶
可用性: MySQL, PostGIS, Oracle, SpatiaLite
接受地理字段或表达式，并测试其值是否格式正确。如果其值是有效的几何形状，则返回 True，否则返回 False。
Length¶
-
class
Length(expression, spheroid=True, **extra)¶
可用性: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite
接受单个地理线串或多线串字段或表达式，并将其长度返回为 Distance 测量。
在 PostGIS 和 SpatiaLite 上，当坐标是大地测量（角度）时，您可以使用 spheroid 关键字参数来指定计算是基于简单球体（精度较低，资源消耗较少）还是基于椭球体（精度较高，资源消耗较多）。
MySQL 不支持在地理 SRS 上进行长度计算。
LineLocatePoint¶
-
class
LineLocatePoint(linestring, point, **extra)¶
可用性: PostGIS, SpatiaLite
返回一个介于 0 和 1 之间的浮点数，表示最接近给定的 point 在 linestring 上的位置，作为 2D 线长度的一部分。
MakeValid¶
-
class
MakeValid(expr)¶
可用性: PostGIS, SpatiaLite (LWGEOM/RTTOPO)
接受地理字段或表达式，并尝试将值转换为有效的几何形状，同时不丢失任何输入顶点。已经有效的几何形状将保持不变。简单多边形可能会变成多重多边形，结果的维度可能比输入低。
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 的相同。
