Este documento explora los detalles de la API del modelo GeoDjango. A lo largo de esta sección, estaremos utilizando el siguiente modelo geográfico de un código postal y de un Modelo de Elevación Digital como nuestros ejemplos:
from django.contrib.gis.db import models
class Zipcode(models.Model):
code = models.CharField(max_length=5)
poly = models.PolygonField()
class Elevation(models.Model):
name = models.CharField(max_length=100)
rast = models.RasterField()
Los campos espaciales consisten en una serie de tipos de campo geométricos y uno tipo de campo raster. Cada uno de los tipos de campo geométrico corresponde a la especificación OpenGIS Simple Features [1]. No existe tal estándar para datos raster.
La clase base para campos de geometría.
Campo de Punto¶Almacena un Point.
Campo de Línea String¶Almacena un LineString.
Campo de Polígono¶Almacena un Polygon.
Campo de Multipuntos¶Almacena un MultiPoint.
Campo de MultiLínea String¶Almacena un MultiLineString.
Campo de Multipolígono¶Almacena un MultiPolygon.
Campo de Colección Geométrica¶Almacena un GeometryCollection.
RasterField¶Almacena un GDALRaster.
RasterField se implementa actualmente solo para el backend de PostGIS.
Además de las opciones regulares Opciones del campo disponibles para los campos de modelo Django, los campos espaciales tienen las siguientes opciones adicionales. Todas son opcionales.
Establece el SRID [2] (Identidad del Sistema de Referencia Espacial) del campo de geometría al valor dado. Por defecto es 4326 (también conocido como WGS84, las unidades son grados de longitud y latitud).
La elección del SRID adecuado para tu modelo es una decisión importante que el desarrollador debe considerar con cuidado. El SRID es un especificador de entero que corresponde al sistema de proyección que se utilizará para interpretar los datos en la base de datos espacial. Los sistemas de proyección dan contexto a las coordenadas que especifican una ubicación. Aunque los detalles del geodesia están más allá del alcance de esta documentación, el problema general es que la Tierra es esférica y las representaciones de la Tierra (por ejemplo, mapas de papel, mapas web) no lo son.
La mayoría de las personas están familiarizadas con utilizar latitud y longitud para referenciar una ubicación en la superficie terrestre. Sin embargo, la latitud y la longitud son ángulos, no distancias. En otras palabras, mientras que el camino más corto entre dos puntos en una superficie plana es una línea recta, el camino más corto entre dos puntos en una superficie curva (como la Tierra) es un arco de un gran círculo. [4] Por lo tanto, se requiere cálculo adicional para obtener distancias en unidades planas (por ejemplo, kilómetros y millas). El uso de un sistema de coordenadas geográficas puede introducir complicaciones para el desarrollador más adelante. Por ejemplo, SpatiaLite no tiene la capacidad de realizar cálculos de distancia entre geometrías utilizando sistemas de coordenadas geográficos, por ejemplo, construir una consulta para encontrar todos los puntos dentro de 5 millas de un límite del condado almacenado como WGS84. [5]
Partes de la superficie terrestre pueden proyectarse en un plano bidimensional o cartesiano. Los sistemas de coordenadas proyectados son especialmente convenientes para aplicaciones regionales específicas, por ejemplo, si sabes que tu base de datos solo cubrirá geometrías en Norte de Kansas, entonces puedes considerar utilizar el sistema de proyección específico de esa región. Además, los sistemas de coordenadas proyectados se definen en unidades cartesianas (como metros o pies), lo que facilita los cálculos de distancia.
Nota
Si deseas realizar consultas de distancia arbitrarias utilizando geometrías no punteadas en WGS84 en PostGIS y quieres una buena rendimiento, habilita la palabra clave GeometryField.geography para que se utilice el tipo de base de datos geography database type en lugar de.
Recursos adicionales:
spatialreference.org: Una base de datos Django que gestiona sistemas de referencia espaciales.
El Sistema de Coordenadas del Estado: Un sitio web que cubre los diversos sistemas de proyección utilizados en los Estados Unidos. Mucha de la información espacial encontrada en EE.UU. estará en uno de estos sistemas de coordenadas en lugar de estar en un sistema de coordenadas geográficas como WGS84.
spatial_index¶Por defecto, se establece en True. Crea un índice espacial para el campo de geometría dado.
Nota
Esto es diferente a la opción del campo db_index porque los índices espaciales se crean de una manera diferente que los índices de base de datos regulares. Específicamente, los índices espaciales suelen crearse utilizando una variante de la R-Tree, mientras que los índices de base de datos regulares suelen utilizar B-Trees.
Hay opciones adicionales disponibles para los campos de geometría. Todas las siguientes opciones son opcionales.
dim¶Esta opción se puede utilizar para personalizar la dimensión de coordenadas del campo de geometría. Por defecto, está establecido en 2, para representar geometrías bidimensionales. Para backends espaciales que lo soporten, puede estar establecido en 3 para el soporte tridimensional.
Nota
En la actualidad, el soporte 3D está limitado a los backends PostGIS y SpatiaLite.
geografía¶Si se establece en True, esta opción creará una columna de base de datos del tipo geografía, en lugar de geometría. Consulte la sección a continuación para obtener más detalles sobre el tipo de geografía.
Nota
El soporte para geografías está limitado a PostGIS y obligará al SRID a ser 4326.
El tipo de geografía proporciona un soporte nativo para características espaciales representadas con coordenadas geográficas (por ejemplo, WGS84 longitud/latitud). [6] A diferencia del plano utilizado por el tipo de geometría, el tipo de geografía utiliza una representación esférica de sus datos. Las operaciones de distancia y medida realizadas en una columna de geografía utilizan automáticamente cálculos de arco circular grande y devuelven unidades lineales. En otras palabras, cuando se llama a ST_Distance sobre dos geografías, se devuelve un valor en metros (en lugar de grados si se llama a una columna de geometría en WGS84).
Dado que las calculaciones de geografía involucran más matemáticas, solo está disponible un subconjunto de los consultas espaciales de PostGIS para el tipo de geografía. En la práctica, esto significa que además de las consultas de distancia se pueden utilizar las siguientes consultas espaciales adicionales en columnas de geografía:
Si necesita usar una consulta o función agregada espacial que no admite el tipo de geografía como entrada, puede utilizar la función de base de datos Cast para convertir la columna de geografía a un tipo de geometría en la consulta:
from django.contrib.gis.db.models import PointField
from django.db.models.functions import Cast
Zipcode.objects.annotate(geom=Cast("geography_field", PointField())).filter(
geom__within=poly
)
Para obtener más información, la documentación de PostGIS contiene una sección útil sobre determinar cuándo usar el tipo de dato geografía en lugar del tipo de dato geometría.
Notas al pie
may 31, 2026