Las funciones documentadas en esta página permiten a los usuarios acceder a funciones de bases de datos geográficas para usar en anotaciones, agregaciones o filtros en Django.

Ejemplo:

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

No todos los backends admiten todas las funciones, así que consulte la documentación de cada función para ver si el backend de su base de datos admite la función que desea utilizar. Si llama a una función geográfica en un backend que no la admite, obtendrá un NotImplementedError excepción.

Resumen de la función:

Medición Relaciones Operaciones Editores Formato de salida Diverso
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

class Area(expression, **extra)

Disponibilidad: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Acepta un solo campo geográfico o expresión y devuelve el área del campo como un Area la medida.

MySQL y SpatiaLite sin LWGEOM no admiten cálculos de área en SRS geográficos.

AsGeoJSON

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

Disponibilidad: MariaDB (≥ 10,2,4), MySQL (≥ 5.7.5), Oracle, PostGIS, SpatiaLite

Acepta un solo campo geográfico o expresión y devuelve un GeoJSON representación de la geometría. Tenga en cuenta que el resultado no es una estructura GeoJSON completa, sino solo el geometry contenido clave de una estructura GeoJSON. Ver también Serializador GeoJSON.

Ejemplo:

>>> City.objects.annotate(json=AsGeoJSON('point')).get(name='Chicago').json
"type":"Point","coordinates":[-87.65018,41.85039]
Argumento de palabra clave Descripción
bbox Establezca esto en True si desea que el cuadro delimitador se incluya en el GeoJSON devuelto. Ignorado en Oracle.
crs Establezca esto en True si desea que el sistema de referencia de coordenadas se incluya en el GeoJSON devuelto. Ignorado en MySQL y Oracle.
precision Puede usarse para especificar el número de dígitos significativos para las coordenadas en la representación de GeoJSON; el valor predeterminado es 8. Ignorado en Oracle.

Cambiado en Django 3.1:

Se agregó soporte de Oracle.

AsGML

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

Disponibilidad: Oracle, PostGIS, SpatiaLite

Acepta un solo campo geográfico o expresión y devuelve un Lenguaje de marcado geográfico (GML) representación de la geometría.

Ejemplo:

>>> 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>
Argumento de palabra clave Descripción
precision Especifica el número de dígitos significativos para las coordenadas en la representación GML; el valor predeterminado es 8. Ignorado en Oracle.
version Especifica la versión de GML que se utilizará: 2 (predeterminado) o 3.

AsKML

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

Disponibilidad: PostGIS, SpatiaLite

Acepta un solo campo geográfico o expresión y devuelve un Lenguaje de marcado Keyhole (KML) representación de la geometría.

Ejemplo:

>>> 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>
Argumento de palabra clave Descripción
precision Esta palabra clave se puede utilizar para especificar la cantidad de dígitos significativos para las coordenadas en la representación KML; el valor predeterminado es 8.

Cambiado en Django 3.1:

Los indocumentados version se eliminó el parámetro.

AsSVG

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

Disponibilidad: PostGIS, SpatiaLite

Acepta un solo campo geográfico o expresión y devuelve un Gráficos vectoriales escalables (SVG) representación de la geometría.

Argumento de palabra clave Descripción
relative Si se establece en True, los datos de la ruta se implementarán en términos de movimientos relativos. Predeterminado a False, lo que significa que en su lugar se utilizan movimientos absolutos.
precision Esta palabra clave se puede utilizar para especificar el número de dígitos significativos para las coordenadas en la representación SVG; el valor predeterminado es 8.

AsWKB

class AsWKB(expression, **extra)

Nuevo en Django 3.1.

Disponibilidad: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Acepta un solo campo geográfico o expresión y devuelve un Binario conocido (WKB) representación de la geometría.

Ejemplo:

>>>bytes(City.objects.annotate(wkb=AsWKB('point')).get(name='Chelyabinsk').wkb)b'x01x01x00x00x00]3xf9fx9b[email protected]x00Xx1d9xd2[email protected]'

AsWKT

class AsWKT(expression, **extra)

Nuevo en Django 3.1.

Disponibilidad: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Acepta un solo campo geográfico o expresión y devuelve un Texto conocido (WKT) representación de la geometría.

Ejemplo:

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

Azimuth

class Azimuth(point_a, point_b, **extra)

Disponibilidad: PostGIS, SpatiaLite (LWGEOM)

