API de GDAL

GDAL signifie Geospatial Data Abstraction Library et est un véritable couteau suisse de fonctionnalités pour les données spatiales. La bibliothèque « Simple Features » OGR est un sous-ensemble de GDAL qui se spécialise dans la lecture et l’écriture de données géographiques vectorielles dans une variété de formats standards.

GeoDjango présente une interface Python de haut niveau pour certaines fonctionnalités de OGR, y compris la lecture et les transformations de coordonnées de données spatiales vectorielles ainsi qu’une prise en charge minimale pour des fonctionnalités GDAL en ce qui concerne les données matricielles (images).

Note

Même si le module s’appelle gdal, GeoDjango ne gère qu’une partie des fonctionnalités d’OGR et matricielles de GDAL pour le moment.

Aperçu

Données d’exemple

Les outils GDAL/OGR présentés ici sont conçus pour vous aider à lire vos données géospatiales. Pour la plupart de ces outils, il est nécessaire de disposer de données à manipuler pour qu’ils soient utiles. Si vous débutez et que vous ne disposez pas encore de vos propres données, les tests de GeoDjango contiennent un certain nombre de jeux de données d’exemple utilisables pour des tests. Vous pouvez les télécharger ici :

$ wget https://raw.githubusercontent.com/django/django/master/tests/gis_tests/data/cities/cities.{shp,prj,shx,dbf}
$ wget https://raw.githubusercontent.com/django/django/master/tests/gis_tests/data/rasters/raster.tif

Objets sources de données vectorielles

DataSource

DataSource est un adaptateur autour de l’objet de source de données OGR qui prend en charge la lecture de données à partir d’une variété de formats de fichiers et de sources de données géospatiales que OGR sait traiter à l’aide d’une interface simple et cohérente. Chaque source de données est représentée par un objet DataSource contenant une ou plusieurs couches de données. Chaque couche représentée par un objet Layer contient un certain nombre d’éléments géographiques (Feature), des informations à propos du type d’éléments contenus dans la couche (par ex. points, polygones, etc.) ainsi que les noms et les types de champs supplémentaires (Field) de données qui peuvent être associés à chaque élément de la couche.

class DataSource(ds_input, encoding='utf-8')

Le constructeur de DataSource n’exige qu’un seul paramètre : le chemin vers le fichier que vous souhaitez lire. Cependant, OGR prend également en charge une variété de sources de données plus complexes, y compris des bases de données, dont l’accès est défini en passant une chaîne spéciale au lieu d’un chemin. Pour plus d’informations, consultez la documentation sur les formats vectoriels OGR. La propriété name d’une instance DataSource donne le nom OGR des données sous-jacentes que la source de données utilise.

Le paramètre facultatif encoding permet d’indiquer un codage non standard des chaînes dans le fichier source. Typiquement, cela peut se révéler utile lorsqu’on obtient des exceptions DjangoUnicodeDecodeError lors de la lecture des valeurs de champs.

Après avoir créé une source DataSource, il est possible de connaître le nombre de couches contenues dans cette source en accédant à la propriété layer_count ou en utilisant (de façon équivalente) la fonction len(). Pour savoir comment accéder aux couches de données elles-mêmes, passez à la section suivante :

>>> from django.contrib.gis.gdal import DataSource
>>> ds = DataSource('/path/to/your/cities.shp')
>>> ds.name
'/path/to/your/cities.shp'
>>> ds.layer_count                  # This file only contains one layer
1
layer_count

Renvoie le nombre de couches de cette source de données.

name

Renvoie le nom de cette source de données.

Layer

class Layer

Layer est un adaptateur autour d’une couche de données dans un objet DataSource. Les objets Layer ne sont jamais créés directement. Ils sont obtenus plutôt à partir d’un objet DataSource, qui est fondamentalement un conteneur Python standard pour des objets Layer. Par exemple, vous pouvez accéder à une couche particulière par son indice (par ex. ds[0] pour accéder à la première couche) ou en passant en boucle toutes les couches d’un conteneur dans une boucle for. La couche elle-même joue le rôle de conteneur pour des éléments géographiques.

En principe, tous les éléments d’une même couche ont le même type de géométrie. La propriété geom_type d’une couche est un objet OGRGeomType identifiant le type des éléments. Nous pouvons l’exploiter pour afficher certaines informations de base à propos de chaque couche d’une source DataSource:

>>> for layer in ds:
...     print('Layer "%s": %i %ss' % (layer.name, len(layer), layer.geom_type.name))
...
Layer "cities": 3 Points

Cet exemple de résultat provient de la source de données des villes chargée plus haut, qui de manière évidente contient une couche nommée "cities", contenant elle-même trois éléments de type point. Par simplicité, les exemples ci-dessous comptent sur le fait que cette couche est stockée dans la variable layer:

>>> layer = ds[0]
name

Renvoie le nom de cette couche dans la source de données.

>>> layer.name
'cities'
num_feat

Renvoie le nombre d’éléments dans cette couche. Identique à len(layer):

>>> layer.num_feat
3
geom_type

Renvoie le type géométrique de cette couche, sous forme d’objet OGRGeomType:

>>> layer.geom_type.name
'Point'
num_fields

Renvoie le nombre de champs dans la couche, c’est-à-dire le nombre de champs de données associés à chaque élément de la couche :

>>> layer.num_fields
4
fields

Renvoie une liste des noms de chaque champ de cette couche :

>>> layer.fields
['Name', 'Population', 'Density', 'Created']

Renvoie une liste des types de données de chaque champ de cette couche. Ce sont des sous-classes de Field, discuté ci-dessous :

