# Documentation Django 6.0.7

# Fonctions de base de données géographiques

Les fonctions documentées sur cette page permettent aux utilisateurs d’accéder aux fonctions géographiques de bases de données utilisables dans les annotations, les agrégations ou les filtres avec Django.

Exemple :

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

Tous les moteurs ne supportent pas forcément toutes les fonctions, référez-vous donc à la documentation de chaque fonction pour voir si votre moteur de base de données prend en charge la fonction que vous souhaitez utiliser. Si vous appelez une fonction géographique sur un moteur qui ne le gère pas, vous obtiendrez une exception `NotImplementedError`.

## Mesures

### `Area`

class Area(expression, **extra)

Disponibilité : MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Accepte un seul champ ou expression géographique et renvoie l’aire du champ sous forme de mesure `Area`.

MySQL et SpatiaLite sans LWGEOM/RTTOPO ne prennent pas en charge les calculs d’aire sur des objets à système de référence géographique.

### `Distance`

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

Disponibilité : MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Accepte deux champs ou expressions géographiques et renvoie la distance entre les deux sous forme d’objet `Distance`. Avec MySQL, un nombre à virgule est renvoyé lorsque les coordonnées sont de type géodétique.

Pour les bases de données qui permettent de calculer des distances avec des coordonnées géodésiques, la bonne fonction de base de données est automatiquement sélectionnée en fonction de la valeur SRID des objets géométriques (par ex. ST_DistanceSphere avec PostGIS).

Lorsque les distances sont calculées avec des coordonnées géodésiques (angles), comme c’est le cas avec le SRID WGS84 (4326) par défaut, vous pouvez définir le paramètre nommé `spheroid` pour décider si le calcul doit se faire selon une sphère simple (moins précis, moins gourmand en ressources) ou sur un sphéroïde (plus précis, plus gourmand en ressources).

Dans l’exemple suivant, on calcule la distance entre la ville de Hobart vers tous les autres champs `PointField` du jeu de requête `AustraliaCity`:

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

Note

Comme l’attribut `distance` est un objet `Distance`, il est facile d’exprimer cette valeur dans l’unité de son choix. Par exemple, `city.distance.mi` est la valeur de distance en milles et `city.distance.km` est la valeur de distance en kilomètres. Consultez Objets de mesure pour des détails d’utilisation et la liste des Unités prises en charge.

### `GeometryDistance`

class GeometryDistance(expr1, expr2, **extra)

Disponibilité : PostGIS

Accepte deux champs ou expressions géographiques et renvoie la distance entre les deux. Lorsqu’on l’utilise dans une clause `order_by()`, elle fournit des jeux de résultats selon le plus proche voisin sur la base des index.

### `Length`

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

Disponibilité : MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Accepte un seul champ ou expression ligne ou multiligne géographique et renvoie sa longueur sous forme de mesure `Distance`.

Avec PostGIS ou SpatiaLite, et lorsque les coordonnées sont géodésiques (angles), vous pouvez définir avec le paramètre nommé `spheroid` si le calcul doit se faire selon une sphère simple (moins précis, moins gourmand en ressources) ou sur un sphéroïde (plus précis, plus gourmand en ressources).

MySQL ne prend pas en charge les calculs de longueur sur des objets à système de référence géographique.

### `Perimeter`

class Perimeter(expression, **extra)

Disponibilité : PostGIS, Oracle, SpatiaLite

Accepte un seul champ ou expression géographique et renvoie le périmètre du champ sous forme de mesure `Distance`.

## Relations

### `Azimuth`

class Azimuth(point_a, point_b, **extra)

Disponibilité : PostGIS, SpatiaLite (LWGEOM/RTTOPO)

Renvoie l’azimuth en radians du segment défini par les points géométriques donnés, ou `None` si les deux points coïncident. L’azimuth est un angle partant du nord et est positif dans le sens horaire : nord = `0`; est = `π/2`; sud = `π`; ouest = `3π/2`.

### `BoundingCircle`

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