Devuelve el acimut en radianes del segmento definido por las geometrías de puntos dadas, o None si los dos puntos coinciden. El acimut es el ángulo referenciado desde el norte y es positivo en el sentido de las agujas del reloj: norte = 0; este = π/2; sur = π; oeste = 3π/2.

BoundingCircle

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

Disponibilidad: PostGIS, Oráculo

Acepta un solo campo geográfico o expresión y devuelve el polígono circular más pequeño que puede contener completamente la geometría.

los num_seg El parámetro se usa solo en PostGIS.

Centroid

class Centroid(expression, **extra)

Disponibilidad: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Acepta un solo campo geográfico o expresión y devuelve el centroid valor de la geometría.

Difference

class Difference(expr1, expr2, **extra)

Disponibilidad: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Acepta dos campos o expresiones geográficas y devuelve la diferencia geométrica, que es la parte de la geometría A que no se cruza con la geometría B.

Distance

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

Disponibilidad: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Acepta dos campos geográficos o expresiones y devuelve la distancia entre ellos, como un Distance objeto. En MySQL, se devuelve un valor flotante sin procesar cuando las coordenadas son geodésicas.

En los backends que admiten el cálculo de la distancia en coordenadas geodésicas, la función de backend adecuada se elige automáticamente según el valor SRID de las geometrías (p. Ej. ST_DistanceSphere en PostGIS).

Cuando las distancias se calculan con coordenadas geodésicas (angulares), como es el caso con el SRID WGS84 (4326) predeterminado, puede establecer la spheroid argumento de palabra clave para decidir si el cálculo debe basarse en una esfera simple (menos precisa, menos intensiva en recursos) o en un esferoide (más precisa, más intensiva en recursos).

En el siguiente ejemplo, la distancia entre la ciudad de Hobart y las demás PointField en el AustraliaCity queryset se calcula:

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

Nota

Porque el distance atributo es un Distance objeto, puede expresar fácilmente el valor en las unidades que elija. Por ejemplo, city.distance.mi es el valor de la distancia en millas y city.distance.km es el valor de la distancia en kilómetros. Ver Objetos de medida para obtener detalles de uso y la lista de Unidades compatibles.

Envelope

class Envelope(expression, **extra)

Disponibilidad: MariaDB, MySQL, Oráculo, PostGIS, SpatiaLite

Acepta una expresión o un campo geográfico único y devuelve la geometría que representa el cuadro delimitador de la geometría.

ForcePolygonCW

class ForcePolygonCW(expression, **extra)

Disponibilidad: PostGIS, SpatiaLite

Acepta un solo campo geográfico o expresión y devuelve una versión modificada del polígono / multipolígono en el que todos los anillos exteriores están orientados en el sentido de las agujas del reloj y todos los anillos interiores están orientados en el sentido contrario a las agujas del reloj. Las geometrías no poligonales se devuelven sin cambios.

GeoHash

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

Disponibilidad: MySQL (≥ 5,7,5), PostGIS, SpatiaLite (LWGEOM)

Acepta un solo campo geográfico o expresión y devuelve un GeoHash representación de la geometría.

los precision El argumento de palabra clave controla el número de caracteres en el resultado.

GeometryDistance

class GeometryDistance(expr1, expr2, **extra)

Disponibilidad: PostGIS

Acepta dos campos geográficos o expresiones y devuelve la distancia entre ellos. Cuando se usa en un order_by() cláusula, proporciona conjuntos de resultados de vecinos más cercanos asistidos por índices.

Intersection

class Intersection(expr1, expr2, **extra)

Disponibilidad: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Acepta dos campos geográficos o expresiones y devuelve la intersección geométrica entre ellos.

IsValid

class IsValid(expr)

Disponibilidad: MySQL (≥ 5,7,5), PostGIS, Oracle, SpatiaLite (LWGEOM)

Acepta una expresión o campo geográfico y prueba si el valor está bien formado. Devoluciones True si su valor es una geometría válida y False de lo contrario.

Length

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

Disponibilidad: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Acepta una única expresión o campo de cadena de líneas geográficas o multilínea y devuelve su longitud como un Distance la medida.

En PostGIS y SpatiaLite, cuando las coordenadas son geodésicas (angulares), puede especificar si el cálculo debe basarse en una esfera simple (menos precisa, menos intensiva en recursos) o en un esferoide (más precisa, más intensiva en recursos) con los spheroid argumento de palabra clave.