>>> [ft.__name__ for ft in layer.field_types]
['OFTString', 'OFTReal', 'OFTReal', 'OFTDate']
field_widths

Renvoie une liste des largeurs maximales de chaque champ de cette couche :

>>> layer.field_widths
[80, 11, 24, 10]
field_precisions

Renvoie une liste des précisions numériques de chaque champ de cette couche. Pour les champs non numériques, la valeur renvoyée n’a pas de sens (et définie à 0) :

>>> layer.field_precisions
[0, 0, 15, 0]
extent

Renvoie l’étendue spatiale de cette couche, sous forme d’objet Envelope:

>>> layer.extent.tuple
(-104.609252, 29.763374, -95.23506, 38.971823)
srs

Propriété renvoyant la référence SpatialReference associée à cette couche :

>>> print(layer.srs)
GEOGCS["GCS_WGS_1984",
    DATUM["WGS_1984",
        SPHEROID["WGS_1984",6378137,298.257223563]],
    PRIMEM["Greenwich",0],
    UNIT["Degree",0.017453292519943295]]

Si la couche Layer n’a pas d’information associée de référence spatiale, c’est None qui est renvoyé.

spatial_filter

Propriété pouvant être utilisée pour obtenir ou définir un filtre spatial pour cette couche. Un filtre spatial ne peut être défini qu’avec une instance OGRGeometry, un tuple à 4 éléments représentant une étendue ou la valeur None. Lorsque cette propriété est définie avec une valeur autre que None, seuls les résultats ayant une intersection avec le filtre sont renvoyés lorsqu’on traite la couche en boucle :

>>> print(layer.spatial_filter)
None
>>> print(len(layer))
3
>>> [feat.get('Name') for feat in layer]
['Pueblo', 'Lawrence', 'Houston']
>>> ks_extent = (-102.051, 36.99, -94.59, 40.00) # Extent for state of Kansas
>>> layer.spatial_filter = ks_extent
>>> len(layer)
1
>>> [feat.get('Name') for feat in layer]
['Lawrence']
>>> layer.spatial_filter = None
>>> len(layer)
3
get_fields()

Une méthode qui renvoie une liste des valeurs d’un champ donné pour chaque élément de la couche :

>>> layer.get_fields('Name')
['Pueblo', 'Lawrence', 'Houston']
get_geoms(geos=False)

Une méthode qui renvoie une liste contenant l’objet géométrique de chaque élément de la couche. Si le paramètre facultatif geos est défini à True, les objets géométriques sont convertis en objets GEOSGeometry. Sinon ils sont renvoyés comme objets OGRGeometry:

>>> [pt.tuple for pt in layer.get_geoms()]
[(-104.609252, 38.255001), (-95.23506, 38.971823), (-95.363151, 29.763374)]
test_capability(capability)

Renvoie une valeur booléenne indiquant si cette couche prend en charge la capacité indiquée (une chaîne). Voici quelques exemples de capacités possibles : 'RandomRead', 'SequentialWrite', 'RandomWrite', 'FastSpatialFilter', 'FastFeatureCount', 'FastGetExtent', 'CreateField', 'Transactions', 'DeleteFeature' et 'FastSetNextByIndex'.

Feature

class Feature

Feature adapte un objet OGR. Les objets Feature ne sont jamais créés directement. Ils sont obtenus à partir d’un objet Layer. Chaque objet Feature est composé d’une partie géométrique et d’un ensemble de champs contenant des propriétés supplémentaires. La partie géométrique d’un élément est accessible par la propriété geom qui renvoie un objet OGRGeometry. Un objet Feature se comporte comme un conteneur Python standard pour ses champs qu’il renvoie sous forme d’objets Field: un champ est accessible directement par son indice ou son nom, mais il est aussi possible de parcourir en boucle les champs d’un élément, par exemple dans une boucle for.

geom

Renvoie la partie géométrique de l’élément sous forme d’objet OGRGeometry:

>>> city.geom.tuple
(-104.609252, 38.255001)
get

Une méthode qui renvoie la valeur du champ indiqué (par son nom) pour cet élément, et non pas un objet Field:

>>> city.get('Population')
102121
geom_type

Renvoie le type géométrique de cet élément, sous forme d’objet OGRGeomType. Le type est le même pour tous les éléments d’une même couche et est équivalent à la propriété Layer.geom_type de l’objet Layer d’où il provient.

num_fields

Renvoie le nombre de champs de données associés à cet élément. Ce nombre est identique pour tous les éléments d’une même couche et est équivalent à la propriété Layer.num_fields de l’objet Layer d’où il provient.

fields

Renvoie une liste des noms de champs de données associés à cet élément. Cette liste est identique pour tous les éléments d’une même couche et est équivalente à la propriété Layer.fields de l’objet Layer d’où il provient.

fid

Renvoie l’identifiant d’élément dans la couche :

>>> city.fid
0
layer_name

Renvoie le nom de la couche Layer d’où l’élément provient. Ce nom est identique pour tous les éléments d’une même couche :

>>> city.layer_name
'cities'
index

Une méthode qui renvoie l’indice du nom de champ indiqué. Cet indice est identique pour tous les éléments d’une même couche :

>>> city.index('Population')
1

Field

class Field
name

Renvoie le nom de ce champ :

>>> city['Name'].name
'Name'
type

Renvoie le type OGR de ce champ sous forme de nombre entier. Le dictionnaire FIELD_CLASSES fait correspondre ces valeurs à des sous-classes de Field:

>>> city['Density'].type
2
type_name

Renvoie une chaîne contenant le nom du type de données de ce champ :

>>> city['Name'].type_name
'String'
value

