{"title":"地理数据库函数","version":"5.1","locale":"zh-hans","docname":"ref/contrib/gis/functions","url":"/zh-hans/5.1/ref/contrib/gis/functions/","canonical":"https://djangodocs.dev/zh-hans/5.1/ref/contrib/gis/functions/","summary":"本页所描述的函数允许用户访问地理数据库函数，以便在 Django 中使用注释、聚合或过滤器。","html":"

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

\n

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

\n

例如：

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

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

\n

函数的摘要：

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

测量

关系映射

操作

编辑器

输入格式：

输出格式

杂项

Area

Azimuth

Difference

ForcePolygonCW

AsGeoJSON

IsEmpty

Distance

BoundingCircle

Intersection

MakeValid

AsGML

IsValid

GeometryDistance

Centroid

SymDifference

Reverse

AsKML

MemSize

Length

ClosestPoint

Union

Scale

AsSVG

NumGeometries

Perimeter

Envelope\nLineLocatePoint\nPointOnSurface

SnapToGrid\nTransform\nTranslate

FromWKB\nFromWKT

AsWKB\nAsWKT\nGeoHash

NumPoints

\n
\n
\n

AreaLink to this heading#

\n
\n
\nclass Area(expression, **extra)Link to this definition#
\n
\n\n

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

\n

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

\n

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

\n
\n
\n

AsGeoJSONLink to this heading#

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

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

\n

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

\n

例如：

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

关键字参数

描述

bbox

如果希望包含返回的 GeoJSON 中的边界框，请将其设置为 True。在 Oracle 中会被忽略。

crs

如果希望在返回的 GeoJSON 中包含坐标参考系统，请将其设置为 True。在 MySQL 和 Oracle 中会被忽略。

precision

可以用来指定 GeoJSON 表示中坐标的有效数字位数，其默认值为 8。在 Oracle 中会被忽略。

\n
\n
\n
\n

AsGMLLink to this heading#

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

可用性：Oracle, PostGIS, SpatiaLite

\n

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

\n

例如：

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

关键字参数

描述

precision

指定在 GML 表示中坐标的有效数字位数，默认值为 8。在 Oracle 中会被忽略。

version

指定要使用的 GML 版本：2（默认）或 3。

\n
\n
\n
\n

AsKMLLink to this heading#

\n
\n
\nclass AsKML(expression, precision=8, **extra)Link to this definition#
\n
\n\n

可用性：PostGIS, SpatiaLite

\n

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

\n

例如：

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

关键字参数

描述

precision

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

\n
\n
\n
\n

AsSVGLink to this heading#

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

可用性：PostGIS, SpatiaLite

\n

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

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n

关键字参数

描述

relative

如果设置为 True，路径数据将以相对移动的方式实现。默认为 False，表示使用绝对移动。

precision

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

\n
\n
\n
\n

AsWKBLink to this heading#

\n
\n
\nclass AsWKB(expression, **extra)Link to this definition#
\n
\n\n

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

\n

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

\n

例如：

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

AsWKTLink to this heading#

\n
\n
\nclass AsWKT(expression, **extra)Link to this definition#
\n
\n\n

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

\n

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

\n

例如：

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

AzimuthLink to this heading#

\n
\n
\nclass Azimuth(point_a, point_b, **extra)Link to this definition#
\n
\n\n

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

\n

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

\n
\n
\n

BoundingCircleLink to this heading#

\n
\n
\nclass BoundingCircle(expression, num_seg=48, **extra)Link to this definition#
\n
\n\n

可用性：PostGIS、Oracle、SpatiaLite 5.1+

\n

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

\n

num_seg 参数仅在 PostGIS 中使用。

\n\n
\n
\n

CentroidLink to this heading#

\n
\n
\nclass Centroid(expression, **extra)Link to this definition#
\n
\n\n

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

\n

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

\n
\n
\n

ClosestPointLink to this heading#

\n\n
\n
\nclass ClosestPoint(expr1, expr2, **extra)Link to this definition#
\n
\n\n

可用性: PostGIS, SpatiaLite

\n

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

\n
\n
\n

DifferenceLink to this heading#

\n
\n
\nclass Difference(expr1, expr2, **extra)Link to this definition#
\n
\n\n

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

\n

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

\n
\n
\n

DistanceLink to this heading#

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

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

\n

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

\n

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

\n

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

\n

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

\n
Python console
>>> from django.contrib.gis.db.models.functions import Distance\n>>> pnt = AustraliaCity.objects.get(name="Hobart").point\n>>> for city in AustraliaCity.objects.annotate(distance=Distance("point", pnt)):\n...     print(city.name, city.distance)\n...\nWollongong 990071.220408 m\nShellharbour 972804.613941 m\nThirroul 1002334.36351 m\n...\n
\n\n
\n
\n

EnvelopeLink to this heading#

\n
\n
\nclass Envelope(expression, **extra)Link to this definition#
\n
\n\n

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

\n

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

\n
\n
\n

ForcePolygonCWLink to this heading#

\n
\n
\nclass ForcePolygonCW(expression, **extra)Link to this definition#
\n
\n\n

可用性: PostGIS, SpatiaLite

\n

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

\n
\n
\n

FromWKBLink to this heading#

\n
\n
\nclass FromWKB(expression, srid=0, **extra)Link to this definition#
\n
\n\n

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

\n

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

\n\n
\n
\n

FromWKTLink to this heading#

\n
\n
\nclass FromWKT(expression, srid=0, **extra)Link to this definition#
\n
\n\n

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

\n

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

\n\n
\n
\n

GeoHashLink to this heading#

\n
\n
\nclass GeoHash(expression, precision=None, **extra)Link to this definition#
\n
\n\n

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

\n

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

\n

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

\n
\n
\n

GeometryDistanceLink to this heading#

\n
\n
\nclass GeometryDistance(expr1, expr2, **extra)Link to this definition#
\n
\n\n

可用性: PostGIS

\n

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

\n
\n
\n

IntersectionLink to this heading#

\n
\n
\nclass Intersection(expr1, expr2, **extra)Link to this definition#
\n
\n\n

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

\n

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

\n
\n
\n

IsEmptyLink to this heading#

\n
\n
\nclass IsEmpty(expr)Link to this definition#
\n
\n\n

可用性: PostGIS

\n

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

\n
\n
\n

IsValidLink to this heading#

\n
\n
\nclass IsValid(expr)Link to this definition#
\n
\n\n

可用性: MySQL, PostGIS, Oracle, SpatiaLite

\n

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

\n
\n
\n

LengthLink to this heading#

\n
\n
\nclass Length(expression, spheroid=True, **extra)Link to this definition#
\n
\n\n

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

\n

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

\n

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

\n

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

\n
\n
\n

LineLocatePointLink to this heading#

\n
\n
\nclass LineLocatePoint(linestring, point, **extra)Link to this definition#
\n
\n\n

可用性: PostGIS, SpatiaLite

\n

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

\n
\n
\n

MakeValidLink to this heading#

\n
\n
\nclass MakeValid(expr)Link to this definition#
\n
\n\n

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

\n

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

\n
\n
\n

MemSizeLink to this heading#

\n
\n
\nclass MemSize(expression, **extra)Link to this definition#
\n
\n\n

可用性: PostGIS

\n

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

\n
\n
\n

NumGeometriesLink to this heading#

\n
\n
\nclass NumGeometries(expression, **extra)Link to this definition#
\n
\n\n

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

\n

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

\n

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

\n
\n
\n

NumPointsLink to this heading#

\n
\n
\nclass NumPoints(expression, **extra)Link to this definition#
\n
\n\n

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

\n

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

\n

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

\n
\n
\n

PerimeterLink to this heading#

\n
\n
\nclass Perimeter(expression, **extra)Link to this definition#
\n
\n\n

可用性: PostGIS, Oracle, SpatiaLite

\n

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

\n
\n
\n

PointOnSurfaceLink to this heading#

\n
\n
\nclass PointOnSurface(expression, **extra)Link to this definition#
\n
\n\n

可用性: PostGIS, MariaDB, Oracle, SpatiaLite

\n

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

\n
\n
\n

ReverseLink to this heading#

\n
\n
\nclass Reverse(expression, **extra)Link to this definition#
\n
\n\n

可用性: PostGIS, Oracle, SpatiaLite

\n

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

\n
\n
\n

ScaleLink to this heading#

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

可用性: PostGIS, SpatiaLite

\n

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

\n
\n
\n

SnapToGridLink to this heading#

\n
\n
\nclass SnapToGrid(expression, *args, **extra)Link to this definition#
\n
\n\n

可用性: PostGIS, SpatiaLite

\n

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

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

参数数量：

描述

1

一个单独的大小，用于捕捉 X 和 Y 网格。

2

捕捉网格的 X 和 Y 大小。

4

X、Y 大小以及相应的 X、Y 起始点。

\n
\n
\n
\n

SymDifferenceLink to this heading#

\n
\n
\nclass SymDifference(expr1, expr2, **extra)Link to this definition#
\n
\n\n

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

\n

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

\n
\n
\n

TransformLink to this heading#

\n
\n
\nclass Transform(expression, srid, **extra)Link to this definition#
\n
\n\n

可用性: PostGIS, Oracle, SpatiaLite

\n

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

\n\n
\n
\n

TranslateLink to this heading#

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

可用性: PostGIS, SpatiaLite

\n

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

\n
\n
\n

UnionLink to this heading#

\n
\n
\nclass Union(expr1, expr2, **extra)Link to this definition#
\n
\n\n

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

\n

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

\n
","rootId":"module-django.contrib.gis.db.models.functions","toc":[{"title":"Area","anchor":"area","children":[]},{"title":"AsGeoJSON","anchor":"asgeojson","children":[]},{"title":"AsGML","anchor":"asgml","children":[]},{"title":"AsKML","anchor":"askml","children":[]},{"title":"AsSVG","anchor":"assvg","children":[]},{"title":"AsWKB","anchor":"aswkb","children":[]},{"title":"AsWKT","anchor":"aswkt","children":[]},{"title":"Azimuth","anchor":"azimuth","children":[]},{"title":"BoundingCircle","anchor":"boundingcircle","children":[]},{"title":"Centroid","anchor":"centroid","children":[]},{"title":"ClosestPoint","anchor":"closestpoint","children":[]},{"title":"Difference","anchor":"difference","children":[]},{"title":"Distance","anchor":"distance","children":[]},{"title":"Envelope","anchor":"envelope","children":[]},{"title":"ForcePolygonCW","anchor":"forcepolygoncw","children":[]},{"title":"FromWKB","anchor":"fromwkb","children":[]},{"title":"FromWKT","anchor":"fromwkt","children":[]},{"title":"GeoHash","anchor":"geohash","children":[]},{"title":"GeometryDistance","anchor":"geometrydistance","children":[]},{"title":"Intersection","anchor":"intersection","children":[]},{"title":"IsEmpty","anchor":"isempty","children":[]},{"title":"IsValid","anchor":"isvalid","children":[]},{"title":"Length","anchor":"length","children":[]},{"title":"LineLocatePoint","anchor":"linelocatepoint","children":[]},{"title":"MakeValid","anchor":"makevalid","children":[]},{"title":"MemSize","anchor":"memsize","children":[]},{"title":"NumGeometries","anchor":"numgeometries","children":[]},{"title":"NumPoints","anchor":"numpoints","children":[]},{"title":"Perimeter","anchor":"perimeter","children":[]},{"title":"PointOnSurface","anchor":"pointonsurface","children":[]},{"title":"Reverse","anchor":"reverse","children":[]},{"title":"Scale","anchor":"scale","children":[]},{"title":"SnapToGrid","anchor":"snaptogrid","children":[]},{"title":"SymDifference","anchor":"symdifference","children":[]},{"title":"Transform","anchor":"transform","children":[]},{"title":"Translate","anchor":"translate","children":[]},{"title":"Union","anchor":"union","children":[]}],"breadcrumbs":[{"docname":"ref/index","title":"API 参考","url":"/zh-hans/5.1/ref/"},{"docname":"ref/contrib/index","title":"contrib 包","url":"/zh-hans/5.1/ref/contrib/"},{"docname":"ref/contrib/gis/index","title":"GeoDjango","url":"/zh-hans/5.1/ref/contrib/gis/"}],"prev":{"docname":"ref/contrib/gis/geoquerysets","title":"GIS QuerySet API 参考","url":"/zh-hans/5.1/ref/contrib/gis/geoquerysets/"},"next":{"docname":"ref/contrib/gis/measure","title":"测量对象","url":"/zh-hans/5.1/ref/contrib/gis/measure/"},"formats":{"html":"/zh-hans/5.1/ref/contrib/gis/functions/","markdown":"/zh-hans/5.1/ref/contrib/gis/functions.md","json":"/zh-hans/5.1/ref/contrib/gis/functions.json"},"source":"https://github.com/django/django/blob/stable/5.1.x/docs/ref/contrib/gis/functions.txt","official":"https://docs.djangoproject.com/zh-hans/5.1/ref/contrib/gis/functions/","inVersions":["6.1","6.0","5.2","5.1","5.0","4.2","4.1","4.0","3.2","3.1","3.0","2.2","2.1","2.0"],"inLocales":["en","zh-hans","fr","ja","id","it","pt-br","ko","es","el","pl"]}