The functions documented on this page allow users to access geographic database functions to be used in annotations, aggregations, or filters in Django.
举例:
>>> from django.contrib.gis.db.models.functions import Length
>>> Track.objects.annotate(length=Length('line')).filter(length__gt=100)
Not all backends support all functions, so refer to the documentation of each
function to see if your database backend supports the function you want to use.
If you call a geographic function on a backend that doesn't support it, you'll
get a NotImplementedError
exception.
Function's summary:
Measurement  关系映射  Operations  Editors  Output format  杂项 

Area

Azimuth

Difference

ForcePolygonCW

AsGeoJSON

IsValid

Distance

BoundingCircle

Intersection

MakeValid

AsGML

MemSize

GeometryDistance

Centroid

SymDifference

Reverse

AsKML

NumGeometries

Length

Envelope

Union

Scale

AsSVG

NumPoints

Perimeter

LineLocatePoint

SnapToGrid

AsWKB


PointOnSurface

Transform

AsWKT


Translate

GeoHash

Area
Area
(expression, **extra)Availability: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite
Accepts a single geographic field or expression and returns the area of the
field as an Area
measure.
MySQL and SpatiaLite without LWGEOM don't support area calculations on geographic SRSes.
AsGeoJSON
AsGeoJSON
(expression, bbox=False, crs=False, precision=8, **extra)Availability: MariaDB (≥ 10.2.4), MySQL (≥ 5.7.5), Oracle, PostGIS, SpatiaLite
Accepts a single geographic field or expression and returns a GeoJSON representation of the geometry. Note that the result
is not a complete GeoJSON structure but only the geometry
key content of a
GeoJSON structure. See also GeoJSON Serializer.
举例:
>>> City.objects.annotate(json=AsGeoJSON('point')).get(name='Chicago').json
{"type":"Point","coordinates":[87.65018,41.85039]}
Keyword Argument  描述 

bbox

Set this to True if you want the bounding box
to be included in the returned GeoJSON. Ignored on Oracle. 
crs

Set this to True if you want the coordinate
reference system to be included in the returned GeoJSON. Ignored on MySQL and Oracle. 
precision