Renvoie la valeur de ce champ. La classe Field elle-même renvoie la valeur sous forme de chaîne, mais chaque sous-classe renvoie la valeur sous la forme qui lui est la plus appropriée :

>>> city['Population'].value
102121
width

Renvoie la largeur de ce champ :

>>> city['Name'].width
80
precision

Renvoie la précision numérique de ce champ. Pour les champs non numériques, cette valeur n’a pas de sens (et elle est définie à 0) :

>>> city['Density'].precision
15
as_double()

Renvoie la valeur du champ sous forme d’un nombre à virgule à double précision :

>>> city['Density'].as_double()
874.7
as_int()

Renvoie la valeur du champ sous forme d’un nombre entier :

>>> city['Population'].as_int()
102121
as_string()

Renvoie la valeur du champ sous forme de chaîne :

>>> city['Name'].as_string()
'Pueblo'
as_datetime()

Renvoie la valeur du champ sous forme d’un tuple de composants date et heure :

>>> city['Created'].as_datetime()
(c_long(1999), c_long(5), c_long(23), c_long(0), c_long(0), c_long(0), c_long(0))

Driver

class Driver(dr_input)

La classe Driver est utilisée en interne pour adapter un pilote de source OGR DataSource.

driver_count

Renvoie le nombre de pilotes vectoriels OGR actuellement inscrits.

Objets géométriques OGR

OGRGeometry

Les objets OGRGeometry partagent des fonctionnalités avec les objets GEOSGeometry et constituent des adaptations fines autour de la représentation géométrique interne à OGR. De ce fait, ils permettent d’accéder de manière plus efficace aux données lorsqu’on utilise une source DataSource. Contrairement à sa contrepartie GEOS, un objet OGRGeometry prend en charge les systèmes de référence spatiale et les transformations de coordonnées :

>>> from django.contrib.gis.gdal import OGRGeometry
>>> polygon = OGRGeometry('POLYGON((0 0, 5 0, 5 5, 0 5))')
class OGRGeometry(geom_input, srs=None)

Cet objet est un adaptateur de la classe OGR Geometry. Ces objets sont directement créés à partir du paramètre geom_input donné, qui peut contenir une chaîne au format WKT, HEX ou GeoJSON, un tampon buffer contenant des données WKB ou un objet OGRGeomType. Ces objets sont également renvoyés par l’attribut Feature.geom, lors de la lecture de données vectorielles à partir de Layer (qui fait elle-même partie d’un objet DataSource).

classmethod from_bbox(bbox)

Construit un Polygon à partir du rectangle englobant indiqué (un tuple à 4 éléments).

__len__()

Renvoie le nombre de points dans une ligne LineString, le nombre de segments d’un Polygon ou le nombre d’objets géométriques dans une collection GeometryCollection. Ne s’applique pas aux autres types géométriques.

__iter__()

Effectue une itération sur les points d’une ligne LineString, sur les segments d’un Polygon ou sur les objets géométriques d’une collection GeometryCollection. Ne s’applique pas aux autres types géométriques.

__getitem__()

Renvoie le point à l’indice donné d’une ligne LineString, le segment intérieur à l’indice donnée d’un Polygon ou l’objet géométrique à l’indice donné d’une collection GeometryCollection. Ne s’applique pas aux autres types géométriques.

dimension

Renvoie les dimensions de coordonnées de cet objet géométrique. 0 pour les points, 1 pour les lignes et 2 pour les surfaces :

>> polygon.dimension
2
coord_dim

Renvoie ou définit les dimensions de coordonnées de cet objet géométrique. Par exemple, la valeur correspond à 2 pour les objets géométriques en deux dimensions.

geom_count

Renvoie le nombre d’éléments dans cet objet géométrique :

>>> polygon.geom_count
1
point_count

Renvoie le nombre de points utilisés pour définir cet objet géométrique :

>>> polygon.point_count
4
num_points

Alias de point_count.

num_coords

Alias de point_count.

geom_type

Renvoie le type de cet objet géométrique, sous forme d’objet OGRGeomType.

geom_name

Renvoie le nom du type de cet objet géométrique :

>>> polygon.geom_name
'POLYGON'
area

Renvoie l’aire de cet objet géométrique ou 0 pour les objets qui n’ont pas d’aire :

>>> polygon.area
25.0
envelope

Renvoie l’enveloppe de cet objet géométrique sous forme d’objet Envelope.

extent

Renvoie l’enveloppe de cet objet géométrique sous forme de tuple à 4 éléments au lieu d’un objet Envelope:

>>> point.extent
(0.0, 0.0, 5.0, 5.0)
srs

Cette propriété contrôle la référence spatiale de cet objet géométrique, ou None si aucun système de référence spatiale ne lui a été attribué. Si un tel attribut existe, la propriété renvoie un objet SpatialReference. La propriété peut être définie avec un autre objet SpatialReference ou tout autre contenu accepté par SpatialReference. Exemple :

>>> city.geom.srs.name
'GCS_WGS_1984'
srid

Renvoie ou définit l’identifiant de référence spatiale correspondant à l’objet SpatialReference de cet objet géométrique. Renvoie None si aucune information de référence spatiale n’est associé à cet objet, ou s’il n’est pas possible de déterminer le code SRID.

geos

Renvoie un objet GEOSGeometry correspondant à cet objet géométrique.

gml

Renvoie la représentation textuelle de cet objet géométrique au format GML :

>>> OGRGeometry('POINT(1 2)').gml
'<gml:Point><gml:coordinates>1,2</gml:coordinates></gml:Point>'
hex

Renvoie la représentation textuelle de cet objet géométrique au format HEX WKB :

>>> OGRGeometry('POINT(1 2)').hex
'0101000000000000000000F03F0000000000000040'
json

