地理数据库函数

本页所描述的函数允许用户访问地理数据库函数，以便在 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]}

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>

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>

AsSVG

class AsSVG(expression, relative=False, precision=8, **extra)

可用性：PostGIS, SpatiaLite

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

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)

可用性：PostGIS, Oracle

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

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

备注

因为 distance 属性是一个 Distance 对象，您可以轻松地以您选择的单位表示该值。例如，city.distance.mi 表示英里中的距离值，city.distance.km 表示千米中的距离值。有关用法详细信息和支持的单位列表，请参阅 测量对象。

Envelope

class Envelope(expression, **extra)

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

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

ForcePolygonCW

class ForcePolygonCW(expression, **extra)

可用性: PostGIS, SpatiaLite

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

FromWKB

New in Django 4.2.

class FromWKB(expression, **extra)

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

从 Well-known binary (WKB) 表示创建几何形状。

FromWKT

New in Django 4.2.

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

New in Django 4.2.

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)

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

MemSize

class MemSize(expression, **extra)

可用性: PostGIS

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

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

接受单个地理字段或表达式，并返回所有点都根据给定的网格进行捕捉的几何形状。如何将几何形状捕捉到网格取决于提供了多少个数字参数（可以是浮点数、整数或长整数）。

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 数值参数进行偏移的几何形状。

Union

class Union(expr1, expr2, **extra)

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

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