MySQL no admite cálculos de longitud en SRS geográficos.

LineLocatePoint

class LineLocatePoint(linestring, point, **extra)

Disponibilidad: PostGIS, SpatiaLite

Devuelve un flotador entre 0 y 1 que representa la ubicación del punto más cercano en linestring a lo dado point, como una fracción de la longitud de la línea 2D.

MakeValid

class MakeValid(expr)

Disponibilidad: PostGIS, SpatiaLite (LWGEOM)

Acepta una expresión o un campo geográfico e intenta convertir el valor en una geometría válida sin perder ninguno de los vértices de entrada. Las geometrías que ya son válidas se devuelven sin cambios. Los polígonos simples pueden convertirse en un multipolígono y el resultado puede ser de menor dimensión que la entrada.

MemSize

class MemSize(expression, **extra)

Disponibilidad: PostGIS

Acepta un solo campo geográfico o expresión y devuelve el tamaño de memoria (número de bytes) que ocupa el campo de geometría.

NumGeometries

class NumGeometries(expression, **extra)

Disponibilidad: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Acepta un solo campo geográfico o expresión y devuelve el número de geometrías si el campo de geometría es una colección (p. Ej., Un GEOMETRYCOLLECTION o MULTI* campo). Devuelve 1 para geometrías individuales.

En MySQL, devuelve None para geometrías simples.

NumPoints

class NumPoints(expression, **extra)

Disponibilidad: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Acepta un solo campo geográfico o expresión y devuelve el número de puntos de una geometría.

En MySQL, devuelve None para cualquier noLINESTRING geometría.

Perimeter

class Perimeter(expression, **extra)

Disponibilidad: PostGIS, Oracle, SpatiaLite

Acepta un solo campo geográfico o expresión y devuelve el perímetro del campo de geometría como un Distance objeto.

PointOnSurface

class PointOnSurface(expression, **extra)

Disponibilidad: PostGIS, MariaDB, Oracle, SpatiaLite

Acepta un solo campo geográfico o expresión y devuelve un Point geometría garantizada para reposar en la superficie del campo; de lo contrario regresa None.

Reverse

class Reverse(expression, **extra)

Disponibilidad: PostGIS, Oracle, SpatiaLite

Acepta un solo campo geográfico o expresión y devuelve una geometría con coordenadas invertidas.

Scale

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

Disponibilidad: PostGIS, SpatiaLite

Acepta un solo campo geográfico o expresión y devuelve una geometría con coordenadas escaladas multiplicándolas con el x, yy opcionalmente z parámetros.

SnapToGrid

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

Disponibilidad: PostGIS, SpatiaLite

Acepta un solo campo geográfico o expresión y devuelve una geometría con todos los puntos ajustados a la cuadrícula dada. La forma en que se ajusta la geometría a la cuadrícula depende de cuántos argumentos numéricos (flotantes, enteros o largos) se den.

Número de argumentos Descripción
1 Un solo tamaño para ajustar las cuadrículas X e Y.
2 Tamaños X e Y para ajustar la cuadrícula.
4 Tamaños X, Y y los correspondientes orígenes X, Y.

SymDifference

class SymDifference(expr1, expr2, **extra)

Disponibilidad: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Acepta dos campos geográficos o expresiones y devuelve la diferencia simétrica geométrica (unión sin intersección) entre los parámetros dados.

Transform

class Transform(expression, srid, **extra)

Disponibilidad: PostGIS, Oracle, SpatiaLite

Acepta un campo geográfico o expresión y un código entero SRID y devuelve la geometría transformada al sistema de referencia espacial especificado por el srid parámetro.

Nota

El sistema de referencia espacial al que corresponde un SRID entero puede depender de la base de datos espacial utilizada. En otras palabras, los números SRID utilizados para Oracle no son necesariamente los mismos que los utilizados por PostGIS.

Translate

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

Disponibilidad: PostGIS, SpatiaLite

Acepta un solo campo geográfico o expresión y devuelve una geometría con sus coordenadas desplazadas por el x, yy opcionalmente z parámetros numéricos.

Union

class Union(expr1, expr2, **extra)

Disponibilidad: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Acepta dos campos geográficos o expresiones y devuelve la unión de ambas geometrías.