It may be used to specify the number of significant
digits for the coordinates in the GeoJSON representation  the default value is 8. Ignored on Oracle. 
Oracle support was added.
AsGML
AsGML
(expression, version=2, precision=8, **extra)Availability: Oracle, PostGIS, SpatiaLite
Accepts a single geographic field or expression and returns a [https://en.wikipedia.org/wiki/Geography_Markup_Language Geographic Markup Language (GML)] representation of the geometry.
举例:
>>> 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>
Keyword Argument  描述 

precision

Specifies the number of significant digits for the
coordinates in the GML representation  the default value is 8. Ignored on Oracle. 
version

Specifies the GML version to use: 2 (default) or 3. 
AsKML
AsKML
(expression, precision=8, **extra)Availability: PostGIS, SpatiaLite
Accepts a single geographic field or expression and returns a [https://developers.google.com/kml/documentation/ Keyhole Markup Language (KML)] representation of the geometry.
举例:
>>> 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>
Keyword Argument  描述 

precision

This keyword may be used to specify the number of
significant digits for the coordinates in the KML representation  the default value is 8. 
The undocumented version
parameter was removed.
AsSVG
AsSVG
(expression, relative=False, precision=8, **extra)Availability: PostGIS, SpatiaLite
Accepts a single geographic field or expression and returns a [https://www.w3.org/Graphics/SVG/ Scalable Vector Graphics (SVG)] representation of the geometry.
Keyword Argument  描述 

relative

If set to True , the path data will be implemented
in terms of relative moves. Defaults to 
precision

This keyword may be used to specify the number of
significant digits for the coordinates in the SVG representation  the default value is 8. 
AsWKB
AsWKB
(expression, **extra)
Availability: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite
Accepts a single geographic field or expression and returns a [https://en.wikipedia.org/wiki/Wellknown_text_representation_of_geometry#Wellknown_binary Wellknown binary (WKB)] representation of the geometry.
举例:
>>> bytes(City.objects.annotate(wkb=AsWKB('point')).get(name='Chelyabinsk').wkb)
b'\x01\x01\x00\x00\x00]3\xf9f\x9b\[email protected]\x00X\x1d9\xd2\[email protected]'
AsWKT
AsWKT
(expression, **extra)
Availability: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite
Accepts a single geographic field or expression and returns a [https://en.wikipedia.org/wiki/Wellknown_text_representation_of_geometry Wellknown text (WKT)] representation of the geometry.
举例:
>>> City.objects.annotate(wkt=AsWKT('point')).get(name='Chelyabinsk').wkt
'POINT (55.137555 61.451728)'
Azimuth
Azimuth
(point_a, point_b, **extra)Availability: PostGIS, SpatiaLite (LWGEOM)
Returns the azimuth in radians of the segment defined by the given point
geometries, or None
if the two points are coincident. The azimuth is angle
referenced from north and is positive clockwise: north = 0
; east = π/2
;
south = π
; west = 3π/2
.
BoundingCircle
BoundingCircle
(expression, num_seg=48, **extra)Accepts a single geographic field or expression and returns the smallest circle polygon that can fully contain the geometry.
The num_seg
parameter is used only on PostGIS.
Centroid
Centroid
(expression, **extra)Availability: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite
Accepts a single geographic field or expression and returns the centroid
value of the geometry.
Difference
Difference
(expr1, expr2, **extra)Availability: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite
Accepts two geographic fields or expressions and returns the geometric difference, that is the part of geometry A that does not intersect with geometry B.
Distance
Distance
(expr1, expr2, spheroid=None, **extra)Availability: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite
Accepts two geographic fields or expressions and returns the distance between
them, as a Distance
object. On MySQL, a raw
float value is returned when the coordinates are geodetic.
On backends that support distance calculation on geodetic coordinates, the proper backend function is automatically chosen depending on the SRID value of the geometries (e.g. ST_DistanceSphere on PostGIS).
When distances are calculated with geodetic (angular) coordinates, as is the
case with the default WGS84 (4326) SRID, you can set the spheroid
keyword
argument to decide if the calculation should be based on a simple sphere (less
accurate, less resourceintensive) or on a spheroid (more accurate, more
resourceintensive).
In the following example, the distance from the city of Hobart to every other
PointField
in the AustraliaCity
queryset is calculated:
>>> 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
...
注解
Because the distance
attribute is a
Distance
object, you can easily express
the value in the units of your choice. For example, city.distance.mi
is
the distance value in miles and city.distance.km
is the distance value
in kilometers. See Measurement Objects for usage details and the list of
Supported units.
Envelope
Envelope
(expression, **extra)Availability: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite
Accepts a single geographic field or expression and returns the geometry representing the bounding box of the geometry.
ForcePolygonCW
ForcePolygonCW
(expression, **extra)Availability: PostGIS, SpatiaLite
Accepts a single geographic field or expression and returns a modified version of the polygon/multipolygon in which all exterior rings are oriented clockwise and all interior rings are oriented counterclockwise. Nonpolygonal geometries are returned unchanged.
GeoHash
GeoHash
(expression, precision=None, **extra)Availability: MySQL (≥ 5.7.5), PostGIS, SpatiaLite (LWGEOM)
Accepts a single geographic field or expression and returns a GeoHash representation of the geometry.
The precision
keyword argument controls the number of characters in the
result.
GeometryDistance
GeometryDistance
(expr1, expr2, **extra)
Availability: PostGIS
Accepts two geographic fields or expressions and returns the distance between
them. When used in an order_by()
clause,
it provides indexassisted nearestneighbor result sets.
Intersection
Intersection
(expr1, expr2, **extra)Availability: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite
Accepts two geographic fields or expressions and returns the geometric intersection between them.
IsValid
IsValid
(expr)Availability: MySQL (≥ 5.7.5), PostGIS, Oracle, SpatiaLite (LWGEOM)
Accepts a geographic field or expression and tests if the value is well formed.
Returns True
if its value is a valid geometry and False
otherwise.
Length
Length
(expression, spheroid=True, **extra)Availability: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite
Accepts a single geographic linestring or multilinestring field or expression
and returns its length as a Distance
measure.
On PostGIS and SpatiaLite, when the coordinates are geodetic (angular), you can
specify if the calculation should be based on a simple sphere (less
accurate, less resourceintensive) or on a spheroid (more accurate, more
resourceintensive) with the spheroid
keyword argument.
MySQL doesn't support length calculations on geographic SRSes.
LineLocatePoint
LineLocatePoint
(linestring, point, **extra)Availability: PostGIS, SpatiaLite
Returns a float between 0 and 1 representing the location of the closest point on
linestring
to the given point
, as a fraction of the 2D line length.
MakeValid
MakeValid
(expr)Availability: PostGIS, SpatiaLite (LWGEOM)
Accepts a geographic field or expression and attempts to convert the value into a valid geometry without losing any of the input vertices. Geometries that are already valid are returned without changes. Simple polygons might become a multipolygon and the result might be of lower dimension than the input.
MemSize
MemSize
(expression, **extra)Availability: PostGIS
Accepts a single geographic field or expression and returns the memory size (number of bytes) that the geometry field takes.
NumGeometries
NumGeometries
(expression, **extra)Availability: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite
Accepts a single geographic field or expression and returns the number of
geometries if the geometry field is a collection (e.g., a GEOMETRYCOLLECTION
or MULTI*
field). Returns 1 for single geometries.
On MySQL, returns None
for single geometries.
NumPoints
NumPoints
(expression, **extra)Availability: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite
Accepts a single geographic field or expression and returns the number of points in a geometry.
On MySQL, returns None
for any nonLINESTRING
geometry.
Perimeter
Perimeter
(expression, **extra)Availability: PostGIS, Oracle, SpatiaLite
Accepts a single geographic field or expression and returns the perimeter of the
geometry field as a Distance
object.
PointOnSurface
PointOnSurface
(expression, **extra)Availability: PostGIS, MariaDB, Oracle, SpatiaLite
Accepts a single geographic field or expression and returns a Point
geometry
guaranteed to lie on the surface of the field; otherwise returns None
.
Reverse
Reverse
(expression, **extra)Availability: PostGIS, Oracle, SpatiaLite
Accepts a single geographic field or expression and returns a geometry with reversed coordinates.
Scale
Scale
(expression, x, y, z=0.0, **extra)Availability: PostGIS, SpatiaLite
Accepts a single geographic field or expression and returns a geometry with
scaled coordinates by multiplying them with the x
, y
, and optionally
z
parameters.
SnapToGrid
SnapToGrid
(expression, *args, **extra)Availability: PostGIS, SpatiaLite
Accepts a single geographic field or expression and returns a geometry with all points snapped to the given grid. How the geometry is snapped to the grid depends on how many numeric (either float, integer, or long) arguments are given.
Number of Arguments  描述 

1  A single size to snap both the X and Y grids to. 
2  X and Y sizes to snap the grid to. 
4  X, Y sizes and the corresponding X, Y origins. 
SymDifference
SymDifference
(expr1, expr2, **extra)Availability: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite
Accepts two geographic fields or expressions and returns the geometric symmetric difference (union without the intersection) between the given parameters.
Transform
Transform
(expression, srid, **extra)Availability: PostGIS, Oracle, SpatiaLite
Accepts a geographic field or expression and a SRID integer code, and returns
the transformed geometry to the spatial reference system specified by the
srid
parameter.
注解
What spatial reference system an integer SRID corresponds to may depend on the spatial database used. In other words, the SRID numbers used for Oracle are not necessarily the same as those used by PostGIS.
Translate
Translate
(expression, x, y, z=0.0, **extra)Availability: PostGIS, SpatiaLite
Accepts a single geographic field or expression and returns a geometry with
its coordinates offset by the x
, y
, and optionally z
numeric
parameters.