Disponibilité : PostGIS, Oracle, SpatiaLite 5.1+

Accepte un seul champ ou expression géographique et renvoie le polygone cercle le plus petit pouvant contenir entièrement l’objet géométrique.

Le paramètre `num_seg` et utilisé uniquement avec PostGIS.

### `Centroid`

class Centroid(expression, **extra)

Disponibilité : MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Accepte un seul champ ou expression géographique et renvoie la valeur centroïde de l’objet géométrique.

### `ClosestPoint`

class ClosestPoint(expr1, expr2, **extra)

Disponibilité : PostGIS, SpatiaLite

Accepte deux champs ou expressions géographiques et renvoie le point 2D de la géométrie A le plus proche de la géométrie B.

### `Envelope`

class Envelope(expression, **extra)

Disponibilité : MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Accepte un seul champ ou expression géographique et renvoie l’objet géométrique représentant le rectangle englobant de l’objet.

### `LineLocatePoint`

class LineLocatePoint(linestring, point, **extra)

Disponibilité : PostGIS, SpatiaLite

Renvoie un nombre à virgule entre 0 et 1 représentant l’emplacement du point de `linestring` le plus proche du `point` indiqué, sous forme de fraction de la longueur de la ligne 2D.

### `PointOnSurface`

class PointOnSurface(expression, **extra)

Disponibilité : PostGIS, MariaDB, Oracle, SpatiaLite

Accepte un seul champ ou expression géographique et renvoie un objet `Point` qui se trouve avec certitude dans la surface du champ ; sinon renvoie `None`.

## Opérations

### `Difference`

class Difference(expr1, expr2, **extra)

Disponibilité : MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Accepte deux champs ou expressions géographiques et renvoie la différence géométrique, c’est-à-dire la part de l’objet A qui ne fait pas partie de son intersection avec l’objet B.

### `Intersection`

class Intersection(expr1, expr2, **extra)

Disponibilité : MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Accepte deux champs ou expressions géographiques et renvoie leur intersection géométrique.

### `SymDifference`

class SymDifference(expr1, expr2, **extra)

Disponibilité : MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Accepte deux champs ou expressions géographiques et renvoie la différence géométrique symétrique (union sans l’intersection) entre les paramètres données.

### `Union`

class Union(expr1, expr2, **extra)

Disponibilité : MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Accepte deux champs ou expressions géographiques et renvoie l’union des deux.

## Modifications

### `ForcePolygonCW`

class ForcePolygonCW(expression, **extra)

Disponibilité : PostGIS, SpatiaLite

Accepte un seul champ ou expression géographique et renvoie une version modifiée du (multi)polygone pour lequel tous les chemins extérieurs sont orientés dans le sens horaire et tous les chemins intérieurs sont orientés dans le sens antihoraire. Les géométries qui ne sont pas des polygones sont renvoyées inchangées.

### `MakeValid`

class MakeValid(expr)

Disponibilité : PostGIS, SpatiaLite (LWGEOM/RTTOPO)

Accepte un champ ou une expression géographique et essaye de convertir la valeur en une géométrie valide sans perdre aucun des segments originaux. Les objets déjà valides sont renvoyés tels quels. Des polygones simples peuvent devenir des multipolygones et le résultat peut être d’une dimension inférieure à l’objet en entrée.

### `Reverse`

class Reverse(expression, **extra)

Disponibilité : PostGIS, Oracle, SpatiaLite

Accepte un seul champ ou expression géographique et renvoie un objet géométrique avec les coordonnées inversées.

### `Rotate`

New in Django 6.0.

class Rotate(expression, angle, origin=None, **extra)

Disponibilité : PostGIS

Effectue une rotation géométrique selon un `angle` indiqué autour de l’origine. En option, la rotation peut se faire autour d’un point défini par le paramètre `origin`.

### `Scale`

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

Disponibilité : PostGIS, SpatiaLite

Accepte un seul champ ou expression géographique et renvoie un objet géométrique avec ses coordonnées mises à l’échelle en les multipliant par les paramètres `x`, `y` et facultativement, `z`.

