# Documentation Django 6.0.7

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

### `GeometryField`

class GeometryField

La classe de base pour les champs de type géométrique.

### `PointField`

class PointField

Stocke un `Point`.

### `LineStringField`

class LineStringField

Stocke une `LineString`.

### `PolygonField`

class PolygonField

Stocke un `Polygon`.

### `MultiPointField`

class MultiPointField

Stocke un `MultiPoint`.

### `MultiLineStringField`

class MultiLineStringField

Stocke une `MultiLineString`.

### `MultiPolygonField`

class MultiPolygonField

Stocke un `MultiPolygon`.

### `GeometryCollectionField`

class GeometryCollectionField

Stocke une `GeometryCollection`.

### `RasterField`

class RasterField

Stocke un `GDALRaster`.

`RasterField` n’est actuellement implémenté que pour le moteur PostGIS.

## Options de champs spatiaux

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 ont l’habitude d’utiliser latitude et longitude pour situer 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 plate est une ligne droite, le chemin le plus court entre deux points sur une surface bombée (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: A database of spatial reference systems.

- 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, seuls les moteurs spatiaux PostGIS et SpatiaLite prennent 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.

### `max_geom_collections`

GeometryField.max_geom_collections

New in Django 5.2.17.

This option is forwarded to the `form field` generated for this model field, bounding how many geometry collections may be contained in submitted WKB/WKT inputs before raising `ValueError`. Since spatial field assignments are lazy, it is also checked when values are accessed, e.g. when saving an instance, but not when read from a database. It defaults to `198`.

#### 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 :

- `bboverlaps`

- `coveredby`

- `covers`

- `intersects`

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.

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.