GeoQuerySet API Reference

class GeoQuerySet([model=None])

Spatial Lookups

就像使用QuerySet API时一样,通过chaining filtersGeoQuerySet进行交互。取代常规Django Field lookups,本节中的空间查找可用于GeometryField

有关简介,请参阅spatial lookups introduction有关与特定空间后端兼容的查找的概述,请参阅spatial lookup compatibility table

bbcontains

可用性:PostGIS,MySQL,SpatiaLite

测试几何字段的边界框是否完全包含查找几何的边界框。

例:

Zipcode.objects.filter(poly__bbcontains=geom)
后端SQL等效
PostGIS geom
MySQLMBRContains(poly, geom)
SpatiaLiteMbrContains(poly, geom)

bboverlaps

可用性:PostGIS,MySQL,SpatiaLite

测试几何字段的边界框是否与查找几何的边界框重叠。

例:

Zipcode.objects.filter(poly__bboverlaps=geom)
后端SQL等效
PostGIS && geom
MySQLMBROverlaps(poly, geom)
SpatiaLiteMbrOverlaps(poly, geom)

contained

可用性:PostGIS,MySQL,SpatiaLite

测试几何字段的边界框是否完全包含在查找几何的边界框中。

例:

Zipcode.objects.filter(poly__contained=geom)
后端SQL等效
PostGIS @ geom
MySQLMBRWithin(poly, geom)
SpatiaLiteMbrWithin(poly, geom)

contains

可用性:PostGIS,Oracle,MySQL,SpatiaLite

测试几何字段在空间上是否包含查找几何。

例:

Zipcode.objects.filter(poly__contains=geom)
后端SQL等效
PostGISST_Contains(poly, geom)
OracleSDO_CONTAINS(poly, geom)
MySQLMBRContains(poly, geom)
SpatiaLite包含(poly, geom)

contains_properly

可用性:PostGIS

如果查找几何与几何字段的内部相交,但不与边界(或外部)相交,则返回true。[4]

例:

Zipcode.objects.filter(poly__contains_properly=geom)
后端SQL等效
PostGISST_ContainsProperly(poly, geom)

coveredby

可用性:PostGIS,Oracle

测试几何字段中没有点在查找几何体之外。[3]

例:

Zipcode.objects.filter(poly__coveredby=geom)
后端SQL等效
PostGISST_CoveredBy(poly, geom)
OracleSDO_COVEREDBY(poly, geom)

covers

可用性:PostGIS,Oracle

测试查找几何中没有点在几何字段之外。[3]

例:

Zipcode.objects.filter(poly__covers=geom)
后端SQL等效
PostGISST_Covers(poly, geom)
OracleSDO_COVERS(poly, geom)

crosses

可用性:PostGIS,SpatiaLite

测试几何字段是否在空间上与查找几何交叉。

例:

Zipcode.objects.filter(poly__crosses=geom)
后端SQL等效
PostGISST_Crosses(poly, geom)
SpatiaLite十字(poly, geom)

disjoint

可用性:PostGIS,Oracle,MySQL,SpatiaLite

测试几何字段是否与查找几何在空间上不相交。

例:

Zipcode.objects.filter(poly__disjoint=geom)
后端SQL等效
PostGISST_Disjoint(poly, geom)
OracleSDO_GEOM.RELATE(poly, 'DISJOINT', geom, 0.05)
MySQLMBRDisjoint(poly, geom)
SpatiaLiteDisjoint(poly, geom)

equals

可用性:PostGIS,Oracle,MySQL,SpatiaLite

exact, same_as

可用性:PostGIS,Oracle,MySQL,SpatiaLite

intersects

可用性:PostGIS,Oracle,MySQL,SpatiaLite

测试几何字段在空间上与查找几何相交。

例:

Zipcode.objects.filter(poly__intersects=geom)
后端SQL等效
PostGISST_Intersects(poly, geom)
OracleSDO_OVERLAPBDYINTERSECT(poly, geom)
MySQLMBRIntersects(poly, geom)
SpatiaLite相交(聚, geom)

overlaps

可用性:PostGIS,Oracle,MySQL,SpatiaLite

relate

可用性:PostGIS,Oracle,SpatiaLite

