地理数据库函数Link to this heading#

AreaLink to this heading#

class Area(expression, **extra)Link to this definition#

Availability: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

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

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

DistanceLink to this heading#

class Distance(expr1, expr2, spheroid=None, **extra)Link to this definition#

可用性: 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
...

GeometryDistanceLink to this heading#

class GeometryDistance(expr1, expr2, **extra)Link to this definition#

可用性: PostGIS

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

LengthLink to this heading#

class Length(expression, spheroid=True, **extra)Link to this definition#

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

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

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

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

PerimeterLink to this heading#

class Perimeter(expression, **extra)Link to this definition#

可用性: PostGIS, Oracle, SpatiaLite

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

AzimuthLink to this heading#

class Azimuth(point_a, point_b, **extra)Link to this definition#

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

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

BoundingCircleLink to this heading#

class BoundingCircle(expression, num_seg=48, **extra)Link to this definition#

可用性：PostGIS、Oracle、SpatiaLite 5.1+

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

num_seg 参数仅在 PostGIS 中使用。

CentroidLink to this heading#

class Centroid(expression, **extra)Link to this definition#

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

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

ClosestPointLink to this heading#

class ClosestPoint(expr1, expr2, **extra)Link to this definition#

可用性: PostGIS, SpatiaLite

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

EnvelopeLink to this heading#

class Envelope(expression, **extra)Link to this definition#

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

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

LineLocatePointLink to this heading#

class LineLocatePoint(linestring, point, **extra)Link to this definition#

可用性: PostGIS, SpatiaLite

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

PointOnSurfaceLink to this heading#

class PointOnSurface(expression, **extra)Link to this definition#

可用性: PostGIS, MariaDB, Oracle, SpatiaLite

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

DifferenceLink to this heading#

class Difference(expr1, expr2, **extra)Link to this definition#

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

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

IntersectionLink to this heading#

class Intersection(expr1, expr2, **extra)Link to this definition#

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

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

SymDifferenceLink to this heading#

class SymDifference(expr1, expr2, **extra)Link to this definition#

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

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

UnionLink to this heading#

class Union(expr1, expr2, **extra)Link to this definition#

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

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

ForcePolygonCWLink to this heading#

class ForcePolygonCW(expression, **extra)Link to this definition#

可用性: PostGIS, SpatiaLite

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

MakeValidLink to this heading#

class MakeValid(expr)Link to this definition#

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

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

ReverseLink to this heading#

class Reverse(expression, **extra)Link to this definition#

可用性: PostGIS, Oracle, SpatiaLite

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

RotateLink to this heading#

class Rotate(expression, angle, origin=None, **extra)Link to this definition#

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.

ScaleLink to this heading#

class Scale(expression, x, y, z=0.0, **extra)Link to this definition#

可用性: PostGIS, SpatiaLite

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

SnapToGridLink to this heading#

class SnapToGrid(expression, *args, **extra)Link to this definition#

可用性: 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.

TransformLink to this heading#

class Transform(expression, srid, **extra)Link to this definition#

可用性: PostGIS, Oracle, SpatiaLite

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

TranslateLink to this heading#

class Translate(expression, x, y, z=0.0, **extra)Link to this definition#

可用性: PostGIS, SpatiaLite

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

FromWKBLink to this heading#

class FromWKB(expression, srid=0, **extra)Link to this definition#

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

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

FromWKTLink to this heading#

class FromWKT(expression, srid=0, **extra)Link to this definition#

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

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

AsGeoJSONLink to this heading#

class AsGeoJSON(expression, bbox=False, crs=False, precision=8, **extra)Link to this definition#

可用性：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]}

AsGMLLink to this heading#

class AsGML(expression, version=2, precision=8, **extra)Link to this definition#

可用性：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>

AsKMLLink to this heading#

class AsKML(expression, precision=8, **extra)Link to this definition#

可用性：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>

AsSVGLink to this heading#

class AsSVG(expression, relative=False, precision=8, **extra)Link to this definition#

可用性：PostGIS, SpatiaLite

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

AsWKBLink to this heading#

class AsWKB(expression, **extra)Link to this definition#

可用性：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@'

AsWKTLink to this heading#

class AsWKT(expression, **extra)Link to this definition#

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

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

例如：

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

GeoHashLink to this heading#

class GeoHash(expression, precision=None, **extra)Link to this definition#

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

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

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

IsEmptyLink to this heading#

class IsEmpty(expr)Link to this definition#

可用性: PostGIS

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

IsValidLink to this heading#

class IsValid(expr)Link to this definition#

Availability: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

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

GeometryTypeLink to this heading#

class GeometryType(expr)Link to this definition#

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

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

MemSizeLink to this heading#

class MemSize(expression, **extra)Link to this definition#

可用性: PostGIS

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

NumGeometriesLink to this heading#

class NumGeometries(expression, **extra)Link to this definition#

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

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

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

NumPointsLink to this heading#

class NumPoints(expression, **extra)Link to this definition#

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

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

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