地理数据库函数 — Django 文档

来自菜鸟教程
Django/docs/2.2.x/ref/contrib/gis/functions
跳转至:导航、​搜索

地理数据库函数

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

例子:

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

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

功能总结:

测量 关系 操作 编辑器 输出格式 杂项
Area Azimuth Difference ForcePolygonCW AsGeoJSON IsValid
Distance BoundingCircle Intersection ForceRHR AsGML MemSize
Length Centroid SymDifference MakeValid AsKML NumGeometries
Perimeter Envelope Union Reverse AsSVG NumPoints
LineLocatePoint Scale GeoHash
PointOnSurface SnapToGrid
Transform
Translate

Area

class Area(expression, **extra)

可用性MySQL、Oracle、PostGIS、SpatiaLite

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

没有 LWGEOM 的 MySQL 和 SpatiaLite 不支持地理 SRS 上的面积计算。


AsGeoJSON

class AsGeoJSON(expression, bbox=False, crs=False, precision=8, **extra)

可用性MySQL (≥ 5.7.5)、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
crs 如果您希望坐标参考系统包含在返回的 GeoJSON 中,请将其设置为 True。 在 MySQL 上忽略。
precision 它可用于指定 GeoJSON 表示中坐标的有效位数——默认值为 8。


AsGML

class AsGML(expression, version=2, precision=8, **extra)

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

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

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

可用性PostGIS,SpatiaLite

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

关键字参数 描述
relative 如果设置为True,路径数据将按照相对移动来实现。 默认为 False,表示使用绝对移动。
precision 此关键字可用于指定 SVG 表示中坐标的有效位数 - 默认值为 8。


Azimuth

class Azimuth(point_a, point_b, **extra)

可用性PostGIS,SpatiaLite (LWGEOM)

返回由给定点几何定义的线段的弧度方位角,如果两个点重合,则返回 None。 方位角是以北为参考的角度,顺时针为正:北 = 0; 东 = π/2; 南 = π; 西 = 3π/2


BoundingCircle

class BoundingCircle(expression, num_seg=48, **extra)

可用性PostGISOracle

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

num_seg 参数仅用于 PostGIS。


Centroid

class Centroid(expression, **extra)

可用性MySQLPostGIS、Oracle、SpatiaLite

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


Difference

class Difference(expr1, expr2, **extra)

可用性MySQLPostGIS、Oracle、SpatiaLite

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


Distance

class Distance(expr1, expr2, spheroid=None, **extra)

可用性MySQLPostGIS、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)

可用性MySQLOraclePostGIS、SpatiaLite

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

2.2 版更改: 添加了 Oracle 支持。


ForcePolygonCW

class ForcePolygonCW(expression, **extra)

2.1 版中的新功能。


可用性PostGIS,SpatiaLite

接受单个地理字段或表达式,并返回多边形/多多边形的修改版本,其中所有外环顺时针方向,所有内环逆时针方向。 非多边形几何图形返回不变。


ForceRHR

class ForceRHR(expression, **extra)

自 2.1 版起已弃用: 改用 ForcePolygonCW


可用性PostGIS

接受单个地理字段或表达式并返回多边形/多多边形的修改版本,其中所有顶点都遵循右手规则。


GeoHash

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

可用性MySQL (≥ 5.7.5)、PostGIS、SpatiaLite (LWGEOM)

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

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


Intersection

class Intersection(expr1, expr2, **extra)

可用性MySQLPostGIS、Oracle、SpatiaLite

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


IsValid

class IsValid(expr)

可用性MySQL (≥ 5.7.5)、PostGIS、Oracle、SpatiaLite (LWGEOM)

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


Length

class Length(expression, spheroid=True, **extra)

可用性MySQL、Oracle、PostGIS、SpatiaLite

接受单个地理线串或多线串字段或表达式,并将其长度作为 距离 度量返回。

在 PostGIS 和 SpatiaLite 上,当坐标为大地测量(角度)时,您可以指定计算是基于简单球体(精度较低,资源密集型较少)还是基于椭球体(更准确,资源密集型)与spheroid 关键字参数。

MySQL 不支持地理 SRS 的长度计算。


LineLocatePoint

class LineLocatePoint(linestring, point, **extra)

可用性PostGIS,SpatiaLite

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


MakeValid

class MakeValid(expr)

可用性PostGIS,SpatiaLite (LWGEOM)

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


MemSize

class MemSize(expression, **extra)

可用性PostGIS

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


NumGeometries

class NumGeometries(expression, **extra)

可用性MySQLPostGIS、Oracle、SpatiaLite

如果几何字段是一个集合(例如,GEOMETRYCOLLECTIONMULTI* 字段),则接受单个地理字段或表达式并返回几何的数量。 对于单个几何图形返回 1。

在 MySQL 上,为单个几何返回 None


NumPoints

class NumPoints(expression, **extra)

可用性MySQLPostGIS、Oracle、SpatiaLite

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

在 MySQL 上,为任何非 LINESTRING 几何返回 None


Perimeter

class Perimeter(expression, **extra)

可用性PostGIS、Oracle、SpatiaLite

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


PointOnSurface

class PointOnSurface(expression, **extra)

可用性PostGIS、Oracle、SpatiaLite

接受单个地理字段或表达式,并返回一个 Point 几何图形,保证位于该字段的表面上; 否则返回 None


Reverse

class Reverse(expression, **extra)

可用性PostGIS、Oracle、SpatiaLite

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


Scale

class Scale(expression, x, y, z=0.0, **extra)

可用性PostGIS,SpatiaLite

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


SnapToGrid

class SnapToGrid(expression, *args, **extra)

可用性PostGIS,SpatiaLite

接受单个地理字段或表达式,并返回所有点都对齐到给定网格的几何图形。 几何体如何捕捉到网格取决于给出的数字(浮点数、整数或长整型)参数的数量。

参数数量 描述
1 将 X 和 Y 网格捕捉到的单一尺寸。
2 将网格捕捉到的 X 和 Y 尺寸。
4 X、Y 尺寸和相应的 X、Y 原点。


SymDifference

class SymDifference(expr1, expr2, **extra)

可用性MySQLPostGIS、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

接受单个地理字段或表达式,并返回其坐标偏移 xy 和可选的 z 数字参数的几何。


Union

class Union(expr1, expr2, **extra)

可用性MySQLPostGIS、Oracle、SpatiaLite

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