Renvoie la représentation textuelle de cet objet géométrique au format JSON :

>>> OGRGeometry('POINT(1 2)').json
'{ "type": "Point", "coordinates": [ 1.000000, 2.000000 ] }'
kml

Renvoie la représentation textuelle de cet objet géométrique au format KML :

wkb_size

Renvoie la taille du tampon WKB nécessaire pour contenir une représentation WKB de cet objet géométrique :

>>> OGRGeometry('POINT(1 2)').wkb_size
21
wkb

Renvoie un tampon buffer contenant une représentation WKB de cet objet géométrique.

wkt

Renvoie la représentation textuelle de cet objet géométrique au format WKT :

ewkt

Renvoie la représentation EWKT de cet objet géométrique.

clone()

Renvoie un nouveau clone OGRGeometry de cet objet géométrique.

close_rings()

S’il existe un segment non fermé dans cet objet géométrique, cette routine le ferme en ajoutant le point de départ en fin de segment :

>>> triangle = OGRGeometry('LINEARRING (0 0,0 1,1 0)')
>>> triangle.close_rings()
>>> triangle.wkt
'LINEARRING (0 0,0 1,1 0,0 0)'
transform(coord_trans, clone=False)

Transforme cet objet géométrique en un système de référence spatiale différent. Cette méthode accepte un objet CoordTransform, un objet SpatialReference ou toute autre contenu accepté par SpatialReference (y compris une chaîne WKT de référence spatiale, une chaîne PROJ.4 ou un code SRID nombre entier). Par défaut, rien n’est renvoyé et l’objet géométrique est lui-même transformé. Cependant, si le paramètre clone est défini à True, un clone transformé de cet objet géométrique est renvoyé.

intersects(other)

Renvoie True si cet objet géométrique possède une intersection avec other, sinon renvoie False.

equals(other)

Renvoie True si cet objet géométrique est équivalent à other, sinon renvoie False.

disjoint(other)

Renvoie True si cet objet géométrique est spatialement disjoint de other (c’est-à-dire qu’il n’a pas d’intersection avec lui), sinon renvoie False.

touches(other)

Renvoie True si cet objet géométrique touche other, sinon renvoie False.

crosses(other)

Renvoie True si cet objet géométrique se croise avec other, sinon renvoie False.

within(other)

Renvoie True si cet objet géométrique est contenu dans other, sinon renvoie False.

contains(other)

Renvoie True si cet objet géométrique contient other, sinon renvoie False.

overlaps(other)

Renvoie True si cet objet géométrique recouvre partiellement other, sinon renvoie False.

boundary()

Les limites de cet objet géométrique, sous forme de nouvel objet OGRGeometry.

convex_hull

Le polygone convexe le plus petit contenant cet objet géométrique, sous forme de nouvel objet OGRGeometry.

difference()

Renvoie la région constituée par la différence entre cet objet géométrique et other, sous forme de nouvel objet OGRGeometry.

intersection()

Renvoie la région constituée par l’intersection entre cet objet géométrique et other, sous forme de nouvel objet OGRGeometry.

sym_difference()

Renvoie la région constituée par la différence symétrique entre cet objet géométrique et other, sous forme de nouvel objet OGRGeometry.

union()

Renvoie la région constituée par l’union entre cet objet géométrique et other, sous forme de nouvel objet OGRGeometry.

tuple

Renvoie les coordonnées d’un point géométrique sous forme de tuple, les coordonnées d’une ligne géométrique sous forme de tuple de tuples, et ainsi de suite :

>>> OGRGeometry('POINT (1 2)').tuple
(1.0, 2.0)
>>> OGRGeometry('LINESTRING (1 2,3 4)').tuple
((1.0, 2.0), (3.0, 4.0))
coords

Un alias de tuple.

class Point
x

Renvoie la coordonnée X de ce point :

>>> OGRGeometry('POINT (1 2)').x
1.0
y

Renvoie la coordonnée Y de ce point :

>>> OGRGeometry('POINT (1 2)').y
2.0
z

Renvoie la coordonnée Z de ce point, ou None si ce point n’a pas de coordonnée Z :

>>> OGRGeometry('POINT (1 2 3)').z
3.0
class LineString
x

Renvoie une liste des coordonnées X de cette ligne :

>>> OGRGeometry('LINESTRING (1 2,3 4)').x
[1.0, 3.0]
y

Renvoie une liste des coordonnées Y de cette ligne :

>>> OGRGeometry('LINESTRING (1 2,3 4)').y
[2.0, 4.0]
z

Renvoie une liste des coordonnées Z de cette ligne, ou None si ce point n’a pas de coordonnée Z :

>>> OGRGeometry('LINESTRING (1 2 3,4 5 6)').z
[3.0, 6.0]
class Polygon
shell

Renvoie l’enveloppe ou le segment extérieur de ce polygone, sous forme de géométrie LinearRing.

exterior_ring

Un alias de shell.

centroid

Renvoie un Point qui représente le centroïde de ce polygone.

class GeometryCollection
add(geom)

Ajoute un objet géométrique à cette collection géométrique. Non applicable aux autres types géométriques.

OGRGeomType

class OGRGeomType(type_input)

Cette classe permet de représenter un type de géométrie OGR en partant de plusieurs types de valeurs :

>>> from django.contrib.gis.gdal import OGRGeomType
>>> gt1 = OGRGeomType(3)             # Using an integer for the type
>>> gt2 = OGRGeomType('Polygon')     # Using a string
>>> gt3 = OGRGeomType('POLYGON')     # It's case-insensitive
>>> print(gt1 == 3, gt1 == 'Polygon') # Equivalence works w/non-OGRGeomType objects
True True
name

