获取帮助

en
es
fr
id
it
ja
ko
pl
pt-br
zh-hans
语言：en

1.10
1.11
2.0
2.1
2.2
3.0
3.1
3.2
4.0
4.1
4.2
5.0
dev
文档版本：5.1

地理数据库函数¶

此页面中记录的函数允许用户访问地理数据库函数，这些函数可用于 Django 中的注释、聚合或过滤器。

示例

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

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

函数摘要

测量	关系	操作	编辑器	输入格式	输出格式	其他
`面积`	`方位角`	`差集`	`强制多边形顺时针`		`作为 GeoJSON`	`是否为空`
`距离`	`边界圆`	`交集`	`使有效`		`作为 GML`	`是否有效`
`几何距离`	`形心`	`对称差`	`反转`		`作为 KML`	`内存大小`
`长度`	`最近点`	`并集`	`缩放`		`作为 SVG`	`几何个数`
`周长`	`Envelope` `LineLocatePoint` `PointOnSurface`		`SnapToGrid` `Transform` `Translate`	`FromWKB` `FromWKT`	`AsWKB` `AsWKT` `GeoHash`	`点数`

`Area`¶

class Area(expression, **extra)[source]¶

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

接受单个地理字段或表达式，并以Area度量返回字段的面积。

没有 LWGEOM/RTTOPO 的 MySQL 和 SpatiaLite 不支持对地理 SRS 进行面积计算。

`AsGeoJSON`¶

class AsGeoJSON(expression, bbox=False, crs=False, precision=8, **extra)[source]¶

可用性：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)[source]¶

可用性：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)[source]¶

可用性：PostGIS，SpatiaLite

接受单个地理字段或表达式，并返回几何图形的键控标记语言 (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)[source]¶

可用性：PostGIS，SpatiaLite

接受单个地理字段或表达式，并返回几何图形的可缩放矢量图形 (SVG)表示。

关键字参数	描述
`relative`	如果设置为`True`，则路径数据将以相对移动的方式实现。默认为`False`，这意味着将使用绝对移动。
`precision`	此关键字可用于指定SVG表示中坐标的有效数字位数——默认值为8。

`AsWKB`¶

class AsWKB(expression, **extra)[source]¶

可用性：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)[source]¶

可用性：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)[source]¶

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

返回由给定点几何图形定义的线段的方位角（以弧度表示），如果两点重合，则返回None。方位角是从北向参考的角度，顺时针方向为正：北 = 0；东 = π/2；南 = π；西 = 3π/2。

`BoundingCircle`¶

class BoundingCircle(expression, num_seg=48, **extra)[source]¶

可用性：PostGIS，Oracle，SpatiaLite 5.1+

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

num_seg参数仅在PostGIS上使用。

Django 5.1 中的更改

添加了 SpatiaLite 5.1+ 支持。

`Centroid`¶

class Centroid(expression, **extra)[source]¶

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

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

`ClosestPoint`¶

Django 5.0 中新增。

class ClosestPoint(expr1, expr2, **extra)[source]¶

可用性：PostGIS，SpatiaLite

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

`Difference`¶

class Difference(expr1, expr2, **extra)[source]¶

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

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

`Distance`¶

class Distance(expr1, expr2, spheroid=None, **extra)[source]¶

可用性：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)[source]¶

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

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

`ForcePolygonCW`¶

class ForcePolygonCW(expression, **extra)[source]¶

可用性: PostGIS，SpatiaLite

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

`FromWKB`¶

class FromWKB(expression, srid=0, **extra)[source]¶

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

从良知二进制 (WKB)表示创建几何图形。可选的srid参数允许指定结果几何图形的SRID。srid在Oracle中被忽略。

Django 5.1 中的更改

添加了srid参数。

`FromWKT`¶

class FromWKT(expression, srid=0, **extra)[source]¶

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

从良知文本 (WKT)表示创建几何图形。可选的srid参数允许指定结果几何图形的SRID。srid在Oracle中被忽略。

Django 5.1 中的更改

添加了srid参数。

`GeoHash`¶

class GeoHash(expression, precision=None, **extra)[source]¶

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

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

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

`GeometryDistance`¶

class GeometryDistance(expr1, expr2, **extra)[source]¶

可用性: PostGIS

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

`Intersection`¶

class Intersection(expr1, expr2, **extra)[source]¶

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

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

`IsEmpty`¶

class IsEmpty(expr)[source]¶

可用性: PostGIS

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

`IsValid`¶

class IsValid(expr)[source]¶

可用性: MySQL，PostGIS，Oracle，SpatiaLite

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

`Length`¶

class Length(expression, spheroid=True, **extra)[source]¶

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

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

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

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

`LineLocatePoint`¶

class LineLocatePoint(linestring, point, **extra)[source]¶

可用性: PostGIS，SpatiaLite

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

