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 que DJANGO_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 Mac OS X.

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(buffer('\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x14@\x00\x00\x00\x00\x00\x007@'))
>>> 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.0000000000000000 0.0000000000000000)
>>> print(LineString((0, 0), (1, 1), srid=4326))
SRID=4326;LINESTRING (0.0000000000000000 0.0000000000000000, 1.0000000000000000 1.0000000000000000)
>>> print(Point(0, 0, srid=32140))
SRID=32140;POINT (0.0000000000000000 0.0000000000000000)

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

Mes journaux sont remplis par des erreurs liées à GEOS

Vous découvrez de nombreuses exceptions TypeError ou AttributeError remplissant les journaux de votre serveur Web. Cela signifie généralement que vous créez des objets GEOS au premier niveau de certains de vos modules Python. Ensuite, en raison d’un conflit de concurrence dans le récupérateur de mémoire, la mémoire de votre module est recyclée avant l’objet GEOS. Pour empêcher cela, créez les objets GEOSGeometry dans la portée locale de vos fonctions ou méthodes.

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

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

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 ou unicode
HEX / HEXEWKB	str ou unicode
WKB / EWKB	buffer
GeoJSON	str ou unicode

Note

La nouvelle notation WKT 3D/4D avec un élément Z ou M intermédiaire (comme POINT Z (3, 4, 5)) n’est prise en charge qu’à partir de GEOS 3.3.0.

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 les Points et les MultiPoints

• 1 pour les LineStrings et les MultiLineStrings

• 2 pour les Polygons et les MultiPolygons

• -1 pour les GeometryCollections vides

• la dimension maximale de ses éléments pour les GeometryCollections 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 objets LinearRing et Polygon 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.

Note

Nécessite GDAL.

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.

Note

Nécessite GDAL.

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 si other.within(this) renvoie True.

GEOSGeometry.crosses(other)

Renvoie True si la matrice d’intersection DE-9IM des deux objets géométriques est T*T****** (pour un point et une courbe, un point et une aire ou une ligne et une aire), ou 0******** (pour deux courbes).

GEOSGeometry.disjoint(other)

Renvoie True si la matrice d’intersection DE-9IM des deux objets géométriques est FF*FF****.

GEOSGeometry.equals(other)

Renvoie True si la matrice d’intersection DE-9IM des deux objets géométriques est T*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 de tolerance 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 si GEOSGeometry.disjoint() vaut False.

GEOSGeometry.overlaps(other)

Renvoie True si la matrice d’intersection DE-9IM des deux objets géométriques est T*T***T** (pour deux points ou deux surfaces), ou 1*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 motif pattern 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 est FT*******, F**T***** ou F***T****.

GEOSGeometry.within(other)

Renvoie True si la matrice d’intersection DE-9IM des deux objets géométriques est T*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 longueur width donnée. Le paramètre facultatif quadsegs définit le nombre de segments utilisés pour faire l’approximation d’un quart de cercle (8 par défaut).

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 ou MultiLineString) à 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’objet other.

GEOSGeometry.project(point)

GEOSGeometry.project_normalized(point)

Renvoie la distance (nombre à virgule) à partir de l’origine de l’objet géométrique (LineString ou MultiLineString) 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 de Polygon peuvent apparaître ou disparaître et des lignes peuvent se croiser. En définissant preserve_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’un Point 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.

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 objet GEOSGeometry).

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 ligne LineString ou la circonférence d’un Polygon).

GEOSGeometry.prepared

Renvoie un objet GEOS PreparedGeometry relatif au contenu de cet objet géométrique. Les objets PreparedGeometry 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 .

Note

Nécessite GDAL.

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.4, un objet SpatialReference ou un objet CoordTransform. Par défaut, l’objet géométrique est transformé lui-même et rien n’est renvoyé. Cependant, quand le paramètre clone 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

Exige GDAL. Génère une exception GEOSException si GDAL n’est pas disponible ou si la valeur SRID de l’objet géométrique est None ou plus petite que 0.

Point

class Point(x, y, 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])

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’objets Point. 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’objets Point:

>>> ls = LineString( ((0, 0), (1, 1)) )
>>> ls = LineString( [Point(0, 0), Point(1, 1)] )

LinearRing

class LinearRing(*args, **kwargs)

Les objets LinearRing sont construits de la même manière que les objets LineString. 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.

Polygon

class Polygon(*args, **kwargs)

Les objets Polygon peuvent être créés en passant un ou plusieurs paramètres représentant les segments du polygone. Les paramètres doivent être soit des instances de segments LinearRing, soit une suite d’éléments pouvant être utilisée pour construire un segment LinearRing:

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

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

class MultiPoint(*args, **kwargs)

Les objets MultiPoint peuvent être créés en passant un ou plusieurs objets Point en paramètres ou une seule liste d’objets Point:

>>> mp = MultiPoint(Point(0, 0), Point(1, 1))
>>> mp = MultiPoint( (Point(0, 0), Point(1, 1)) )

MultiLineString

class MultiLineString(*args, **kwargs)

Les objets MultiLineString peuvent être créés en passant un ou plusieurs objets LineString en paramètres ou une seule liste d’objets LineString:

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

MultiPolygon

class MultiPolygon(*args, **kwargs)

Les objets MultiPolygon peuvent être créés en passant un ou plusieurs objets Polygon en paramètres ou une seule liste d’objets Polygon:

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

cascaded_union

Renvoie un Polygon représentant l’union de tous les polygones composant cette collection. L’algorithme utilisé est nettement plus efficace (plus rapide) que de vouloir effectuer l’union individuelle des objets géométriques entre eux [2].

GeometryCollection

class GeometryCollection(*args, **kwargs)

Les objets GeometryCollection peuvent être créés en passant un ou plusieurs objets GEOSGeometry en paramètres ou une seule liste d’objets GEOSGeometry:

>>> 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é, il suffit d’accéder à 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ètre other (autre) qui doit représenter une instance GEOSGeometry.

contains(other)

contains_properly(other)

covers(other)

crosses(other)

New in Django 1.7.

Note

GEOS 3.3 est requis pour utiliser ce prédicat.

disjoint(other)

New in Django 1.7.

Note

GEOS 3.3 est requis pour utiliser ce prédicat.

intersects(other)

overlaps(other)

New in Django 1.7.

Note

GEOS 3.3 est requis pour utiliser ce prédicat.

touches(other)

New in Django 1.7.

Note

GEOS 3.3 est requis pour utiliser ce prédicat.

within(other)

New in Django 1.7.

Note

GEOS 3.3 est requis pour utiliser ce prédicat.

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 spatiales
Type retourné:	un objet GEOSGeometry correspondant aux données spatiales du fichier

Exemple :

>>> from django.contrib.gis.geos import fromfile
>>> g = fromfile('/home/bob/geom.wkt')

fromstr(string, srid=None)

Paramètres:	string (string) – chaîne contenant des données spatiales srid (int) – identifiant de référence spatiale
Type retourné:	un objet GEOSGeometry correspondant aux données spatiales de la chaîne

fromstr(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 simplement 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

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éthode write. 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.

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

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

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

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

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

WKTWriter.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)'

Notes de bas de page

[1]	Voir PostGIS EWKB, EWKT and Canonical Forms, documentation de PostGIS au chap. 4.1.2.

[2]	Pour plus d’informations, lisez l’article de blog de Paul Ramsey intitulé (Much) Faster Unions in PostGIS 1.4 et l’article de Martin Davis intitulé Fast polygon merging in JTS using Cascaded Union.

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.

Exceptions

exception GEOSException

L’exception GEOS de base, indiquant une erreur en lien avec GEOS.