Renvoie une forme de chaîne raccourcie du type de géométrie OGR :

>>> gt1.name
'Polygon'
num

Renvoie le numéro correspondant au type de géométrie OGR :

>>> gt1.num
3
django

Renvoie le type de champ Django (une sous-classe de GeometryField) à utiliser pour stocker ce type OGR, ou None s’il n’existe pas de type de champ Django approprié :

>>> gt1.django
'PolygonField'

Envelope

class Envelope(*args)

Représente une structure d’enveloppe OGR contenant les coordonnées X et Y minimales et maximales d’un rectangle englobant. Les noms de variables sont compatibles avec la structure C de l’objet OGR Envelope.

min_x

La valeur minimum de la coordonnée X.

min_y

La valeur maximum de la coordonnée X.

max_x

La valeur minimum de la coordonnée Y.

max_y

La valeur maximum de la coordonnée Y.

ur

La coordonnée supérieure droite, sous forme de tuple.

ll

La coordonnée inférieure gauche, sous forme de tuple.

tuple

Un tuple représentant l’enveloppe.

wkt

Une chaîne représentant cette enveloppe sous forme d’un polygone au format WKT.

expand_to_include(*args)

Objets de systèmes de coordonnées

SpatialReference

class SpatialReference(srs_input)

Les objets de référence spatiale sont initialisés selon le paramètre srs_input indiqué, qui peut être dans l’un des formats suivants :

  • OGC Well Known Text (WKT) (une chaîne)

  • code EPSG (nombre entier ou chaîne)

  • chaîne PROJ.4

  • Une chaîne de raccourci correspondant à des standards bien connus ('WGS84', 'WGS72', 'NAD27', 'NAD83')

Exemple :

>>> wgs84 = SpatialReference('WGS84') # shorthand string
>>> wgs84 = SpatialReference(4326) # EPSG code
>>> wgs84 = SpatialReference('EPSG:4326') # EPSG string
>>> proj4 = '+proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs '
>>> wgs84 = SpatialReference(proj4) # PROJ.4 string
>>> wgs84 = SpatialReference("""GEOGCS["WGS 84",
DATUM["WGS_1984",
     SPHEROID["WGS 84",6378137,298.257223563,
         AUTHORITY["EPSG","7030"]],
     AUTHORITY["EPSG","6326"]],
 PRIMEM["Greenwich",0,
     AUTHORITY["EPSG","8901"]],
 UNIT["degree",0.01745329251994328,
     AUTHORITY["EPSG","9122"]],
 AUTHORITY["EPSG","4326"]]""") # OGC WKT
__getitem__(target)

Renvoie la valeur correspondant à la chaîne de nœud d’attribut, None si le nœud n’existe pas. Accepte aussi un tuple (cible, enfant) en paramètre, où enfant est l’indice de l’attribut dans la structure WKT. Par exemple :

>>> wkt = 'GEOGCS["WGS 84", DATUM["WGS_1984, ... AUTHORITY["EPSG","4326"]]')
>>> srs = SpatialReference(wkt) # could also use 'WGS84', or 4326
>>> print(srs['GEOGCS'])
WGS 84
>>> print(srs['DATUM'])
WGS_1984
>>> print(srs['AUTHORITY'])
EPSG
>>> print(srs['AUTHORITY', 1]) # The authority value
4326
>>> print(srs['TOWGS84', 4]) # the fourth value in this wkt
0
>>> print(srs['UNIT|AUTHORITY']) # For the units authority, have to use the pipe symbol.
EPSG
>>> print(srs['UNIT|AUTHORITY', 1]) # The authority value for the units
9122
attr_value(target, index=0)

La valeur de l’attribut correspondant au nœud cible indiqué (par ex. 'PROJCS'). Le paramètre index désigne un indice de l’enfant à renvoyer.

auth_name(target)

Renvoie le nom d’autorité correspondant au nœud cible indiqué.

auth_code(target)

Renvoie le code d’autorité correspondant au nœud cible indiqué.

clone()

Renvoie un clone de cet objet de référence spatiale.

identify_epsg()

Cette méthode inspecte la représentation WKT de cet objet SpatialReference et ajoute des nœuds d’autorité EPSG lorsqu’un identifiant EPSG s’applique.

from_esri()

Transforme cet objet SpatialReference du format ESRI au format EPSG.

to_esri()

Transforme cet objet SpatialReference en format ESRI.

validate()

Vérifie si la référence spatiale est valide et génère une exception quand ce n’est pas le cas.

import_epsg(epsg)

Importe une référence spatiale à partir d’un code EPSG.

import_proj(proj)

Importe une référence spatiale à partir d’une chaîne PROJ.4.

import_user_input(user_input)
import_wkt(wkt)

Importe une référence spatiale à partir d’une chaîne WKT.

import_xml(xml)

Importe une référence spatiale à partir d’une chaîne XML.

name

Renvoie le nom de cette référence spatiale.

srid

Renvoie le SRID de l’autorité de premier niveau, ou None si elle n’est pas définie.

linear_name

Renvoie le nom d’unité linéaire.

linear_units

Renvoie la valeur d’unité linéaire.

angular_name

Renvoie le nom d’unité d’angle.

angular_units

Renvoie la valeur d’unité d’angle.

units

Renvoie un tuple binaire des valeur et nom d’unité, et détermine automatiquement s’il faut renvoyer l’unité linéaire ou l’unité d’angle.

ellipsoid

Renvoie un tuple des paramètres d’ellispoïde de cette référence spatiale : (demi-grand axe, demi-petit axe, inverse de l’aplatissement).