`MakeValid`¶

class MakeValid(expr)[source]¶

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

接收一个地理字段或表达式，并尝试将其值转换为有效的几何图形，而不会丢失任何输入顶点。已经是有效几何图形的几何图形将原样返回。简单多边形可能会变成多面多边形，结果的维度可能低于输入。

`MemSize`¶

class MemSize(expression, **extra)[source]¶

可用性：PostGIS

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

`NumGeometries`¶

class NumGeometries(expression, **extra)[source]¶

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

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

在 MySQL 中，对于单个几何图形返回 None。

`NumPoints`¶

class NumPoints(expression, **extra)[source]¶

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

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

在 MySQL 中，对于任何非 LINESTRING 几何图形返回 None。

`Perimeter`¶

class Perimeter(expression, **extra)[source]¶

可用性：PostGIS，Oracle，SpatiaLite

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

`PointOnSurface`¶

class PointOnSurface(expression, **extra)[source]¶

可用性：PostGIS，MariaDB，Oracle，SpatiaLite

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

`Reverse`¶

class Reverse(expression, **extra)[source]¶

可用性：PostGIS，Oracle，SpatiaLite

接收单个地理字段或表达式，并返回具有反向坐标的几何图形。

`Scale`¶

class Scale(expression, x, y, z=0.0, **extra)[source]¶

可用性：PostGIS，SpatiaLite

接收单个地理字段或表达式，并返回一个几何图形，其坐标通过与 x、y 和可选的 z 参数相乘进行缩放。

`SnapToGrid`¶

class SnapToGrid(expression, *args, **extra)[source]¶

可用性：PostGIS，SpatiaLite

接收单个地理字段或表达式，并返回一个几何图形，所有点都捕捉到给定的网格。几何图形如何捕捉到网格取决于给定的数值参数（浮点数、整数或长整数）数量。

参数数量	描述
1	一个用于将 X 和 Y 网格都捕捉到的单个大小。
2	用于捕捉网格的 X 和 Y 大小。
4	X、Y 大小和相应的 X、Y 原点。

`SymDifference`¶

class SymDifference(expr1, expr2, **extra)[source]¶

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

接收两个地理字段或表达式，并返回给定参数之间的几何对称差（并集减去交集）。

`Transform`¶

class Transform(expression, srid, **extra)[source]¶

可用性：PostGIS，Oracle，SpatiaLite

接收一个地理字段或表达式和一个 SRID 整数代码，并将转换后的几何图形返回到由 srid 参数指定的空间参考系统。

注意

整数 SRID 对应的空间参考系统可能取决于使用的空间数据库。换句话说，Oracle 使用的 SRID 编号不一定与 PostGIS 使用的相同。

`Translate`¶

class Translate(expression, x, y, z=0.0, **extra)[source]¶

可用性: PostGIS，SpatiaLite

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

`Union`¶

class Union(expr1, expr2, **extra)[source]¶

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

接受两个地理字段或表达式，并返回这两个几何图形的并集。

GIS QuerySet API 参考

测量对象

返回顶部

文档

地理数据库函数¶

Area¶

AsGeoJSON¶

AsGML¶

AsKML¶

AsSVG¶

AsWKB¶

AsWKT¶

Azimuth¶

BoundingCircle¶

Centroid¶

ClosestPoint¶

Difference¶

Distance¶

Envelope¶

ForcePolygonCW¶

FromWKB¶

FromWKT¶

GeoHash¶

GeometryDistance¶

Intersection¶

IsEmpty¶

IsValid¶

Length¶

LineLocatePoint¶

MakeValid¶

MemSize¶

NumGeometries¶

NumPoints¶

Perimeter¶

PointOnSurface¶

Reverse¶

Scale¶

SnapToGrid¶

SymDifference¶

Transform¶

Translate¶

Union¶

附加信息

支持 Django！

目录

浏览

您当前位置

获取帮助

下载

`Area`¶

`AsGeoJSON`¶

`AsGML`¶

`AsKML`¶

`AsSVG`¶

`AsWKB`¶

`AsWKT`¶

`Azimuth`¶

`BoundingCircle`¶

`Centroid`¶

`ClosestPoint`¶

`Difference`¶

`Distance`¶

`Envelope`¶

`ForcePolygonCW`¶

`FromWKB`¶

`FromWKT`¶

`GeoHash`¶

`GeometryDistance`¶

`Intersection`¶

`IsEmpty`¶

`IsValid`¶

`Length`¶

`LineLocatePoint`¶

`MakeValid`¶

`MemSize`¶

`NumGeometries`¶

`NumPoints`¶

`Perimeter`¶

`PointOnSurface`¶

`Reverse`¶

`Scale`¶

`SnapToGrid`¶

`SymDifference`¶

`Transform`¶

`Translate`¶

`Union`¶