API GEOS¶
Contexte¶
Qu’est-ce que GEOS ?¶
GEOS signifie Geometry Engine - Open Source. C’est une bibliothèque C++ dérivée de Java Topology Suite. GEOS implémente les prédicats et les opérateurs spatiaux de la spécification OpenGIS Simple Features for SQL. GEOS, dorénavant un projet OSGeo, a été initialement développée et maintenue par Refractions Research (Victoria, Canada).
Fonctionnalités¶
GeoDjango implémente une adaptation Python de haut niveau de la bibliothèque GEOS. Ses fonctionnalités comprennent notamment :
- Une interface sous licence BSD des routines géométriques GEOS, implémentées purement en Python à l’aide de
ctypes
. - Faiblement couplé à GeoDjango. Par exemple, les objets
GEOSGeometry
peuvent être utilisés en dehors d’un projet Django. En d’autres termes, il n’est pas nécessaire queDJANGO_SETTINGS_MODULE
ou une base de données soient définis. - Mutabilité : les objets
GEOSGeometry
peuvent être modifiés. - Multiplateforme et testé ; compatible avec les plateformes Windows, Linux, Solaris et macOS.
Tutoriel¶
Cette section contient une brève introduction à l’utilisation des objets GEOSGeometry
.
Création d’un objet géométrique¶
Les objets GEOSGeometry
peuvent être créés de plusieurs façons. La première est de simplement créer une instance avec du contenu spatial. Les exemples suivants montrent comment créer le même objet géométrique avec du contenu WKT, HEX, WKB et GeoJSON :
>>> from django.contrib.gis.geos import GEOSGeometry
>>> pnt = GEOSGeometry('POINT(5 23)') # WKT
>>> pnt = GEOSGeometry('010100000000000000000014400000000000003740') # HEX
>>> pnt = GEOSGeometry(memoryview(b'\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x14@\x00\x00\x00\x00\x00\x007@')) # WKB
>>> pnt = GEOSGeometry('{ "type": "Point", "coordinates": [ 5.000000, 23.000000 ] }') # GeoJSON
Un autre option est d’utiliser le constructeur correspondant au type d’objet géométrique que vous souhaitez créer. Par exemple un objet Point
peut être créé en passant des coordonnées X et Y à son constructeur :
>>> from django.contrib.gis.geos import Point
>>> pnt = Point(5, 23)
Tous ces constructeurs acceptent le paramètre nommé srid
. Par exemple :
>>> from django.contrib.gis.geos import GEOSGeometry, LineString, Point
>>> print(GEOSGeometry('POINT (0 0)', srid=4326))
SRID=4326;POINT (0 0)
>>> print(LineString((0, 0), (1, 1), srid=4326))
SRID=4326;LINESTRING (0 0, 1 1)
>>> print(Point(0, 0, srid=32140))
SRID=32140;POINT (0 0)
Pour terminer, il existe la méthode de fabrication fromfile()
qui renvoie un objet GEOSGeometry
à partir d’un fichier :
>>> from django.contrib.gis.geos import fromfile
>>> pnt = fromfile('/path/to/pnt.wkt')
>>> pnt = fromfile(open('/path/to/pnt.wkt'))
Les objets géométriques sont « pythonesques »¶
Les objets GEOSGeometry
sont « pythonesques », ce qui signifie qu’il est possible d’accéder, de modifier ou de passer en boucle leurs composants à l’aide des conventions Python standards. Par exemple, voici comment parcourir les coordonnées d’un Point
en boucle :
>>> pnt = Point(5, 23)
>>> [coord for coord in pnt]
[5.0, 23.0]
Avec n’importe quel objet géométrique, la propriété GEOSGeometry.coords
peut être utilisée pour obtenir les coordonnées géométriques sous forme de tuple Python :
>>> pnt.coords
(5.0, 23.0)
Il est possible d’obtenir et de définir les éléments des objets géométriques par des techniques d’indices Python standard. Cependant, les valeurs renvoyées dépendent du type d’objet géométrique. Par exemple, l’application d’un indice sur une ligne LineString
renvoie un tuple de coordonnées :
>>> from django.contrib.gis.geos import LineString
>>> line = LineString((0, 0), (0, 50), (50, 50), (50, 0), (0, 0))
>>> line[0]
(0.0, 0.0)
>>> line[-2]
(50.0, 0.0)
Alors que l’application d’un indice sur un Polygon
renvoie un anneau (un objet LinearRing
) correspondant à l’indice :
>>> from django.contrib.gis.geos import Polygon
>>> poly = Polygon( ((0.0, 0.0), (0.0, 50.0), (50.0, 50.0), (50.0, 0.0), (0.0, 0.0)) )
>>> poly[0]
<LinearRing object at 0x1044395b0>
>>> poly[0][-2] # second-to-last coordinate of external ring
(50.0, 0.0)
De plus, les coordonnées et les composants d’un objet géométrique peuvent être complétés ou modifiés de manière similaire à une liste Python :
>>> line[0] = (1.0, 1.0)
>>> line.pop()
(0.0, 0.0)
>>> line.append((1.0, 1.0))
>>> line.coords
((1.0, 1.0), (0.0, 50.0), (50.0, 50.0), (50.0, 0.0), (1.0, 1.0))
Les objets géométriques prennent en charge les opérateurs d’ensembles (set
) :
>>> from django.contrib.gis.geos import LineString
>>> ls1 = LineString((0, 0), (2, 2))
>>> ls2 = LineString((1, 1), (3, 3))
>>> print(ls1 | ls2) # equivalent to `ls1.union(ls2)`
MULTILINESTRING ((0 0, 1 1), (1 1, 2 2), (2 2, 3 3))
>>> print(ls1 & ls2) # equivalent to `ls1.intersection(ls2)`
LINESTRING (1 1, 2 2)
>>> print(ls1 - ls2) # equivalent to `ls1.difference(ls2)`
LINESTRING(0 0, 1 1)
>>> print(ls1 ^ ls2) # equivalent to `ls1.sym_difference(ls2)`
MULTILINESTRING ((0 0, 1 1), (2 2, 3 3))
L’opérateur d’égalité ne vérifie pas l’égalité spatiale
L’opérateur d’égalité de GEOSGeometry
utilise equals_exact()
, et non pas equals()
, c’est-à-dire que l’égalité dépend de coordonnées identiques, dans la même position et avec les mêmes SRID :
>>> from django.contrib.gis.geos import LineString
>>> ls1 = LineString((0, 0), (1, 1))
>>> ls2 = LineString((1, 1), (0, 0))
>>> ls3 = LineString((1, 1), (0, 0), srid=4326)
>>> ls1.equals(ls2)
True
>>> ls1 == ls2
False
>>> ls3 == ls2 # different SRIDs
False
Objets géométriques¶
GEOSGeometry
¶
-
class
GEOSGeometry
(geo_input, srid=None)¶ Paramètres: - geo_input – Valeur d’entrée géométrique (chaîne ou tampon)
- srid (int) – identifiant de référence spatiale
Il s’agit de la classe de base de tous les objets géométriques GEOS. Elle s’initialise en fonction du paramètre geo_input
donné, puis en déduit la sous-classe géométrique appropriée (par ex. GEOSGeometry('POINT(1 1)')
crée un objet Point
).
Le paramètre srid
, s’il est présent, est défini comme le SRID de l’objet géométrique créé si geo_input
ne possède pas de SRID. Si les valeurs de SRID entre les paramètres geo_input
et srid
diffèrent, une erreur ValueError
est produite
>>> from django.contrib.gis.geos import GEOSGeometry
>>> GEOSGeometry('POINT EMPTY', srid=4326).ewkt
'SRID=4326;POINT EMPTY'
>>> GEOSGeometry('SRID=4326;POINT EMPTY', srid=4326).ewkt
'SRID=4326;POINT EMPTY'
>>> GEOSGeometry('SRID=1;POINT EMPTY', srid=4326)
Traceback (most recent call last):
...
ValueError: Input geometry already has SRID: 1.
Les formats de valeurs d’entrée suivants, ainsi que leur type Python correspondant, sont acceptés :
Format | Type en entrée |
---|---|
WKT / EWKT | str |
HEX / HEXEWKB | str |
WKB / EWKB | buffer |
GeoJSON | str |
Pour le format GeoJSON, le SRID est défini sur la base du membre crs
. SI crs
n’est pas fourni, le SRID par défaut est 4326.
-
classmethod
GEOSGeometry.
from_gml
(gml_string)¶ Construit un objet
GEOSGeometry
à partir de la chaîne GML donnée.
Propriétés¶
-
GEOSGeometry.
coords
¶ Renvoie les coordonnées de l’objet géométrique sous forme de tuple.
-
GEOSGeometry.
dims
¶ Renvoie la dimension de l’objet géométrique :
0
pour lesPoint
s et lesMultiPoint
s1
pour lesLineString
s et lesMultiLineString
s2
pour lesPolygon
s et lesMultiPolygon
s-1
pour lesGeometryCollection
s vides- la dimension maximale de ses éléments pour les
GeometryCollection
s non vides
-
GEOSGeometry.
empty
¶ Renvoie une valeur booléenne indiquant si l’ensemble des points de l’objet géométrique est vide.
-
GEOSGeometry.
geom_type
¶ Renvoie une chaîne correspondant au type de l’objet géométrique. Par exemple :
>>> pnt = GEOSGeometry('POINT(5 23)') >>> pnt.geom_type 'Point'
-
GEOSGeometry.
geom_typeid
¶ Renvoie le numéro d’identification du type géométrique GEOS. Le tableau suivant expose la valeur correspondant à chaque type géométrique :
Objet géométrique ID Point
0 LineString
1 LinearRing
2 Polygon
3 MultiPoint
4 MultiLineString
5 MultiPolygon
6 GeometryCollection
7
-
GEOSGeometry.
num_coords
¶ Renvoie le nombre de coordonnées de l’objet géométrique.
-
GEOSGeometry.
num_geom
¶ Renvoie le nombre d’objets géométriques dans cet objet. En d’autres termes, le résultat sera 1 pour toute autre chose que les collections d’objets géométriques.
-
GEOSGeometry.
hasz
¶ Renvoie une valeur booléenne indiquant si l’objet géométrique est en trois dimensions.
-
GEOSGeometry.
ring
¶ Renvoie une valeur booléenne indiquant si l’objet géométrique est un
LinearRing
.
-
GEOSGeometry.
simple
¶ Renvoie une valeur booléenne indiquant si l’objet géométrique est « simple ». Un objet géométrique est simple si et seulement s’il n’a pas d’intersection avec lui-même (excepté aux points limites). Par exemple, un objet
LineString
n’est pas simple si sa ligne se croise elle-même. Par définition les objetsLinearRing
etPolygon
sont toujours simples car ils ne peuvent pas avoir d’intersections avec eux-mêmes.
-
GEOSGeometry.
valid
¶ Renvoie une valeur booléenne indiquant si l’objet géométrique est valide.
-
GEOSGeometry.
valid_reason
¶ Renvoie une chaîne décrivant la raison pour laquelle un objet géométrique n’est pas valable.
-
GEOSGeometry.
srid
¶ Propriété pouvant être utilisée pour récupérer ou définir le SRID associé à l’objet. Par exemple :
>>> pnt = Point(5, 23) >>> print(pnt.srid) None >>> pnt.srid = 4326 >>> pnt.srid 4326
Propriétés en sortie¶
Les propriétés de cette section exportent l’objet GEOSGeometry
sous une forme différente. Cette forme peut être une chaîne, un tampon mémoire ou même un autre objet.
-
GEOSGeometry.
ewkt
¶ Renvoie le format WKT (Well-Known Text) étendu de l’objet géométrique. Cette représentation est spécifique à PostGIS et constitue un sur-ensemble du standard WKT OGC [1]. En bref, la représentation WKT est préfixée par le code SRID, par exemple
SRID=4326;POINT(5 23)
.Note
Le résultat de cette propriété n’inclut pas les informations 3dm, 3dz ou 4d que PostGIS prend en charge dans ses représentations EWKT.
-
GEOSGeometry.
hex
¶ Renvoie la représentation WKB de cet objet géométrique sous forme hexadécimale. Notez que la valeur SRID n’est pas incluse dans cette représentation car elle ne fait pas partie de la spécification OGC (utilisez plutôt la propriété
GEOSGeometry.hexewkb
).
-
GEOSGeometry.
hexewkb
¶ Renvoie la représentation EWKB de cet objet géométrique sous forme hexadécimale. Il s’agit d’une extension de la spécification WKB incluant la valeur SRID correspondant à l’objet géométrique.
-
GEOSGeometry.
json
¶ Renvoie la 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.
-
GEOSGeometry.
geojson
¶ Alias de
GEOSGeometry.json
.
-
GEOSGeometry.
kml
¶ Renvoie une représentation KML (Keyhole Markup Language) de cet objet géométrique. Ceci ne devrait être utilisé que pour des objets géométriques ayant le SRID 4326 (WGS84), mais cette restriction n’est pas forcée.
-
GEOSGeometry.
ogr
¶ Renvoie un objet
OGRGeometry
équivalent à l’objet géométrique GEOS.
-
GEOSGeometry.
wkb
¶ Renvoie la représentation WKB (Well-Known Binary) de cet objet géométrique sous forme de tampon Python (buffer). La valeur SRID n’est pas incluse. Si vous le souhaitez, utilisez plutôt la propriété
GEOSGeometry.ewkb
.
-
GEOSGeometry.
ewkb
¶ Renvoie la représentation EWKB de cet objet géométrique sous forme de tampon Python (buffer). Il s’agit d’une extension de la spécification WKB qui inclut toute valeur SRID faisant partie de cet objet.
-
GEOSGeometry.
wkt
¶ Renvoie la représentation WKT (Well-Known Text) de cet objet géométrique (un standard OGC).
Méthodes de prédicats spatiaux¶
Toutes les méthodes de prédicats spatiaux ci-après acceptent en paramètre une autre instance GEOSGeometry
(other
) et renvoient une valeur booléenne.
-
GEOSGeometry.
contains
(other)¶ Renvoie
True
siother.within(this)
renvoieTrue
.
-
GEOSGeometry.
covers
(other)¶ Renvoie
True
si cet objet géométrique recouvre l’objet géométrique donné.Le prédicat
covers
possède les définitions équivalentes suivantes :- Chaque point de l’autre objet géométrique est un point de cet objet géométrique.
- La matrice d’intersection DE-9IM des deux objets géométriques est
T*****FF*
,*T****FF*
,***T**FF*
ou****T*FF*
.
Si l’un des objets géométriques est vide, renvoie
False
.Ce prédicat est semblable à
GEOSGeometry.contains()
, mais est plus inclusif (c’est-à-dire qu’il renvoieTrue
dans plus de cas). En particulier, au contraire decontains()
, il ne distingue pas entre les points à la limite et ceux à l’intérieur de l’objet géométrique. Dans la plupart des situations,covers()
devrait être préféré àcontains()
. Comme bénéfice supplémentaire,covers()
est plus sujet à l’optimisation et devrait donc être bien plus performant quecontains()
.
-
GEOSGeometry.
crosses
(other)¶ Renvoie
True
si la matrice d’intersection DE-9IM des deux objets géométriques estT*T******
(pour un point et une courbe, un point et une aire ou une ligne et une aire), ou0********
(pour deux courbes).
-
GEOSGeometry.
disjoint
(other)¶ Renvoie
True
si la matrice d’intersection DE-9IM des deux objets géométriques estFF*FF****
.
-
GEOSGeometry.
equals
(other)¶ Renvoie
True
si la matrice d’intersection DE-9IM des deux objets géométriques estT*F**FFF*
.
-
GEOSGeometry.
equals_exact
(other, tolerance=0)¶ Renvoie
True
si les deux objets géométriques sont exactement égaux, jusqu’à une certaine tolérance. La valeur detolerance
doit être un nombre à virgule représentant la tolérance d’erreur dans la comparaison. Par exemple,poly1.equals_exact(poly2, 0.001)
compare l’égalité jusqu’à un millième d’unité.
-
GEOSGeometry.
intersects
(other)¶ Renvoie
True
siGEOSGeometry.disjoint()
vautFalse
.
-
GEOSGeometry.
overlaps
(other)¶ Renvoie
True
si la matrice d’intersection DE-9IM des deux objets géométriques estT*T***T**
(pour deux points ou deux surfaces), ou1*T***T**
(pour deux courbes).
-
GEOSGeometry.
relate_pattern
(other, pattern)¶ Renvoie
True
si la matrice d’intersection DE-9IM des deux objets géométriques correspond au motifpattern
donné, une chaîne de neuf caractères dans l’alphabet {T
,F
,*
,0
}.
-
GEOSGeometry.
touches
(other)¶ Renvoie
True
si la matrice d’intersection DE-9IM des deux objets géométriques estFT*******
,F**T*****
ouF***T****
.
-
GEOSGeometry.
within
(other)¶ Renvoie
True
si la matrice d’intersection DE-9IM des deux objets géométriques estT*F**F***
.
Méthodes topologiques¶
-
GEOSGeometry.
buffer
(width, quadsegs=8)¶ Renvoie un objet
GEOSGeometry
représentant tous les points dont la distance à cet objet géométrique est plus petit ou égal à la longueurwidth
donnée. Le paramètre facultatifquadsegs
définit le nombre de segments utilisés pour faire l’approximation d’un quart de cercle (8 par défaut).
-
GEOSGeometry.
buffer_with_style
(width, quadsegs=8, end_cap_style=1, join_style=1, mitre_limit=5.0)¶ Identique à
buffer()
, mais permet de personnaliser le style du tampon.end_cap_style
peut être rond (1
), plat (2
) ou carré (3
).join_style
peut être rond (1
), onglet (2
) ou biseau (3
).- La limite de taux d’onglet (
mitre_limit
) n’affecte que le style de jointure par onglet.
-
GEOSGeometry.
difference
(other)¶ Renvoie un objet
GEOSGeometry
représentant les points composants cet objet géométrique qui ne composent pas l’autre objet.
-
GEOSGeometry.
interpolate
(distance)¶
-
GEOSGeometry.
interpolate_normalized
(distance)¶ Étant donné une distance (nombre à virgule), renvoie le point (ou le point le plus proche) de l’objet géométrique (
LineString
ouMultiLineString
) à cette distance. La version normalisée accepte une distance sous forme d’un nombre à virgule entre 0 (origine) et 1 (point terminal).Inverse de
GEOSGeometry.project()
.
-
GEOSGeometry.
intersection
(other)¶ Renvoie un objet
GEOSGeometry
représentant les points partagés entre cet objet géométrique et l’objetother
.
-
GEOSGeometry.
project
(point)¶
-
GEOSGeometry.
project_normalized
(point)¶ Renvoie la distance (nombre à virgule) à partir de l’origine de l’objet géométrique (
LineString
ouMultiLineString
) jusqu’au point projeté sur la géométrie (c’est-à-dire le point de la ligne le plus proche du point donné). La version normalisée renvoie la distance sous forme d’un nombre à virgule entre 0 (origine) et 1 (point terminal).Inverse de
GEOSGeometry.interpolate()
.
-
GEOSGeometry.
relate
(other)¶ Renvoie la matrice d’intersection DE-9IM (une chaîne) représentant la relation topologique entre cet objet géométrique et l’objet en paramètre.
-
GEOSGeometry.
simplify
(tolerance=0.0, preserve_topology=False)¶ Renvoie un nouvel objet
GEOSGeometry
, simplifié à la tolérance indiquée en utilisant l’algorithme Douglas-Peucker. Une plus haute valeur de tolérance produit moins de points dans le résultat. Si aucune tolérance n’est fournie, la valeur par défaut est 0.Par défaut, cette fonction ne préserve pas la topologie. Par exemple, les objets
Polygon
peuvent être divisés, être fusionnés pour former des lignes ou carrément disparaître. Des trous dePolygon
peuvent apparaître ou disparaître et des lignes peuvent se croiser. En définissantpreserve_topology=True
, le résultat aura les mêmes dimensions et le même nombre de composants que l’objet de départ ; la fonction est cependant nettement plus lente.
-
GEOSGeometry.
sym_difference
(other)¶ Renvoie un objet
GEOSGeometry
formé des points de cet objet géométrique qui ne sont pas dans l’objet en paramètre, ainsi que des points dans l’objet en paramètre qui ne sont pas dans cet objet.
-
GEOSGeometry.
union
(other)¶ Renvoie un objet
GEOSGeometry
représentant tous les points de cet objet géométrique additionnés de ceux de l’objet en paramètre.
Propriétés topologiques¶
-
GEOSGeometry.
boundary
¶ Renvoie les limites sous forme d’une nouvelle instance d’objet géométrique.
-
GEOSGeometry.
centroid
¶ Renvoie un objet
Point
représentant le centre géométrique de l’objet. Le point n’est pas assuré d’être à l’intérieur de l’objet géométrique.
-
GEOSGeometry.
convex_hull
¶ Renvoie le plus petit
Polygon
contenant tous les points de l’objet géométrique.
-
GEOSGeometry.
envelope
¶ Renvoie un
Polygon
qui représente l’enveloppe englobante de cet objet géométrique. Notez qu’unPoint
peut aussi être renvoyé si l’objet en entrée est lui-même un point.
-
GEOSGeometry.
point_on_surface
¶ Calcule et renvoie un
Point
assuré d’être à l’intérieur de l’objet géométrique.
-
GEOSGeometry.
unary_union
¶ Calcule l’union de tous les éléments de cet objet géométrique.
Le résultat respecte le contrat suivant :
- L’union d’un ensemble de
LineString
procède à leur complète mise en nœuds et à la dissolution des lignes. - L’union d’un ensemble de
Polygon
renvoie toujours un objet géométriquePolygon
ouMultiPolygon
(au contraire deGEOSGeometry.union()
qui peut renvoyer des géométries de plus faible dimension si un conflit de topologie se produit).
- L’union d’un ensemble de
Autres propriétés et méthodes¶
-
GEOSGeometry.
area
¶ Cette propriété renvoie l’aire de l’objet géométrique.
-
GEOSGeometry.
extent
¶ Cette propriété renvoie l’étendue de cet objet géométrique sous forme d’un tuple à 4 éléments, formé de
(xmin, ymin, xmax, ymax)
.
-
GEOSGeometry.
clone
()¶ Cette méthode renvoie un objet
GEOSGeometry
clone de l’original.
-
GEOSGeometry.
distance
(geom)¶ Renvoie la distance entre les points les plus proches de cet objet géométrique et l’objet
geom
(un autre objetGEOSGeometry
).Note
Les calculs de distance GEOS sont linéaires ; en d’autres termes, GEOS n’effectue pas de calculs sphériques même si le SRID définit un système de coordonnées géographique.
-
GEOSGeometry.
length
¶ Renvoie la longueur de cet objet géométrique (par ex. 0 pour un
Point
, la longueur d’une ligneLineString
ou la circonférence d’unPolygon
).
-
GEOSGeometry.
prepared
¶ Renvoie un objet GEOS
PreparedGeometry
relatif au contenu de cet objet géométrique. Les objetsPreparedGeometry
sont optimisés pour les opérations contains, intersects, covers, crosses, disjoint, overlaps, touches et within. Référez-vous à la documentation Objets géométriques préparés pour plus d’informations.
-
GEOSGeometry.
srs
¶ Renvoie un objet
SpatialReference
correspondant au SRID de l’objet géométrique ou .
-
GEOSGeometry.
transform
(ct, clone=False)¶ Transforme l’objet géométrique en fonction du paramètre de transformation de coordonnées donné (
ct
), qui peut être un numéro de SRID, une chaîne de référence spatiale WKT, une chaîne PROJ, un objetSpatialReference
ou un objetCoordTransform
. Par défaut, l’objet géométrique est transformé lui-même et rien n’est renvoyé. Cependant, quand le paramètreclone
est défini, l’objet géométrique n’est pas modifié et c’est un clone transformé de l’objet géométrique qui est renvoyé.Note
Génère une exception
GEOSException
si GDAL n’est pas disponible ou si la valeur SRID de l’objet géométrique estNone
ou plus petite que 0. Aucune contrainte n’est imposée pour le code SRID de l’objet géométrique quand elle est appelée avec un objetCoordTransform
.
-
GEOSGeometry.
make_valid
()¶ - New in Django 4.1.
Returns a valid
GEOSGeometry
equivalent, trying not to lose any of the input vertices. If the geometry is already valid, it is returned untouched. This is similar to theMakeValid
database function. Requires GEOS 3.8.
-
GEOSGeometry.
normalize
(clone=False)¶ Converts this geometry to canonical form. If the
clone
keyword is set, then the geometry is not modified and a normalized clone of the geometry is returned instead:>>> g = MultiPoint(Point(0, 0), Point(2, 2), Point(1, 1)) >>> print(g) MULTIPOINT (0 0, 2 2, 1 1) >>> g.normalize() >>> print(g) MULTIPOINT (2 2, 1 1, 0 0)
Changed in Django 4.1:The
clone
argument was added.
Point
¶
-
class
Point
(x=None, y=None, z=None, srid=None)¶ Les objets
Point
sont créés en utilisant des paramètres représentant les composantes de coordonnées du point ou une suite unique de coordonnées. Par exemple, les lignes suivantes sont équivalentes :>>> pnt = Point(5, 23) >>> pnt = Point([5, 23])
Des objets
Point
vides peuvent être instanciés en ne passant aucun paramètre ou une liste vide. Ces lignes sont équivalentes :>>> pnt = Point() >>> pnt = Point([])
LineString
¶
-
class
LineString
(*args, **kwargs)¶ Les objets
LineString
sont créés en utilisant des paramètres représentant une suite de coordonnées ou une suite d’objetsPoint
. Par exemple, les lignes suivantes sont équivalentes>>> ls = LineString((0, 0), (1, 1)) >>> ls = LineString(Point(0, 0), Point(1, 1))
De plus, les objets
LineString
peuvent aussi être créés en passant une seule liste de coordonnées ou d’objetsPoint
:>>> ls = LineString( ((0, 0), (1, 1)) ) >>> ls = LineString( [Point(0, 0), Point(1, 1)] )
Des objets
LineString
vides peuvent être instanciés en ne passant aucun paramètre ou une liste vide. Ces lignes sont équivalentes :>>> ls = LineString() >>> ls = LineString([])
-
closed
¶ Indique si cette ligne
LineString
est fermée.
-
LinearRing
¶
-
class
LinearRing
(*args, **kwargs)¶ Les objets
LinearRing
sont construits de la même manière que les objetsLineString
. Cependant, les coordonnées doivent être fermées, c’est-à-dire que la première et la dernière coordonnée doivent être identiques. Par exemple :>>> ls = LinearRing((0, 0), (0, 1), (1, 1), (0, 0))
Remarquez que
(0, 0)
est à la fois la première et la dernière coordonnée ; si elles ne sont pas égales, une erreur est générée.-
is_counterclockwise
¶ Indique si cet objet
LinearRing
est orienté dans le sens antihoraire.
-
Polygon
¶
-
class
Polygon
(*args, **kwargs)¶ Les objets
Polygon
peuvent être créés en passant des paramètres représentant les segments du polygone. Les paramètres doivent être soit des instances de segmentsLinearRing
, soit une suite d’éléments pouvant être utilisée pour construire un segmentLinearRing
:>>> ext_coords = ((0, 0), (0, 1), (1, 1), (1, 0), (0, 0)) >>> int_coords = ((0.4, 0.4), (0.4, 0.6), (0.6, 0.6), (0.6, 0.4), (0.4, 0.4)) >>> poly = Polygon(ext_coords, int_coords) >>> poly = Polygon(LinearRing(ext_coords), LinearRing(int_coords))
-
classmethod
from_bbox
(bbox)¶ Renvoie un objet polygone à partir du rectangle englobant donné, un tuple à 4 éléments comprenant
(xmin, ymin, xmax, ymax)
.
-
num_interior_rings
¶ Renvoie le nombre de segments intérieurs de cet objet géométrique.
-
classmethod
Comparaison de polygones
Notez qu’il est possible de comparer des objets Polygon
directement avec <
or >
, mais comme la comparaison se fait à travers les segments LineString
du polygone, cela n’a pas grande signification (mais c’est cohérent et rapide). Vous pouvez toujours forcer la comparaison avec la propriété area
:
>>> if poly_1.area > poly_2.area:
>>> pass
Collections géométriques¶
MultiPoint
¶
MultiLineString
¶
-
class
MultiLineString
(*args, **kwargs)¶ Les objets
MultiLineString
peuvent être créés en passant des objetsLineString
en paramètres ou une seule liste d’objetsLineString
:>>> ls1 = LineString((0, 0), (1, 1)) >>> ls2 = LineString((2, 2), (3, 3)) >>> mls = MultiLineString(ls1, ls2) >>> mls = MultiLineString([ls1, ls2])
-
merged
¶ Renvoie une ligne
LineString
représentant la fusion de tous les composants de cet objet
-
closed
¶ Renvoie
True
si et seulement si tous les éléments sont fermés.
-
MultiPolygon
¶
-
class
MultiPolygon
(*args, **kwargs)¶ Les objets
MultiPolygon
peuvent être créés en passant des objetsPolygon
en paramètres ou une seule liste d’objetsPolygon
:>>> p1 = Polygon( ((0, 0), (0, 1), (1, 1), (0, 0)) ) >>> p2 = Polygon( ((1, 1), (1, 2), (2, 2), (1, 1)) ) >>> mp = MultiPolygon(p1, p2) >>> mp = MultiPolygon([p1, p2])
GeometryCollection
¶
-
class
GeometryCollection
(*args, **kwargs)¶ Les objets
GeometryCollection
peuvent être créés en passant des objetsGEOSGeometry
en paramètres ou une seule liste d’objetsGEOSGeometry
:>>> poly = Polygon( ((0, 0), (0, 1), (1, 1), (0, 0)) ) >>> gc = GeometryCollection(Point(0, 0), MultiPoint(Point(0, 0), Point(1, 1)), poly) >>> gc = GeometryCollection((Point(0, 0), MultiPoint(Point(0, 0), Point(1, 1)), poly))
Objets géométriques préparés¶
Pour obtenir un objet géométrique préparé, accédez à la propriété GEOSGeometry.prepared
. Avec une instance PreparedGeometry
, il est possible d’utiliser ses méthodes de prédicats spatiaux énumérées ci-dessous avec d’autres objets GEOSGeometry
. Une opération sur un objet géométrique préparé peut être beaucoup plus rapide ; plus l’objet géométrique est complexe, plus grand sera le gain de rapidité pour l’opération. Pour plus d’informations, consultez la page du wiki GEOS sur les objets géométriques préparés.
Par exemple :
>>> from django.contrib.gis.geos import Point, Polygon
>>> poly = Polygon.from_bbox((0, 0, 5, 5))
>>> prep_poly = poly.prepared
>>> prep_poly.contains(Point(2.5, 2.5))
True
PreparedGeometry
¶
-
class
PreparedGeometry
¶ Toutes les méthodes des objets
PreparedGeometry
acceptent un paramètreother
(autre) qui doit représenter une instanceGEOSGeometry
.-
contains
(other)¶
-
contains_properly
(other)¶
-
covers
(other)¶
-
crosses
(other)¶
-
disjoint
(other)¶
-
intersects
(other)¶
-
overlaps
(other)¶
-
touches
(other)¶
-
within
(other)¶
-
Fabrication d’objets géométriques¶
-
fromfile
(file_h)¶ Paramètres: file_h (a Python file
object or a string path to the file) – Fichier d’entrée contenant des données spatialesType renvoyé: un objet GEOSGeometry
correspondant aux données spatiales du fichierExemple :
>>> from django.contrib.gis.geos import fromfile >>> g = fromfile('/home/bob/geom.wkt')
-
fromstr
(string, srid=None)¶ Paramètres: Type renvoyé: un objet
GEOSGeometry
correspondant aux données spatiales de la chaînefromstr(string, srid)
est équivalente àGEOSGeometry(string, srid)
.Exemple :
>>> from django.contrib.gis.geos import fromstr >>> pnt = fromstr('POINT(-90.5 29.5)', srid=4326)
Objets d’entrées/sorties¶
Objets de lecture¶
Les classes d’entrées/sorties en lecture renvoient une instance GEOSGeometry
à partir du contenu WKB ou WKT en entrée en fonction de leur méthode read(geom)
.
-
class
WKBReader
¶ Exemple :
>>> from django.contrib.gis.geos import WKBReader >>> wkb_r = WKBReader() >>> wkb_r.read('0101000000000000000000F03F000000000000F03F') <Point object at 0x103a88910>
-
class
WKTReader
¶ Exemple :
>>> from django.contrib.gis.geos import WKTReader >>> wkt_r = WKTReader() >>> wkt_r.read('POINT(1 1)') <Point object at 0x103a88b50>
Objets d’écriture¶
Tous les objets d’écriture ont une méthode write(geom)
qui renvoie la représentation WKB ou WKT de l’objet géométrique concerné. De plus, les objets WKBWriter
ont aussi des propriétés pouvant être utilisées pour changer l’ordre des octets et d’inclure la valeur SRID (autrement dit, du contenu EWKB).
-
class
WKBWriter
(dim=2)¶ WKBWriter
offre le plus de contrôle sur le contenu produit. Par défaut, il renvoie du contenu WKB conforme OGC lorsqu’on appelle sa méthodewrite
. Cependant, il possède des propriétés permettant la production de format EWKB, un sur-ensemble du standard WKB qui inclut des informations supplémentaires. Voir la documentationWKBWriter.outdim
pour plus de détails sur le paramètredim
.-
write
(geom)¶
Renvoie la représentation WKB de l’objet géométrique sous forme d’objet Python
buffer
. Exemple :>>> from django.contrib.gis.geos import Point, WKBWriter >>> pnt = Point(1, 1) >>> wkb_w = WKBWriter() >>> wkb_w.write(pnt) <read-only buffer for 0x103a898f0, size -1, offset 0 at 0x103a89930>
-
write_hex
(geom)¶
Renvoie la représentation WKB de l’objet géométrique sous forme hexadécimale. Exemple :
>>> from django.contrib.gis.geos import Point, WKBWriter >>> pnt = Point(1, 1) >>> wkb_w = WKBWriter() >>> wkb_w.write_hex(pnt) '0101000000000000000000F03F000000000000F03F'
-
byteorder
¶
Cette propriété peut être définie pour changer l’ordre des octets de la représentation géométrique.
Valeur byteorder
Description 0 Gros-boutiste (big endian, compatible avec les systèmes RISC) 1 Petit-boutiste (little endian, compatible avec les systèmes x86) Exemple :
>>> from django.contrib.gis.geos import Point, WKBWriter >>> wkb_w = WKBWriter() >>> pnt = Point(1, 1) >>> wkb_w.write_hex(pnt) '0101000000000000000000F03F000000000000F03F' >>> wkb_w.byteorder = 0 '00000000013FF00000000000003FF0000000000000'
-
outdim
¶
Cette propriété peut être définie pour changer les dimensions du résultat de la représentation géométrique. En d’autres termes, si vous avez un objet 3D, définir cette valeur à 3 permet d’inclure la dimension Z dans le format WKB.
Valeur outdim
Description 2 Par défaut, produit du contenu WKB en 2D. 3 Produit du contenu WKB en 3D. Exemple :
>>> from django.contrib.gis.geos import Point, WKBWriter >>> wkb_w = WKBWriter() >>> wkb_w.outdim 2 >>> pnt = Point(1, 1, 1) >>> wkb_w.write_hex(pnt) # By default, no Z value included: '0101000000000000000000F03F000000000000F03F' >>> wkb_w.outdim = 3 # Tell writer to include Z values >>> wkb_w.write_hex(pnt) '0101000080000000000000F03F000000000000F03F000000000000F03F'
-
srid
¶
Définissez cette propriété avec une valeur booléenne pour indiquer si le code SRID de l’objet géométrique doit être inclus dans la représentation WKB. Exemple :
>>> from django.contrib.gis.geos import Point, WKBWriter >>> wkb_w = WKBWriter() >>> pnt = Point(1, 1, srid=4326) >>> wkb_w.write_hex(pnt) # By default, no SRID included: '0101000000000000000000F03F000000000000F03F' >>> wkb_w.srid = True # Tell writer to include SRID >>> wkb_w.write_hex(pnt) '0101000020E6100000000000000000F03F000000000000F03F'
-
-
class
WKTWriter
(dim=2, trim=False, precision=None)¶ Cette classe permet de produire la représentation WKT d’un objet géométrique. Voir les attributs
WKBWriter.outdim
,trim
etprecision
pour plus de détails sur les paramètres du constructeur.-
write
(geom)¶
Renvoie la représentation WKT de l’objet géométrique. Exemple :
>>> from django.contrib.gis.geos import Point, WKTWriter >>> pnt = Point(1, 1) >>> wkt_w = WKTWriter() >>> wkt_w.write(pnt) 'POINT (1.0000000000000000 1.0000000000000000)'
-
outdim
¶ Voir
WKBWriter.outdim
.
-
trim
¶
Cette propriété est utilisée pour activer ou désactiver la suppression de décimales non nécessaires.
>>> from django.contrib.gis.geos import Point, WKTWriter >>> pnt = Point(1, 1) >>> wkt_w = WKTWriter() >>> wkt_w.trim False >>> wkt_w.write(pnt) 'POINT (1.0000000000000000 1.0000000000000000)' >>> wkt_w.trim = True >>> wkt_w.write(pnt) 'POINT (1 1)'
-
precision
¶
Cette propriété contrôle la précision de l’arrondi des coordonnées ; si elle vaut
None
, l’arrondi est désactivé.>>> from django.contrib.gis.geos import Point, WKTWriter >>> pnt = Point(1.44, 1.66) >>> wkt_w = WKTWriter() >>> print(wkt_w.precision) None >>> wkt_w.write(pnt) 'POINT (1.4399999999999999 1.6599999999999999)' >>> wkt_w.precision = 0 >>> wkt_w.write(pnt) 'POINT (1 2)' >>> wkt_w.precision = 1 >>> wkt_w.write(pnt) 'POINT (1.4 1.7)'
-
Notes de bas de page
[1] | Voir PostGIS EWKB, EWKT and Canonical Forms, documentation de PostGIS au chap. 4.1.2. |
Réglages¶
GEOS_LIBRARY_PATH
¶
Une chaîne indiquant l’emplacement de la bibliothèque GEOS C. Ce réglage n’est généralement nécessaire que si la bibliothèque GEOS C n’est pas à un emplacement standard (par ex. /home/bob/lib/libgeos_c.so
).
Note
Le réglage doit contenir le chemin complet vers la bibliothèque partagée en C ; en d’autres termes, il faut indiquer libgeos_c.so
, et non pas libgeos.so
.