semi_major

Renvoie le demi-grand axe d’ellipsoïde de cette référence spatiale.

semi_minor

Renvoie le demi-petit axe d’ellipsoïde de cette référence spatiale.

inverse_flattening

Renvoie l’inverse de l’aplatissement d’ellipsoïde de cette référence spatiale.

geographic

Renvoie True si cette référence spatiale est géographique (le nœud racine est GEOGCS).

local

Renvoie True si cette référence spatiale est locale (le nœud racine est LOCAL_CS).

projected

Renvoie True si cette référence spatiale est un système de coordonnées projeté (le nœud racine est PROJCS).

wkt

Renvoie la représentation WKT de cette référence spatiale.

pretty_wkt

Renvoie la représentation « conviviale » de la chaîne WKT.

proj

Renvoie la représentation PROJ.4 de cette référence spatiale.

proj4

Alias de SpatialReference.proj.

xml

Renvoie la représentation XML de cette référence spatiale.

CoordTransform

class CoordTransform(source, target)

Représente une transformation de système de coordonnées. Elle est initialisée avec deux instances SpatialReference représentant respectivement les systèmes de coordonnées source et cible. Ces objets sont appropriés lorsqu’une même transformation de coordonnées se répète plusieurs fois pour différents objets géométriques :

>>> ct = CoordTransform(SpatialReference('WGS84'), SpatialReference('NAD83'))
>>> for feat in layer:
...     geom = feat.geom # getting clone of feature geometry
...     geom.transform(ct) # transforming

Objets de données matricielles

New in Django 1.8.

GDALRaster

GDALRaster est un adaptateur autour de l’objet de source de données matricielles GDAL qui prend en charge la lecture de données à partir d’une variété de formats de fichiers et de sources de données géospatiales que GDAL sait traiter à l’aide d’une interface simple et cohérente. Chaque source de données est représentée par un objet GDALRaster contenant une ou plusieurs couches de données nommées bandes. Chaque bande représentée par un objet GDALBand contient des données d’images géoréférencées. Par exemple, un image RVB est représentée par trois bandes : une pour le rouge, une pour le vert et une pour le bleu.

Note

Pour des données matricielles, il n’y a pas de différence entre une instance d’objet matriciel et sa source de données. Contrairement aux objets Geometry, les objets GDALRaster représentent toujours une source de données. Des structures matricielles temporaires peuvent être créées en mémoire à l’aide du pilote adéquat, mais elles seront de la même classe que les sources matricielles basées sur des fichiers.

class GDALRaster(ds_input, write=False)

Le constructeur de GDALRaster accepte deux paramètres. Le premier paramètre définit la source matricielle, il s’agit soit d’un chemin vers un fichier ou de données spatiales avec des valeurs définissant les propriétés d’une nouvelle structure matricielle (telles que la taille et le nom). Dans le cas d’un chemin vers un fichier, le second paramètre indique si la structure matricielle doit être ouverte avec un accès en écriture. Dans le cas de données brutes, les paramètres width, height et srid sont obligatoires. L’exemple suivant montre comment des matrices peuvent être créées à partir de différentes sources (à l’aide de données d’exemples provenant des tests GeoDjango, voir aussi la section Données d’exemple) :

>>> from django.contrib.gis.gdal import GDALRaster
>>> rst = GDALRaster('/path/to/your/raster.tif', write=False)
>>> rst.name
'/path/to/your/raster.tif'
>>> rst.width, rst.height            # This file has 163 x 174 pixels
(163, 174)
>>> rst = GDALRaster({'srid': 4326, 'width': 1, 'height': 2, 'datatype': 1
...                   'bands': [{'data': [0, 1]}]}) # Creates in-memory raster
>>> rst.srs.srid
4326
>>> rst.width, rst.height
(1, 2)
>>> rst.bands[0].data()
array([[0, 1]], dtype=int8)
Changed in Django 1.9:

Les objets GDALRaster peuvent maintenant être instanciées directement à partir de données brutes. Les propriétés suivantes peuvent être définies : srs, geotransform, origin, scale, et skew.

name

Le nom de la source qui est équivalent au chemin du fichier lu ou le nom fourni au moment de l’instanciation.

>>> GDALRaster({'width': 10, 'height': 10, 'name': 'myraster', 'srid': 4326}).name
'myraster'
driver

Le nom du pilote GDAL utilisé pour traiter le fichier d’entrée. Pour les objets GDALRaster créés à partir d’un fichier, le type de pilote est automatiquement détecté. La création de structures matricielles à partir de rien utilise par défaut le pilote en mémoire ('MEM'), mais il peut être modifié en fonction des besoins. Par exemple, indiquez GTiff pour un fichier GeoTiff. Pour une liste de types de fichiers, voir aussi la liste des formats matriciels GDAL.

L’exemple suivant montre une création d’objet matriciel en mémoire :

>>> GDALRaster({'width': 10, 'height': 10, 'srid': 4326}).driver.name
'MEM'

L’exemple suivant montre la création d’un objet matriciel basé sur un fichier GeoTiff :

>>> import tempfile
>>> rstfile = tempfile.NamedTemporaryFile(suffix='.tif')
>>> rst = GDALRaster({'driver': 'GTiff', 'name': rstfile.name, 'srid': 4326,
...                   'width': 255, 'height': 255, 'nr_of_bands': 1})
>>> rst.name
'/tmp/tmp7x9H4J.tif'           # The exact filename will be different on your computer
>>> rst.driver.name
'GTiff'
width

La largeur de la source en pixels (axe X).

>>> GDALRaster({'width': 10, 'height': 20, 'srid': 4326}).width
10
height