通过给定模式中给出的值,测试几何字段是否在空间上与查找几何相关。此查找需要tuple参数,(geom, pattern)pattern的形式将取决于空间后端:

PostGIS & SpatiaLite

在这些空间后端上,交叉图案是包括九个字符的串,其定义几何域的内部,边界和外部与查找几何体之间的交叉。交叉图案矩阵只能使用以下字符:12TF*这种查找类型允许用户“微调”与DE-9IM模型一致的特定几何关系。[1]

例:

# A tuple lookup parameter is used to specify the geometry and
# the intersection pattern (the pattern here is for 'contains').
Zipcode.objects.filter(poly__relate=(geom, 'T*T***FF*'))

PostGIS SQL等效:

SELECT ... WHERE ST_Relate(poly, geom, 'T*T***FF*')

SpatiaLite SQL等价物:

SELECT ... WHERE Relate(poly, geom, 'T*T***FF*')

Oracle

Here the relation pattern is comprised at least one of the nine relation strings: TOUCH, OVERLAPBDYDISJOINT, OVERLAPBDYINTERSECT, EQUAL, INSIDE, COVEREDBY, CONTAINS, COVERS, ON, and ANYINTERACT. 多个字符串可以与逻辑布尔运算符OR组合,例如,'inside+touch'[2]关系字符串不区分大小写。

例:

Zipcode.objects.filter(poly__relate=(geom, 'anyinteract'))

Oracle SQL等效:

SELECT ... WHERE SDO_RELATE(poly, geom, 'anyinteract')

touches

可用性:PostGIS,Oracle,MySQL,SpatiaLite

测试几何字段是否在空间上触及查找几何。

例:

Zipcode.objects.filter(poly__touches=geom)
后端SQL等效
PostGISST_Touches(poly, geom)
MySQLMBRTouches(poly, geom)
OracleSDO_TOUCH(poly, geom)
SpatiaLite触摸(聚, geom)

within

可用性:PostGIS,Oracle,MySQL,SpatiaLite

测试几何字段是否在查找几何体内的空间。

例:

Zipcode.objects.filter(poly__within=geom)
后端SQL等效
PostGISST_Within(poly, geom)
MySQLMBRWithin(poly, geom)
OracleSDO_INSIDE(poly, geom)
SpatiaLite在(poly, geom)

left

可用性:PostGIS

测试几何字段的边界框是否严格位于查找几何的边界框的左侧。

例:

Zipcode.objects.filter(poly__left=geom)

PostGIS等效:

SELECT ... WHERE poly << geom

right

可用性:PostGIS

测试几何字段的边界框是否严格位于查找几何的边界框的右侧。

例:

Zipcode.objects.filter(poly__right=geom)

PostGIS等效:

SELECT ... WHERE poly >> geom

overlaps_left

可用性:PostGIS

测试几何字段的边界框是否与查找几何体的边界框的左侧重叠或位于左侧。

例:

Zipcode.objects.filter(poly__overlaps_left=geom)

PostGIS等效:

SELECT ... WHERE poly &< geom

overlaps_right

可用性:PostGIS

测试几何字段的边界框是否与查找几何的边界框的右侧重叠或位于右侧。

例:

Zipcode.objects.filter(poly__overlaps_right=geom)

PostGIS等效:

SELECT ... WHERE poly &> geom

overlaps_above

可用性:PostGIS

测试几何字段的边界框是否与查找几何的边界框重叠或高于其。

例:

Zipcode.objects.filter(poly__overlaps_above=geom)

PostGIS等效:

SELECT ... WHERE poly |&> geom

overlaps_below

可用性:PostGIS

测试几何字段的边界框是否重叠或低于查找几何的边界框。

例:

Zipcode.objects.filter(poly__overlaps_below=geom)

PostGIS等效:

SELECT ... WHERE poly &<| geom

strictly_above

可用性:PostGIS

测试几何字段的边界框是否严格高于查找几何的边界框。

例:

Zipcode.objects.filter(poly__strictly_above=geom)

PostGIS等效:

SELECT ... WHERE poly |>> geom

strictly_below

可用性:PostGIS

测试几何字段的边界框是否严格低于查找几何的边界框。