### `SnapToGrid`

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

Disponibilité : PostGIS, SpatiaLite

Accepte un seul champ ou expression géographique et renvoie un objet géométrique dont tous les points sont ajustés à la grille donnée. La manière d’ajuster l’objet géométrique à la grille dépend du nombre de paramètres numériques fournis (des nombres à virgule, entiers ou entiers longs).

Nombre de paramètres | Description
--- | ---
1 | Une seule taille de cellule de grille (à la fois pour la taille X et Y).
2 | Tailles X et Y de cellule de grille.
4 | Tailles de cellule X et Y ainsi que coordonnées X et Y de l’origine de la grille.

### `Transform`

class Transform(expression, srid, **extra)

Disponibilité : PostGIS, Oracle, SpatiaLite

Accepte un champ ou expression géographique et un code SRID nombre entier, et renvoie l’objet géométrique transformé dans le système de référence spatiale indiqué par le paramètre `srid`.

Note

La correspondance entre les numéros de SRID et les systèmes de référence spatiale peut dépendre du moteur spatial utilisé. Par exemple, les numéros SRID utilisés par Oracle ne sont pas forcément les mêmes que ceux utilisés par PostGIS.

### `Translate`

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

Disponibilité : PostGIS, SpatiaLite

Accepte un seul champ ou expression géographique et renvoie un objet géométrique avec ses coordonnées décalées en fonction des paramètres `x`, `y` et facultativement, `z`.

## Format d’entrée

### `FromWKB`

class FromWKB(expression, srid=0, **extra)

Disponibilité : MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Crée un objet géométrique à partir d’une représentation WKB (Well-known binary). L’argument facultatif `srid` permet d’indiquer la valeur SRID de l’objet géométrique résultant. `srid` est ignoré avec Oracle.

### `FromWKT`

class FromWKT(expression, srid=0, **extra)

Disponibilité : MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Crée un objet géométrique à partir d’une représentation WKT (Well-known text). L’argument facultatif `srid` permet d’indiquer la valeur SRID de l’objet géométrique résultant. `srid` est ignoré avec Oracle.

## Format de sortie

### `AsGeoJSON`

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

Disponibilité : MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Accepte un seul champ ou expression géographique et renvoie une représentation GeoJSON de l’objet géométrique. Notez que le résultat ne constitue pas une structure GeoJSON complète, mais seulement le contenu de la clé `geometry` d’une structure GeoJSON. Voir aussi Sérialisation GeoJSON.

Exemple :

    >>> City.objects.annotate(json=AsGeoJSON("point")).get(name="Chicago").json
    {"type":"Point","coordinates":[-87.65018,41.85039]}

Paramètre nommé | Description
--- | ---
`bbox` | À définir à `True` pour que le rectangle englobant soit inclus dans le contenu GeoJSON renvoyé. Ignoré avec Oracle.
`crs` | À définir à `True` pour que le système de référence de coordonnées soit inclus dans le format GeoJSON renvoyé. Ignoré avec MySQL et Oracle.
`precision` | Peut être utilisé pour indiquer le nombre de chiffres significatifs des coordonnées de la représentation GeoJSON, la valeur par défaut étant 8. Ignoré avec Oracle.

### `AsGML`

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

Disponibilité : Oracle, PostGIS, SpatiaLite

Accepte un seul champ ou expression géographique et renvoie une représentation Geographic Markup Language (GML) du champ géométrique.

Exemple :

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

Paramètre nommé | Description
--- | ---
`precision` | Indique le nombre de chiffres significatifs des coordonnées de la représentation GML, la valeur par défaut étant 8. Ignoré avec Oracle.
`version` | Indique la version GML à utiliser : 2 (par défaut) ou 3.

### `AsKML`

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

Disponibilité : PostGIS, SpatiaLite

Accepte un seul champ ou expression géographique et renvoie une représentation Keyhole Markup Language (KML) du champ géométrique.

Exemple :

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