La hauteur de la source en pixels (axe Y).

>>> GDALRaster({'width': 10, 'height': 20, 'srid': 4326}).height
20
srs

Le système de référence spatiale de la structure matricielle, sous forme d’instance SpatialReference. Ce système peut être modifié en définissant sa valeur à un autre objet SpatialReference ou en fournissant toute valeur acceptée par le constructeur de SpatialReference.

>>> rst = GDALRaster({'width': 10, 'height': 20, 'srid': 4326})
>>> rst.srs.srid
4326
>>> rst.srs = 3086
>>> rst.srs.srid
3086
geotransform

La matrice de transformation linéaire utilisée pour géoréférencer la source, sous forme de tuple de six coefficients qui font correspondre les coordonnées de pixel/ligne dans un espace géoréférencé en utilisant la relation suivante :

Xgeo = GT(0) + Xpixel*GT(1) + Yline*GT(2)
Ygeo = GT(3) + Xpixel*GT(4) + Yline*GT(5)

Les mêmes valeurs peuvent être obtenues en accédant aux propriétés origin (indices 0 et 3), scale (indices 1 et 5) et skew (indices 2 et 4).

La valeur par défaut est [0.0, 1.0, 0.0, 0.0, 0.0, -1.0].

>>> rst = GDALRaster({'width': 10, 'height': 20, 'srid': 4326})
>>> rst.geotransform
[0.0, 1.0, 0.0, 0.0, 0.0, -1.0]
origin

Coordonnées de l’origine en haut à gauche de l’image matricielle dans le système de référence spatial de la source, sous forme d’objet point avec ses composantes x et y.

>>> rst = GDALRaster({'width': 10, 'height': 20, 'srid': 4326})
>>> rst.origin
[0.0, 0.0]
>>> rst.origin.x = 1
>>> rst.origin
[1.0, 0.0]
scale

Largeur et hauteur de pixel utilisés pour le géoréférencement de l’image matricielle, sous forme d’objet point avec ses composantes x et y. Voir geotransform pour plus d’informations.

>>> rst = GDALRaster({'width': 10, 'height': 20, 'srid': 4326})
>>> rst.scale
[1.0, -1.0]
>>> rst.scale.x = 2
>>> rst.scale
[2.0, -1.0]
skew

Coefficients de distortion utilisés pour le géoréférencement de l’image matricielle, sous forme d’objet point avec ses composantes x et y. Dans le cas d’images orientées au nord, ces coefficients valent tous deux 0.

>>> rst = GDALRaster({'width': 10, 'height': 20, 'srid': 4326})
>>> rst.skew
[0.0, 0.0]
>>> rst.skew.x = 3
>>> rst.skew
[3.0, 0.0]
extent

Étendue (valeurs limites) de la source matricielle, sous forme de tuple à 4 composants (xmin, ymin, xmax, ymax) exprimés dans le système de référence spatial de la source.

>>> rst = GDALRaster({'width': 10, 'height': 20, 'srid': 4326})
>>> rst.extent
(0.0, -20.0, 10.0, 0.0)
>>> rst.origin.x = 100
>>> rst.extent
(100.0, -20.0, 110.0, 0.0)
bands

Liste de toutes les bandes de la source, sous forme d’instances GDALBand.

>>> rst = GDALRaster({"width": 1, "height": 2, 'srid': 4326,
...                   "bands": [{"data": [0, 1]}, {"data": [2, 3]}]})
>>> len(rst.bands)
2
>>> rst.bands[1].data()
array([[ 2.,  3.]], dtype=float32)
warp(ds_input, resampling='NearestNeighbour', max_error=0.0)
New in Django 1.9.

Renvoie une version déformée de cet objet matriciel.

Les paramètres de déformation peuvent être donnés dans le paramètre ds_input. L’emploi de ds_input est semblable au même paramètre du constructeur de la classe. Il s’agit d’un dictionnaire doté des caractéristiques de la matrice cible. Les clés de dictionnaire autorisées sont width (largeur), height (hauteur), SRID, origin, scale (échelle), skew (obliquité), datatype (type de données), driver (pilote) et name (nom de fichier).

Par défaut, les fonctions de déformation maintiennent la plupart des paramètres égaux aux valeurs initiales de l’objet matriciel, de sorte que seuls les paramètres qui doivent être modifiés ont besoin d’être fournis. Notez que cela inclut le pilote, donc pour les objets matriciels basés sur des fichiers, la fonction de déformation va créer une nouvelle structure sur le disque.

Le seul paramètre qui est défini différemment de l’objet matriciel source est le nom. La valeur par défaut du nom de matrice est le nom de la source combinée avec '_copy' + nom_pilote_source. Pour les objets matriciels basés sur des fichiers, il est recommandé de fournir le chemin du fichier de la matrice cible.

L’algorithme de ré-échantillonnage utilisé pour la déformation peut être indiqué par le paramètre resampling. La valeur par défaut est NearestNeighbor et les autres valeurs autorisées sont Bilinear, Cubic, CubicSpline, Lanczos, Average, et Mode.

Le paramètre max_error peut être utilisé pour indiquer l’erreur maximale autorisée, mesurée en pixels d’entrée, pour l’approximation de la transformation. La valeur par défaut est de 0.0 ce qui implique des calculs exacts.

Pour les familiers de GDAL, cette fonction présente des capacités identiques à l’utilitaire en ligne de commande gdalwarp.

Par exemple, la fonction warp peut être utilisée pour transformer une image matricielle au double de son échelle de pixels d’origine :