例:

Zipcode.objects.filter(poly__strictly_below=geom)

PostGIS等效:

SELECT ... WHERE poly <<| geom

Distance Lookups

可用性:PostGIS,Oracle,SpatiaLite

有关执行距离查询的概述,请参阅distance queries introduction

距离查找采用以下形式:

<field>__<distance lookup>=(<geometry>, <distance value>[, 'spheroid'])

传递到距离查找的值是一个元组;前两个值是强制性的,并且是用于计算距离的几何和距离值(以字段为单位的数字或Distance对象)。在每个距离查找上,但是dwithin,可以包括可选的第三元素'spheroid',以便告诉GeoDjango对具有大地测量的字段使用更精确的球体距离计算函数坐标系(例如,将使用ST_Distance_Spheroid而不是ST_Distance_Sphere)。

distance_gt

返回模型,其中距查找几何体的几何字段的距离大于给定的距离值。

例:

Zipcode.objects.filter(poly__distance_gt=(geom, D(m=5)))
后端SQL等效
PostGISST_Distance(poly, geom) &gt; 5
OracleSDO_GEOM.SDO_DISTANCE(poly, geom, 0.05) > 5 t5 >
SpatiaLite距离(poly, geom) > 5

distance_gte

返回模型,其中与查找几何体的几何字段的距离大于或等于给定的距离值。

例:

Zipcode.objects.filter(poly__distance_gte=(geom, D(m=5)))
后端SQL等效
PostGISST_Distance(poly, geom) &gt; = 5
OracleSDO_GEOM.SDO_DISTANCE(poly, geom, 0.05) &gt; = t5>
SpatiaLiteDistance(poly, geom) &gt; = 5

distance_lt

返回模型,其中距查找几何体的几何字段的距离小于给定的距离值。

例:

Zipcode.objects.filter(poly__distance_lt=(geom, D(m=5)))
后端SQL等效
PostGISST_Distance(poly, geom) 5
OracleSDO_GEOM.SDO_DISTANCE(poly, geom, 0.05) 5 t5 >
SpatiaLite距离(poly, geom) 5

distance_lte

返回其中与查找几何体的几何字段的距离小于或等于给定距离值的模型。

例:

Zipcode.objects.filter(poly__distance_lte=(geom, D(m=5)))
后端SQL等效
PostGISST_Distance(poly, geom) 5
OracleSDO_GEOM.SDO_DISTANCE(poly, geom, 0.05) &lt; = t5>
SpatiaLite距离(poly, geom) 5

dwithin

返回模型,其中距查找几何体的几何域的距离在彼此的给定距离内。请注意,如果目标几何图形位于投影系统中,则只能提供Distance对象。对于地理几何,您应使用几何字段的单位(例如,度为WGS84)。

例:

Zipcode.objects.filter(poly__dwithin=(geom, D(m=5)))
后端SQL等效
PostGISST_DWithin(poly, geom, 5)
OracleSDO_WITHIN_DISTANCE(poly, geom, 5)

注意

此查找不适用于SpatiaLite。

GeoQuerySet Methods

GeoQuerySet方法指定对查询集中每个地理字段上的每个空间操作执行空间操作,并将其输出存储在模型上的新属性中(通常是GeoQuerySet方法)。

还有聚合GeoQuerySet方法,它返回单个值而不是查询集。本节将说明GeoDjango中可用的每个GeoQuerySet方法的API和可用性。

注意

可用的方法取决于您的空间后端。有关详细信息,请参阅compatibility table

除了少数例外,以下关键字参数可与所有GeoQuerySet方法一起使用:

关键字参数描述
field_name

默认情况下,GeoQuerySet方法使用模型中遇到的第一个地理字段。当模型中有多个地理字段时,此关键字应用于指定另一个地理字段(例如,field_name='point2')。