Paramètre nommé | Description
--- | ---
`precision` | Ce paramètre peut être utilisé pour indiquer le nombre de chiffres significatifs des coordonnées de la représentation KML, la valeur par défaut étant 8.

### `AsSVG`

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

Disponibilité : PostGIS, SpatiaLite

Accepte un seul champ ou expression géographique et renvoie une représentation Scalable Vector Graphics (SVG) du champ géométrique.

Paramètre nommé | Description
--- | ---
`relative` | Si défini à `True`, les données de chemin sont représentées en termes de déplacements relatifs. La valeur par défaut est `False` ce qui signifie que ce sont les déplacements absolus qui sont utilisés.
`precision` | Ce paramètre peut être utilisé pour indiquer le nombre de chiffres significatifs des coordonnées de la représentation SVG, la valeur par défaut étant 8.

### `AsWKB`

class AsWKB(expression, **extra)

Disponibilité : MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Accepte un seul champ ou expression géographique et renvoie une représentation WKB (Well-known binary) du champ géométrique.

Exemple :

    >>> bytes(City.objects.annotate(wkb=AsWKB("point")).get(name="Chelyabinsk").wkb)
    b'\x01\x01\x00\x00\x00]3\xf9f\x9b\x91K@\x00X\x1d9\xd2\xb9N@'

### `AsWKT`

class AsWKT(expression, **extra)

Disponibilité : MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Accepte un seul champ ou expression géographique et renvoie une représentation WKT (Well-known text) du champ géométrique.

Exemple :

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

### `GeoHash`

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

Disponibilité : MariaDB, MySQL, PostGIS, SpatiaLite (LWGEOM/RTTOPO)

Accepte un seul champ ou expression géographique et renvoie une représentation GeoHash du champ géométrique.

Le paramètre nommé `precision` contrôle le nombre de caractères du résultat.

Changed in Django 6.0:

La prise en charge avec MariaDB 12.0.1+ a été ajoutée.

## Divers

### `IsEmpty`

class IsEmpty(expr)

Availability: PostGIS, SpatiaLite

Accepte un champ ou une expression géographique et teste si la valeur est un objet géométrique vide. Renvoie `True` si la valeur est un objet géométrique vide et `False` dans le cas contraire.

Changed in Django 6.1:

SpatiaLite support was added.

### `IsValid`

class IsValid(expr)

Disponibilité : MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Accepte un champ ou une expression géographique et teste si la valeur est bien formée. Renvoie `True` si la valeur est un objet géométrique valide et `False` dans le cas contraire.

Changed in Django 6.0:

La prise en charge avec MariaDB 12.0.1+ a été ajoutée.

### `GeometryType`

New in Django 6.0.

class GeometryType(expr)

Disponibilité : PostGIS, Oracle 23c+, MariaDB, MySQL, SpatiaLite

Accepte un champ ou une expression géographique et renvoie son type géométrique.

### `MemSize`

class MemSize(expression, **extra)

Disponibilité : PostGIS

Accepte un seul champ ou expression géographique et renvoie la taille mémoire (en octets) consommé par le champ géométrique.

### `NumDimensions`

New in Django 6.1.

class NumDimensions(expression, **extra)

Availability: PostGIS, SpatiaLite

Accepts a single geometry field or expression and returns the number of dimensions used by the geometry.

### `NumGeometries`

class NumGeometries(expression, **extra)

Disponibilité : MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Accepte un seul champ ou expression géographique et renvoie le nombre d’objets géométriques dans le cas où le champ est une collection (par ex. `GEOMETRYCOLLECTION` ou un champ `MULTI*`). Renvoie 1 pour des objets géométriques uniques.

Avec MySQL, renvoie `None` pour des objets géométriques uniques.

### `NumPoints`

class NumPoints(expression, **extra)

Disponibilité : MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Accepte un seul champ ou expression géographique et renvoie le nombre de points de l’objet géométrique.

Avec MySQL, renvoie `None` pour les objets géométriques autres que `LINESTRING`.