djangodocs

Django 1.10
Português (Brasil)
Documentation contents

Geographic Database Functions

The functions documented on this page allow users to access geographic database functions to be used in annotations, aggregations, or filters in Django.

Exemplo

Code
>>> 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.

Sumário de funções:

Measurement

Relacionamentos

Operações

Editores

Formato de saída

Variados

Area

BoundingCircle

Difference

ForceRHR

AsGeoJSON

IsValid

Distance

Centroid

Intersection

MakeValid

AsGML

MemSize

Length

Envelope

SymDifference

Reverse

AsKML

NumGeometries

Perimeter

PointOnSurface

Union

Scale

AsSVG

NumPoints

SnapToGrid

GeoHash

Transform

Translate

Área

class Area(expression, **extra)

Availability: MySQL, Oracle, PostGIS, SpatiaLite

Accepts a single geographic field or expression and returns the area of the field as an Area measure. On MySQL, a raw float value is returned, as it’s not possible to automatically determine the unit of the field.

AsGeoJSON

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

Availability: 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.

Exemplo

Code
>>> City.objects.annotate(json=AsGeoJSON('point')).get(name='Chicago').json
{"type":"Point","coordinates":[-87.65018,41.85039]}

Keyword Argument

Descrição

bbox

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

crs

Set this to True if you want the coordinate reference system to be included in the returned GeoJSON.

precision

It may be used to specify the number of significant digits for the coordinates in the GeoJSON representation – the default value is 8.

AsGML

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

Availability: PostGIS, SpatiaLite

Accepts a single geographic field or expression and returns a Geographic Markup Language (GML) representation of the geometry.

Exemplo

Code
>>> 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

Descrição

precision

Specifies the number of significant digits for the coordinates in the GML representation – the default value is 8.

version

Specifies the GML version to use: 2 (default) or 3.

AsKML

class AsKML(expression, precision=8, **extra)

Availability: PostGIS, SpatiaLite

Accepts a single geographic field or expression and returns a Keyhole Markup Language (KML) representation of the geometry.

Exemplo

Code
>>> 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

Descrição

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.

AsSVG

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

Availability: PostGIS, SpatiaLite

Accepts a single geographic field or expression and returns a Scalable Vector Graphics (SVG) representation of the geometry.

Keyword Argument

Descrição

relative

If set to True, the path data will be implemented in terms of relative moves. Defaults to False, meaning that absolute moves are used instead.

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.

BoundingCircle

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

Availability: PostGIS

Accepts a single geographic field or expression and returns the smallest circle polygon that can fully contain the geometry.

Centroid

class Centroid(expression, **extra)

Disponibilidade: MySQL, PostGIS, Oracle, SpatiaLite

Aceita um único campo geográfico ou expressão e retorna o valor do cetróide de uma geometria.

Difference

class Difference(expr1, expr2, **extra)

Availability: MySQL (≥ 5.6.1), 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

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

Availability: MySQL (≥ 5.6.1), 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, as it’s not possible to automatically determine the unit of the field.

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_Distance_Sphere 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 resource-intensive) or on a spheroid (more accurate, more resource-intensive).

In the following example, the distance from the city of Hobart to every other PointField in the AustraliaCity queryset is calculated:

Code
>>> 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
...

Envelope

class Envelope(expression, **extra)

Availability: MySQL, PostGIS, SpatiaLite

Accepts a single geographic field or expression and returns the geometry representing the bounding box of the geometry.

ForceRHR

class ForceRHR(expression, **extra)

Availability: PostGIS

Accepts a single geographic field or expression and returns a modified version of the polygon/multipolygon in which all of the vertices follow the right-hand rule.

GeoHash

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

Availability: PostGIS, SpatiaLite (≥ 4.0, 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.

Intersection

class Intersection(expr1, expr2, **extra)

Availability: MySQL (≥ 5.6.1), PostGIS, Oracle, SpatiaLite

Accepts two geographic fields or expressions and returns the geometric intersection between them.

IsValid

class IsValid(expr)

Availability: PostGIS

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

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

Availability: MySQL, Oracle, PostGIS, SpatiaLite

Accepts a single geographic linestring or multilinestring field or expression and returns its length as an Distance measure. On MySQL, a raw float value is returned, as it’s not possible to automatically determine the unit of the field.

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 resource-intensive) or on a spheroid (more accurate, more resource-intensive) with the spheroid keyword argument.

MakeValid

class MakeValid(expr)

Availability: PostGIS

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

class 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

class NumGeometries(expression, **extra)

Disponibilidade: 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); otherwise returns None.

NumPoints

class NumPoints(expression, **extra)

Disponibilidade: MySQL, PostGIS, Oracle, SpatiaLite

Accepts a single geographic field or expression and returns the number of points in the first linestring in the geometry field; otherwise returns None.

Perimeter

class Perimeter(expression, **extra)

Availability: PostGIS, Oracle, SpatiaLite (≥ 4.0)

Accepts a single geographic field or expression and returns the perimeter of the geometry field as a Distance object.

PointOnSurface

class PointOnSurface(expression, **extra)

Availability: PostGIS, 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

class Reverse(expression, **extra)

Availability: PostGIS, Oracle, SpatiaLite (≥ 4.0)

Accepts a single geographic field or expression and returns a geometry with reversed coordinates.

Scale

class 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

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

Availability: PostGIS, SpatiaLite (≥ 3.1)

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

Descrição

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

class SymDifference(expr1, expr2, **extra)

Availability: MySQL (≥ 5.6.1), PostGIS, Oracle, SpatiaLite

Accepts two geographic fields or expressions and returns the geometric symmetric difference (union without the intersection) between the given parameters.

Transform

class 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.

Translate

class 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.

Union

class Union(expr1, expr2, **extra)

Availability: MySQL (≥ 5.6.1), PostGIS, Oracle, SpatiaLite

Accepts two geographic fields or expressions and returns the union of both geometries.

This page as Markdown JSON

Edit this page on GitHub Official version