>>> rst = GDALRaster({
...     "width": 6, "height": 6, "srid": 3086,
...     "origin": [500000, 400000],
...     "scale": [100, -100],
...     "bands": [{"data": range(36), "nodata_value": 99}]
... })
>>> target = rst.warp({"scale": [200, -200], "width": 3, "height": 3})
>>> target.bands[0].data()
array([[  7.,   9.,  11.],
       [ 19.,  21.,  23.],
       [ 31.,  33.,  35.]], dtype=float32)
transform(srid, driver=None, name=None, resampling='NearestNeighbour', max_error=0.0)
New in Django 1.9.

Renvoie une version transformée de cet objet matriciel en fonction du code SRID indiqué.

Cette fonction transforme l’objet matriciel actuel dans un nouveau système de référence spatial qui peut être indiqué avec srid. Elle calcule les limites et l’échelle de la matrice dans le nouveau système de référence spatial et la déforme à l’aide de la fonction warp.

Par défaut, c’est le pilote de la matrice source qui est utilisé et son nom est composé du nom d’origine et de la chaîne '_copy' + nom_pilote_source. Il est possible d’indiquer un autre pilote ou un autre nom avec les paramètres driver et name.

L’algorithme de ré-échantillonnage par défaut est NearestNeighbour mais il peut être modifié par le paramètre resampling. L’erreur maximale autorisée du ré-échantillonnage est de 0.0 par défaut mais elle peut être modifiée par le paramètre max_error. Consultez la documentation de warp pour plus de détails sur ces paramètres.

>>> rst = GDALRaster({
...     "width": 6, "height": 6, "srid": 3086,
...     "origin": [500000, 400000],
...     "scale": [100, -100],
...     "bands": [{"data": range(36), "nodata_value": 99}]
... })
>>> target = rst.transform(4326)
>>> target.origin
[-82.98492744885776, 27.601924753080144]

GDALBand

class GDALBand

Les instances GDALBand ne sont pas créées explicitement, mais plutôt obtenues à partir d’un objet GDALRaster, au moyen de son attribut bands. Ces instances contiennent les valeurs de pixel réelles de l’image matricielle.

description

Le nom ou la description de la bande, le cas échéant.

width

La largeur de la bande en pixels (axe X).

height

La hauteur de la bande en pixels (axe Y).

pixel_count
New in Django 1.9.

Le nombre total de pixels dans cette bande. Il est égal à width * height.

min

La valeur de pixel minimale de la bande (à l’exclusion de la valeur « no data »).

max

La valeur de pixel maximale de la bande (à l’exclusion de la valeur « no data »).

nodata_value

La valeur « no data » d’une bande est généralement un marqueur spécial servant à identifier les pixels qui ne sont pas des données valides. De tels pixels ne sont généralement pas affichés et ne contribuent pas non plus aux opérations d’analyse.

Changed in Django 1.9:

Cette propriété peut maintenant aussi être définie.

datatype(as_string=False)

Le type de données contenu dans la bande, sous forme de constante entière entre 0 (inconnu) et 11. Si as_string vaut True, le type de données est renvoyé sous forme de chaîne avec les valeurs possibles suivantes : GDT_Unknown, GDT_Byte, GDT_UInt16, GDT_Int16, GDT_UInt32, GDT_Int32, GDT_Float32, GDT_Float64, GDT_CInt16, GDT_CInt32, GDT_CFloat32 et GDT_CFloat64.

data(data=None, offset=None, size=None)
New in Django 1.9.

L’accesseur aux valeurs de pixel de la bande GDALBand. Renvoie le tableau complet des données si aucun paramètre n’est fourni. Il est possible de ne récupérer qu’un sous-ensemble de la matrice de pixels en spécifiant une taille de bloc et un décalage sous forme de tuples.

Si NumPy est disponible, les données sont renvoyées sous forme de tableau NumPy. Pour des raisons de performance, il est fortement recommandé d’utiliser NumPy.

Les données sont écrites dans la bande GDALBand si le paramètre data est fourni. Les types de données acceptés sont : packed string, buffer, list, array et array NumPy. Le nombre d’éléments dans les données doit correspondre au nombre total de pixels dans la bande, ou au nombre de pixels d’un bloc spécifique de valeurs de pixels si les paramètres offset et size sont fournis.

Par exemple :

>>> rst = GDALRaster({'width': 4, 'height': 4, 'srid': 4326, 'datatype': 1, 'nr_of_bands': 1})
>>> bnd = rst.bands[0]
>>> bnd.data(range(16))
>>> bnd.data()
array([[ 0,  1,  2,  3],
       [ 4,  5,  6,  7],
       [ 8,  9, 10, 11],
       [12, 13, 14, 15]], dtype=int8)
>>> bnd.data(offset=(1, 1), size=(2, 2))
array([[ 5,  6],
       [ 9, 10]], dtype=int8)
>>> bnd.data(data=[-1, -2, -3, -4], offset=(1, 1), size=(2, 2))
>>> bnd.data()
array([[ 0,  1,  2,  3],
       [ 4, -1, -2,  7],
       [ 8, -3, -4, 11],
       [12, 13, 14, 15]], dtype=int8)
>>> bnd.data(data='\x9d\xa8\xb3\xbe', offset=(1, 1), size=(2, 2))
>>> bnd.data()
array([[  0,   1,   2,   3],
       [  4, -99, -88,   7],
       [  8, -77, -66,  11],
       [ 12,  13,  14,  15]], dtype=int8)

Réglages

GDAL_LIBRARY_PATH

Une chaîne indiquant l’emplacement de la bibliothèque GDAL. Typiquement, ce réglage n’est utilisé que si la bibliothèque GDAL ne se trouve pas à un emplacement standard (par ex. /home/john/lib/libgdal.so).

Back to Top