获取帮助

el
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.1
dev
文档版本：5.0

地理数据库函数¶

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

示例

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

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

函数摘要

测量	关系	操作	编辑器	输入格式	输出格式	杂项
`面积`	`方位角`	`差值`	`ForcePolygonCW`		`AsGeoJSON`	`IsEmpty`
`距离`	`BoundingCircle`	`交集`	`MakeValid`		`AsGML`	`IsValid`
`GeometryDistance`	`质心`	`对称差`	`反转`		`AsKML`	`MemSize`
`长度`	`ClosestPoint`	`并集`	`缩放`		`AsSVG`	`NumGeometries`
`周长`	`Envelope` `LineLocatePoint` `PointOnSurface`		`SnapToGrid` `Transform` `Translate`	`FromWKB` `FromWKT`	`AsWKB` `AsWKT` `GeoHash`	`NumPoints`

`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`¶

类 AsGML(表达式, 版本=2, 精度=8, **额外)¶

可用性：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 上忽略。
`版本`	指定要使用的 GML 版本：2（默认）或 3。

`AsKML`¶

类 AsKML(表达式, 精度=8, **额外)¶

可用性：PostGIS、SpatiaLite

接受单个地理字段或表达式，并返回几何的Keyhole 标记语言 (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`¶

类 AsSVG(表达式, 相对=False, 精度=8, **额外)¶

可用性: PostGIS、SpatiaLite

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

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

`AsWKB`¶

类 AsWKB(表达式, **额外)¶

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

接受单个地理字段或表达式，并返回几何的已知二进制 (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`¶

类 AsWKT(表达式, **额外)¶

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

接受单个地理字段或表达式，并返回几何的已知文本 (WKT)表示。

示例

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

`方位角`¶

类 方位角(点_a, 点_b, **额外)¶

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

返回由给定点几何定义的线段的弧度方位角，或如果两个点重合则返回无。方位角是从北向引用的角度，并按顺时针方向为正：北 = 0；东 = π/2；南 = π；西 = 3π/2。

`边界圆`¶

类 边界圆(表达式, num_seg=48, **额外)¶

可用性: PostGIS，Oracle

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

仅在 PostGIS 上使用num_seg参数。

`质心`¶

类 质心(表达式, **额外)¶

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

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

`最近点`¶

Django 5.0 中的新增功能。

类 最近点(expr1, expr2, **额外)¶

可用性：PostGIS、SpatiaLite

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

`差值`¶

类 差值(expr1, expr2, **额外)¶

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

Django 4.2 中的新增功能。

class FromWKB(expression, **extra)¶

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

根据已知二进制 (WKB)表示形式创建几何。

`FromWKT`¶

Django 4.2 中的新增功能。

class FromWKT(expression, **extra)¶

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

根据已知文本 (WKT)表示形式创建几何。

`GeoHash`¶

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

可用性：MySQL、PostGIS、SpatiaLite (LWGEOM/RTTOPO)

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

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

`GeometryDistance`¶

类 GeometryDistance(expr1, expr2, **extra)¶

可用性: PostGIS

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

`Intersection`¶

类 Intersection(expr1, expr2, **extra)¶

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

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

`IsEmpty`¶

Django 4.2 中的新增功能。

类 IsEmpty(expr)¶

可用性: PostGIS

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

`IsValid`¶

类 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 之间的小数，表示 linestring 上最接近给定 point 的点的 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`¶

类 比例(表达式, x, y, z=0.0, **额外)¶

可用性: PostGIS、SpatiaLite

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

`捕捉到网格`¶

类 捕捉到网格(表达式, *参数, **额外)¶

可用性: PostGIS、SpatiaLite

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

参数数量	说明
1	捕捉 X 和 Y 网格的单个大小。
2	捕捉网格的 X 和 Y 大小。
4	X、Y 大小以及相应的 X、Y 原点。

`对称差`¶

类 对称差(expr1, expr2, **额外)¶

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

类 联合(expr1, expr2, **额外)¶

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

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

GIS QuerySet API 参考

测量对象

返回顶部

文档

地理数据库函数¶

Area¶

AsGeoJSON¶

AsGML¶

AsKML¶

AsSVG¶

AsWKB¶

AsWKT¶

方位角¶

边界圆¶

质心¶

最近点¶

差值¶

Distance¶

Envelope¶

ForcePolygonCW¶

FromWKB¶

FromWKT¶

GeoHash¶

GeometryDistance¶

Intersection¶

IsEmpty¶

IsValid¶

Length¶

LineLocatePoint¶

MakeValid¶

MemSize¶

NumGeometries¶

NumPoints¶

Perimeter¶

PointOnSurface¶

Reverse¶

Scale¶

捕捉到网格¶

对称差¶

Transform¶

Translate¶

Union¶

其他信息

支持 Django！

内容

浏览

你在这里

获取帮助

下载

`Area`¶

`AsGeoJSON`¶

`AsGML`¶

`AsKML`¶

`AsSVG`¶

`AsWKB`¶

`AsWKT`¶

`方位角`¶

`边界圆`¶

`质心`¶

`最近点`¶

`差值`¶

`Distance`¶

`Envelope`¶

`ForcePolygonCW`¶

`FromWKB`¶

`FromWKT`¶

`GeoHash`¶

`GeometryDistance`¶

`Intersection`¶

`IsEmpty`¶

`IsValid`¶

`Length`¶

`LineLocatePoint`¶

`MakeValid`¶

`MemSize`¶

`NumGeometries`¶

`NumPoints`¶

`Perimeter`¶

`PointOnSurface`¶

`Reverse`¶

`Scale`¶

`捕捉到网格`¶

`对称差`¶

`Transform`¶

`Translate`¶

`Union`¶