API de modèle de GeoDjango

This document explores the details of the GeoDjango Model API. Throughout this section, we’ll be using the following geographic model of a ZIP code and of a Digital Elevation Model as our examples:

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[source]

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

PointField

class PointField[source]

Stocke un Point.

LineStringField

class LineStringField[source]

Stocke une LineString.

PolygonField

class PolygonField[source]

Stocke un Polygon.

MultiPointField

class MultiPointField[source]

Stocke un MultiPoint.

MultiLineStringField

class MultiLineStringField[source]

Stocke une MultiLineString.

MultiPolygonField

class MultiPolygonField[source]

Stocke un MultiPolygon.

GeometryCollectionField

class GeometryCollectionField[source]

Stocke une GeometryCollection.

RasterField

class RasterField[source]

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

Choosing an appropriate SRID for your model is an important decision that the developer should consider carefully. The SRID is an integer specifier that corresponds to the projection system that will be used to interpret the data in the spatial database. [3] Projection systems give the context to the coordinates that specify a location. Although the details of geodesy are beyond the scope of this documentation, the general problem is that the earth is spherical and representations of the earth (e.g., paper maps, web maps) are not.

Most people are familiar with using latitude and longitude to reference a location on the earth’s surface. However, latitude and longitude are angles, not distances. In other words, while the shortest path between two points on a flat surface is a straight line, the shortest path between two points on a curved surface (such as the earth) is an arc of a great circle. [4]

Thus, additional computation is required to obtain distances in planar units (e.g., kilometers and miles). Using a geographic coordinate system may introduce complications for the developer later on. For example, SpatiaLite does not have the capability to perform distance calculations between geometries using geographic coordinate systems, e.g. constructing a query to find all points within 5 miles of a county boundary stored as WGS84. [5]

Portions of the earth’s surface may projected onto a two-dimensional, or Cartesian, plane. Projected coordinate systems are especially convenient for region-specific applications, e.g., if you know that your database will only cover geometries in North Kansas, then you may consider using projection system specific to that region. Moreover, projected coordinate systems are defined in Cartesian units (such as meters or feet), easing distance calculations.

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: A website covering the various projection systems used in the United States. Much of the U.S. spatial data encountered will be in one of these coordinate systems rather than in a geographic coordinate system such as WGS84.

spatial_index

BaseSpatialField.spatial_index

Defaults to True. Creates a spatial index for the given geometry field.

Note

This is different from the db_index field option because spatial indexes are created in a different manner than regular database indexes. Specifically, spatial indexes are typically created using a variant of the R-Tree, while regular database indexes typically use B-Trees.

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

This option may be used for customizing the coordinate dimension of the geometry field. By default, it is set to 2, for representing two-dimensional geometries. For spatial backends that support it, it may be set to 3 for three-dimensional support.

Note

Pour l’instant, seuls les moteurs spatiaux PostGIS et SpatiaLite prennent en charge la 3D.

geography

GeometryField.geography

If set to True, this option will create a database column of type geography, rather than geometry. Please refer to the geography type section below for more details.

Note

La prise en charge du type géographique nécessite PostGIS et force le SRID à 4326.

Type géographique

The geography type provides native support for spatial features represented with geographic coordinates (e.g., WGS84 longitude/latitude). [6] Unlike the plane used by a geometry type, the geography type uses a spherical representation of its data. Distance and measurement operations performed on a geography column automatically employ great circle arc calculations and return linear units. In other words, when ST_Distance is called on two geographies, a value in meters is returned (as opposed to degrees if called on a geometry column in 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
)

For more information, the PostGIS documentation contains a helpful section on determining when to use geography data type over geometry data type.

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]

Typically, SRID integer corresponds to an EPSG (European Petroleum Survey Group) identifier. However, it may also be associated with custom projections defined in spatial database’s spatial reference systems table.

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