在PostGIS上,field_name关键字也可以用于通过ForeignKey关系相关的模型中的几何字段上(例如,field_name='related__point'

model_att

默认情况下,GeoQuerySet方法通常将其输出附加到与GeoQuerySet方法同名的属性中。使用所需的属性名称设置此关键字将覆盖此默认行为。例如,qs = Zipcode.objects.centroid(model_att ='c')每个模型上的c属性中的Zipcode几何字段,而不是centroid属性中的几何字段。

This keyword is required if a method name clashes with an existing GeoQuerySet method – if you wanted to use the area() method on model with a PolygonField named area, for example.

Measurement

可用性:PostGIS,Oracle,SpatiaLite

area

GeoQuerySet.area(**kwargs)

返回此GeoQuerySet的每个元素上的area属性中的地理字段的面积。

distance

GeoQuerySet.distance(geom, **kwargs)

此方法采用几何作为参数,并将distance属性附加到返回查询集中包含距离(作为Distance对象)到给定几何的每个模型。

In the following example (taken from the GeoDjango distance tests), the distance from the Tasmanian city of Hobart to every other PointField in the AustraliaCity queryset is calculated:

>>> pnt = AustraliaCity.objects.get(name='Hobart').point
>>> for city in AustraliaCity.objects.distance(pnt): print(city.name, city.distance)
Wollongong 990071.220408 m
Shellharbour 972804.613941 m
Thirroul 1002334.36351 m
Mittagong 975691.632637 m
Batemans Bay 834342.185561 m
Canberra 598140.268959 m
Melbourne 575337.765042 m
Sydney 1056978.87363 m
Hobart 0.0 m
Adelaide 1162031.83522 m
Hillsdale 1049200.46122 m

注意

由于distance属性是Distance对象,因此您可以轻松地以所选单位表示值。例如,city.distance.mi是以英里为单位的距离值,city.distance.km是以公里为单位的距离值。有关使用详细信息和Supported units的列表,请参阅Measurement Objects

length

GeoQuerySet.length(**kwargs)

返回查询集中每个模型上的length属性(a Distance对象)中的几何字段的长度。

perimeter

GeoQuerySet.perimeter(**kwargs)

返回查询集中每个模型上的perimeter属性(a Distance对象)中的几何字段的周长。

Geometry Relationships

以下方法不带参数,并附加几何对象GeoQuerySet的每个元素,这是在几何字段上评估的关系函数的结果。

centroid

GeoQuerySet.centroid(**kwargs)

可用性:PostGIS,Oracle,SpatiaLite

返回GeoQuerySet的每个元素上centroid属性中地理字段的centroid值。

envelope

GeoQuerySet.envelope(**kwargs)

可用性:PostGIS,SpatiaLite

返回在GeoQuerySet的每个元素上的envelope属性中表示几何字段边界框的几何。

point_on_surface

GeoQuerySet.point_on_surface(**kwargs)

可用性:PostGIS,Oracle,SpatiaLite

返回保证位于查询集的每个元素的point_on_surface属性中几何字段表面上的Point几何图形;否则设置为无。

Geometry Editors

force_rhr

GeoQuerySet.force_rhr(**kwargs)

可用性:PostGIS

返回多边形/多边形的修改版本,其中所有顶点都遵循右手规则,并作为force_rhr属性附加到查询集的每个元素。

reverse_geom

GeoQuerySet.reverse_geom(**kwargs)

可用性:PostGIS,Oracle

反转几何字段的坐标顺序,并作为reverse属性附加到查询集的每个元素。

scale

GeoQuerySet.scale(x, y, z=0.0, **kwargs)

可用性:PostGIS,SpatiaLite

snap_to_grid

GeoQuerySet.snap_to_grid(*args, **kwargs)

将输入几何的所有点都捕捉到网格。几何如何捕捉到网格取决于给定多少数字(float,integer或long)参数。

参数数量描述
1单个尺寸来捕捉X和Y网格。
2用于捕捉网格的X和Y尺寸。
4X,Y尺寸和相应的X,Y原点。

transform

GeoQuerySet.transform(srid=4326, **kwargs)

可用性:PostGIS,Oracle,SpatiaLite

transform方法将模型的几何字段转换为由srid参数指定的空间参考系统。如果未给出srid,则默认使用4326(WGS84)。

注意

与其他GeoQuerySet方法不同,transform存储其输出“in-place”。换句话说,在模型上不存在变换的几何的新属性。

注意

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

例:

>>> qs = Zipcode.objects.all().transform() # Transforms to WGS84
>>> qs = Zipcode.objects.all().transform(32140) # Transforming to "NAD83 / Texas South Central"
>>> print(qs[0].poly.srid)
32140
>>> print(qs[0].poly)
POLYGON ((234055.1698884720099159 4937796.9232223574072123 ...

translate

GeoQuerySet.translate(x, y, z=0.0, **kwargs)

可用性:PostGIS,SpatiaLite

使用给定的数字参数作为偏移将几何字段转换为新位置。

Geometry Operations

可用性:PostGIS,Oracle,SpatiaLite

以下方法都将几何作为参数,并将几何添加到作为操作结果的GeoQuerySet的每个元素。

difference

GeoQuerySet.difference(geom)

GeoQuerySet的每个元素上的difference属性中返回具有给定几何的地理字段的空间差异。

intersection

GeoQuerySet.intersection(geom)

返回GeoQuerySet的每个元素上的intersection属性中的地理字段与给定几何的空间交集。

sym_difference

GeoQuerySet.sym_difference(geom)

GeoQuerySet的每个元素的sym_difference属性中返回具有给定几何的地理字段的对称差异。

union

GeoQuerySet.union(geom)

GeoQuerySet的每个元素上的union属性中返回具有给定几何的地理字段的并集。

Geometry Output

以下GeoQuerySet方法将返回具有转换为所请求的输出格式的每个模型中的geometry字段值的属性。

geohash

GeoQuerySet.geohash(precision=20, **kwargs)

geohash属性附加到包含几何的GeoHash表示的查询集中的每个模型。

geojson

GeoQuerySet.geojson(**kwargs)

可用性:PostGIS,SpatiaLite

geojson属性附加到包含几何的GeoJSON表示的查询集中的每个模型。

关键字参数描述
precision它可以用于指定GeoJSON表示中的坐标的有效数字的数量 - 默认值为8。
crs如果您希望坐标参考系包含在返回的GeoJSON中,请将其设置为True
bbox如果要将边界框包含在返回的GeoJSON中,请将此设置为True

gml

GeoQuerySet.gml(**kwargs)

可用性:PostGIS,Oracle,SpatiaLite

gml属性附加到包含几何的地理标记语言(GML)表示的查询集中的每个模型。

例:

>>> qs = Zipcode.objects.all().gml()
>>> print(qs[0].gml)
<gml:Polygon srsName="EPSG:4326"><gml:OuterBoundaryIs>-147.78711,70.245363 ...  -147.78711,70.245363</gml:OuterBoundaryIs></gml:Polygon>
关键字参数描述
precision此关键字仅适用于PostGIS。它可用于指定GML表示中坐标的有效数字的数量 - 默认值为8。
version此关键字仅适用于PostGIS。它可以用于指定所使用的GML版本,并且可以仅为2或3的值。默认值为2。

kml

GeoQuerySet.kml(**kwargs)

可用性:PostGIS,SpatiaLite

kml属性附加到包含几何字段的锁孔标记语言(KML)表示的查询集中的每个模型。应当注意,如果需要,KML的内容被转换为WGS84。

例:

>>> qs = Zipcode.objects.all().kml()
>>> 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。

svg

GeoQuerySet.svg(**kwargs)

可用性:PostGIS,SpatiaLite

svg属性附加到查询集中包含几何字段的可缩放矢量图形(SVG)路径数据的每个模型。

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

Miscellaneous

mem_size

GeoQuerySet.mem_size(**kwargs)

可用性:PostGIS

返回几何字段在GeoQuerySet的每个元素上的mem_size属性中占用的内存大小(字节数)。

num_geom

GeoQuerySet.num_geom(**kwargs)

可用性:PostGIS,Oracle,SpatiaLite

Returns the number of geometries in a num_geom attribute on each element of the GeoQuerySet if the geometry field is a collection (e.g., a GEOMETRYCOLLECTION or MULTI* field); otherwise sets with None.

num_points

GeoQuerySet.num_points(**kwargs)

可用性:PostGIS,Oracle,SpatiaLite

返回GeoQuerySet的每个元素的num_points属性中几何字段中第一个线串的点数;否则设置为None

Spatial Aggregates

Aggregate Methods

自从1.8版起已弃用:现在已弃用集合方法。喜欢使用他们基于功能的等同物。

collect

GeoQuerySet.collect(**kwargs)

自1.8版起已弃用:请改用Collect聚合。

aggregate(Collect(<field>))的快捷方式。

extent

GeoQuerySet.extent(**kwargs)

自版本1.8后已弃用:改用Extent聚合。

aggregate(Extent(<field>))的快捷方式。

extent3d

GeoQuerySet.extent3d(**kwargs)

自版本1.8后已弃用:改用Extent聚合。

aggregate(Extent3D(<field>))的快捷方式。

make_line

GeoQuerySet.make_line(**kwargs)

自1.8版起已弃用:改用MakeLine聚合。

aggregate(MakeLine(<field>))的快捷方式。

unionagg

GeoQuerySet.unionagg(**kwargs)

自1.8版起已弃用:请改用Union聚合。

aggregate(Union(<field>))的快捷方式。

Aggregate Functions

Django提供一些GIS特定的聚合函数。有关如何使用这些聚合函数的详细信息,请参阅the topic guide on aggregation

关键字参数描述
tolerance此关键字仅适用于Oracle。它是由SDOAGGRTYPE过程使用的公差值; Oracle文档有更多详细信息。

例:

>>> from django.contrib.gis.db.models import Extent, Union
>>> WorldBorder.objects.aggregate(Extent('mpoly'), Union('mpoly'))

Collect

class Collect(geo_field)

可用性:PostGIS,Spatialite(≥3.0)

从几何列返回GEOMETRYCOLLECTIONMULTI几何对象。这类似于Union聚合的简化版本,除了它可以比执行并集快几个数量级,因为它只是将几何卷积为集合或多对象,而不关心解决边界。

Extent

class Extent(geo_field)

可用性:PostGIS,Oracle,Spatialite(≥3.0)

QuerySet中的所有geo_field的范围返回为四元组,包括左下坐标和右上坐标。

例:

>>> qs = City.objects.filter(name__in=('Houston', 'Dallas')).aggregate(Extent('poly'))
>>> print(qs[poly__extent])
(-96.8016128540039, 29.7633724212646, -95.3631439208984, 32.782058715820)

Extent3D

class Extent3D(geo_field)

可用性:PostGIS

QuerySet中的所有geo_field的3D范围作为六元组返回,包括左下坐标和右上坐标(每个坐标都具有x,y和z坐标) 。

例:

>>> qs = City.objects.filter(name__in=('Houston', 'Dallas')).aggregate(Extent3D('poly'))
>>> print(qs[poly__extent3d])
(-96.8016128540039, 29.7633724212646, 0, -95.3631439208984, 32.782058715820, 0)

MakeLine

class MakeLine(geo_field)

可用性:PostGIS

Returns a LineString constructed from the point field geometries in the QuerySet. 目前,订购查询集没有任何效果。

例:

>>> print(City.objects.filter(name__in=('Houston', 'Dallas')
...      ).aggregate(MakeLine('poly'))[poly__makeline]
LINESTRING (-95.3631510000000020 29.7633739999999989, -96.8016109999999941 32.7820570000000018)

Union

class Union(geo_field)

可用性:PostGIS,Oracle,SpatiaLite

此方法返回一个GEOSGeometry对象,其中包含查询集中每个几何的并集。请注意,使用Union是处理器密集型,可能需要大量的时间在大查询集。

注意

如果使用此方法的计算时间过于昂贵,请考虑使用Collect

例:

>>> u = Zipcode.objects.aggregate(Union(poly))  # This may take a long time.
>>> u = Zipcode.objects.filter(poly__within=bbox).aggregate(Union(poly))  # A more sensible approach.

脚注

[1]请参阅 OpenGIS SQL简单功能规范2.1.13.2,p。 2-13(尺寸扩展九相交模型)。
[2]请参阅 SDO_RELATE文档Oracle Spatial用户指南和手册“11。
[3]12有关此程序的说明,请阅读“包含空间谓词 Martin Davis(PostGIS开发人员)。
[4]有关详细信息,请参阅PostGIS ST_ContainsProperly 文档