API de modèle de GeoDjango¶
Ce document présente les détails de l’API de modèle de GeoDjango. Tout au long de cette section, nous allons utiliser le modèle géographique suivant d’un code ZIP et d’un modèle d’élévation numérique en tant qu’exemples :
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()
Types de champs spatiaux¶
Les champs spatiaux consistent en une série de types de champs géométriques et en un type de champ matriciel. Chaque type de champ géométrique correspond à la spécification OpenGIS Simple Features [1]. Il n’existe pas de standard équivalent pour les données matricielles.
Options de champs spatiaux¶
Les options de champs géométriques srid et spatial_index sont maintenant partagées par GeometryField et RasterField à travers BaseSpatialField.
En plus des Options des champs disponibles habituellement pour les champs de modèles Django, les champs spatiaux possèdent les options supplémentaires suivantes. Toutes sont facultatives.
srid¶
-
BaseSpatialField.srid¶
Définit le SRID [2] (Spatial Reference System Identity) du champ géométrique à la valeur indiquée. La valeur par défaut est 4326 (aussi connue sous le nom WGS84, les unités étant en degrés de longitude et de latitude).
Choix d’un SRID¶
Le choix d’un SRID approprié pour un modèle est une décision importante que le développeur doit considérer attentivement. Le SRID est un nombre entier correspondant au système de projection qui sera utilisé pour interpréter les données de la base de données spatiale. [3] Les systèmes de projection donne le contexte des coordonnées qui définissent un emplacement. Même si les détails de la géodesie dépassent le périmètre de cette documentation, le problème général est que la Terre est sphérique et que les représentations de la Terre (par ex. les cartes papier, les cartes Web) ne le sont pas.
La plupart des gens connaissent l’utilisation de la latitude et de la longitude pour faire référence à un emplacement sur la surface de la Terre. Cependant, la latitude et la longitude sont des angles, pas des distances. En d’autres termes, alors que le chemin le plus court entre deux points sur une surface plane est une ligne droite, le chemin le plus court entre deux points sur une surface courbe (telle que la Terre) est un arc d’un grand cercle. [4] Il est donc nécessaire de procéder à des calculs supplémentaires pour obtenir les distances en unités planaires (kilomètres ou milles). L’emploi d’un système de coordonnées géographique peut introduire par la suite des complications pour le développeur. Par exemple, SpatiaLite ne peut pas calculer des distances entre des géométries exprimées en système de coordonnées géographique. Par exemple, construire une requête pour trouver tous les points à mois de 5 kilomètres des frontières d’un département stocké sous forme de coordonnées WGS84. [5]
Des portions de la surface terrestre peuvent être projetées sur un plan bidimensionnel ou cartésien. Les systèmes de coordonnées projetés sont particulièrement adaptés pour les applications spécifiques à une région. Par exemple , si vous savez que votre base de données ne contiendra que des objets géométriques du Kansas du Nord, il est envisageable d’utiliser un système de projection spécifique à cette région. De plus, les systèmes de coordonnées projetés sont définis en unités cartésiennes (telles que les mètres ou les pieds) qui facilitent le calcul des distances.
Note
Si vous souhaitez effectuer des requêtes de distance arbitraires avec des objets géométriques autres que des points en WSG84 avec PostGIS, avec des performances décentes, définissez le mot-clé GeometryField.geography afin que le type de données geography soit utilisé.
Ressources supplémentaires :
spatialreference.org: une base de données programmée en Django de systèmes de références spatiales.
The State Plane Coordinate System: un site Web présentant les divers systèmes de projection utilisés aux États-Unis. La plupart des données spatiales américaines existantes sont dans l’un de ces systèmes de coordonnées plutôt que dans un système de coordonnées géographique tel que WGS84.
spatial_index¶
-
BaseSpatialField.spatial_index¶
La valeur par défaut est True. Crée un index spatial pour le champ géométrique donné.
Note
C’est différent de l’option de champ db_index car les index spatiaux sont créés de façon différente des index normaux de base de données. En particulier, les index spatiaux sont généralement créés en utilisant une variante de R-Tree alors que les index normaux utilisent généralement l’algorithme B-Tree.
Options de champs géométriques¶
Les champs géométriques disposent d’options supplémentaires. Toutes les options suivantes sont facultatives.
dim¶
-
GeometryField.dim¶
Cette option peut être utilisée pour personnaliser les dimensions de coordonnées du champ géométrique. Par défaut, il y a deux dimensions pour représenter des objets géométrique en 2D. Pour les moteurs spatiaux qui le gèrent, il est possible de définir cette option à 3 pour la prise en charge de la 3D.
Note
Pour l’instant, seul le moteur spatial PostGIS prend en charge la 3D.
geography¶
-
GeometryField.geography¶
Si définie à True, cette option crée une colonne de base de données de type géographique plutôt que géométrique. Référez-vous à la section type géographique ci-dessous pour plus de détails.
Note
La prise en charge du type géographique nécessite PostGIS et force le SRID à 4326.
Type géographique¶
Le type géographique fournit une prise en charge native des objets spatiaux représentés par des coordonnées géographiques (par ex. longitude/latitude WGS84). [6] Au contraire du plan utilisé par un type géométrique, le type géographique utilise une représentation sphérique de ses données. Les opérations de distance et de mesure effectuées sur une colonne géographique utilisent automatiquement des calculs sur les arcs de grands cercles et renvoient des unités linéaires. En d’autres termes, lorsque ST_Distance est appelée sur deux éléments de type géographique, une valeur en mètres est renvoyée (contrairement aux valeurs en degrés renvoyées lors de calculs sur des colonnes de type géométrique en WGS84).
Comme les calculs géographiques induisent plus d’opérations mathématiques, seul un sous-ensemble des recherches spatiales PostGIS sont disponibles pour le type géographique. En pratique, cela signifie qu’en plus des recherches de distance, seules les recherches spatiales supplémentaires suivantes sont disponibles pour les colonnes de type géographique :
Si vous avez besoin d’utiliser une requête ou un agrégat spatial qui ne prend pas en charge le type géographique en entrée, il est possible de faire appel à la fonction de base de données Cast pour convertir la colonne géographique en type géométrique dans la requête :
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)
Pour plus d’informations, la documentation PostGIS contient une section instructive sur la façon de déterminer quand utiliser le type de données géographique au lieu d’un type géométrique.
GeoManager¶
Le gestionnaire GeoManager est obligatoire afin de pouvoir utiliser les Méthodes GeoQuerySet dépréciées.
Obsolète depuis la version 1.9: Toutes les méthodes GeoQuerySet ont été rendues obsolètes et remplacées par des fonctions de base de données équivalentes. Dès que les anciennes méthodes auront été remplacées dans votre code, il est alors possible d’enlever le gestionnaire spécial GeoManager de vos classes de modèles géographiques.
Dans les anciennes versions, le gestionnaire était obligatoire pour effectuer des requêtes géographiques. Sans lui, tous les filtres géographiques échouaient.
GeoManager était nécessaire même si le modèle ne possédait pas lui-même de champ géographique, par exemple dans le cas d’une relation avec une clé ForeignKey vers un modèle ayant un champ géographique. Par exemple, si nous avions un modèle Address avec un champ ForeignKey vers le modèle Zipcode:
from django.contrib.gis.db import models
class Address(models.Model):
num = models.IntegerField()
street = models.CharField(max_length=100)
city = models.CharField(max_length=100)
state = models.CharField(max_length=2)
zipcode = models.ForeignKey(Zipcode, on_delete=models.CASCADE)
objects = models.GeoManager()
Le gestionnaire géographique était nécessaire pour effectuer des requêtes spatiales concernant des objets Zipcode liés, par exemple :
qs = Address.objects.filter(zipcode__poly__contains='POINT(-104.590948 38.319914)')
Notes de bas de page
| [1] | OpenGIS Consortium, Inc., Simple Feature Specification For SQL. |
| [2] | Ibid., chap. 2.3.8, p. 39 (Geometry Values and Spatial Reference Systems). |
| [3] | Les nombres entiers SRID correspondent typiquement aux identifiants EPSG (European Petroleum Survey Group). Cependant, ils peuvent aussi être associés à des projections personnalisées définies dans la table des systèmes de référence spatiale de la base de données spatiale. |
| [4] | Terry A. Slocum, Robert B. McMaster, Fritz C. Kessler et Hugh H. Howard, Thematic Cartography and Geographic Visualization (Prentice Hall, 2e édition), chap. 7.1.3. |
| [5] | Cette restriction ne s’applique pas à PostGIS. |
| [6] | Veuillez vous référer à la documentation du type géographique de PostGIS pour plus de détails. |
