# Documentation Django 5.2.8

# API de GDAL

## Aperçu

GDAL stands for Geospatial Data Abstraction Library, and is a veritable « Swiss army knife » of GIS data functionality. A subset of GDAL is the OGR Simple Features Library, which specializes in reading and writing vector geographic data in a variety of standard formats.

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.

### Données d’exemple

The GDAL/OGR tools described here are designed to help you read in your geospatial data, in order for most of them to be useful you have to have some data to work with. If you’re starting out and don’t yet have any data of your own to use, GeoDjango tests contain a number of data sets that you can use for testing. You can download them here:

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

## Objets sources de données vectorielles

### `DataSource`

`DataSource` is a wrapper for the OGR data source object that supports reading data from a variety of OGR-supported geospatial file formats and data sources using a consistent interface. Each data source is represented by a `DataSource` object which contains one or more layers of data. Each layer, represented by a `Layer` object, contains some number of geographic features (`Feature`), information about the type of features contained in that layer (e.g. points, polygons, etc.), as well as the names and types of any additional fields (`Field`) of data that may be associated with each feature in that layer.

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)

  Returns a boolean indicating whether this layer supports the given capability (a string). Examples of valid capability strings include: `'RandomRead'`, `'SequentialWrite'`, `'RandomWrite'`, `'FastSpatialFilter'`, `'FastFeatureCount'`, `'FastGetExtent'`, `'CreateField'`, `'Transactions'`, `'DeleteFeature'`, and `'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_gml(gml_string)

  Construit un `OGRGeometry` à partir de la chaîne GML donnée.

  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

  is_3d

  Une valeur booléenne indiquant si cet objet géométrique possède des coordonnées Z.

  set_3d(value)

  Une méthode qui ajoute ou enlève la coordonnée de dimension Z.

      >>> p = OGRGeometry("POINT (1 2 3)")
      >>> p.is_3d
      True
      >>> p.set_3d(False)
      >>> p.wkt
      "POINT (1 2)"

  is_measured

  Une valeur booléenne indiquant si cet objet géométrique possède des coordonnées M.

  set_measured(value)

  Une méthode pour ajouter ou enlever la coordonnée de dimension M.

      >>> p = OGRGeometry("POINT (1 2)")
      >>> p.is_measured
      False
      >>> p.set_measured(True)
      >>> p.wkt
      "POINT M (1 2 0)"

  geom_count

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

      >>> polygon.geom_count
      1

  has_curve
  New in Django 5.2.

  Une valeur booléenne indiquant si cet objet géométrique est ou contient une courbe.

  get_linear_geometry()
  New in Django 5.2.

  Renvoie une version linéaire de la géométrie. Si la conversion ne peut pas se faire, c’est l’objet géométrique initial qui est renvoyé.

  get_curve_geometry()
  New in Django 5.2.

  Renvoie une version en courbes de la géométrie. Si la conversion ne peut pas se faire, c’est l’objet géométrique initial qui est renvoyé.

  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

  This property controls the spatial reference for this geometry, or `None` if no spatial reference system has been assigned to it. If assigned, accessing this property returns a `SpatialReference` object. It may be set with another `SpatialReference` object, or any input that `SpatialReference` accepts. Example:

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

  srid

  Returns or sets the spatial reference identifier corresponding to `SpatialReference` of this geometry. Returns `None` if there is no spatial reference information associated with this geometry, or if an SRID cannot be determined.

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

  centroid

  Renvoie un `Point` qui représente le centroïde de cet objet géométrique.

  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

  m

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

      >>> OGRGeometry("POINT ZM (1 2 3 4)").m
      4.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]

  m

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

      >>> OGRGeometry("LINESTRING(0 1 2 10, 1 2 3 11, 2 3 4 12)").m
      [10.0, 11.0, 12.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`.

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

  - 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
      >>> proj = "+proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs "
      >>> wgs84 = SpatialReference(proj)  # PROJ 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.

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

### `GDALRaster`

`GDALRaster` is a wrapper for the GDAL raster source object that supports reading data from a variety of GDAL-supported geospatial file formats and data sources using a consistent interface. Each data source is represented by a `GDALRaster` object which contains one or more layers of data named bands. Each band, represented by a `GDALBand` object, contains georeferenced image data. For example, an RGB image is represented as three bands: one for red, one for green, and one for blue.

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 définit la source matricielle et le second définit si la matrice doit être ouverte en mode écriture. Pour les matrices nouvellement créées, le second paramètre est ignoré et la nouvelle matrice est toujours créée en mode écriture.

  Le premier paramètre peut prendre trois formes : une chaîne ou un chemin `Path` représentant un chemin de fichier (système de fichiers réel ou GDAL virtuel), un dictionnaire avec des valeurs définissant une nouvelle matrice, ou un objet composé d’octets représentant une fichier matriciel.

  Si le paramètre d’entrée est un chemin de fichier, la matrice est ouverte à partir de ce fichier. Si l’entrée consiste en un dictionnaire de données brutes, les paramètres `width`, `height` et `srid` sont obligatoires. Si l’entrée est un objet d’octets, il sera ouvert en utilisant le système de fichiers virtuel de GDAL.

  Pour une description détaillée sur la façon de créer des images matricielles à l’aide d’une structure dictionnaire, voir Création de géométries matricielles à partir de données. Pour une description détaillée sur la façon de créer des images matricielles dans le système de fichiers virtuel, voir Utilisation du système de fichiers virtuel de GDAL.

  L’exemple suivant montre comment des images matricielles peuvent être créées à partir de différentes sources d’entrée (en utilisant les données d’exemple 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(
      ...     {  # Creates an in-memory raster
      ...         "srid": 4326,
      ...         "width": 4,
      ...         "height": 4,
      ...         "datatype": 1,
      ...         "bands": [
      ...             {
      ...                 "data": (2, 3),
      ...                 "offset": (1, 1),
      ...                 "size": (2, 2),
      ...                 "shape": (2, 1),
      ...                 "nodata_value": 5,
      ...             }
      ...         ],
      ...     }
      ... )
      >>> rst.srs.srid
      4326
      >>> rst.width, rst.height
      (4, 4)
      >>> rst.bands[0].data()
      array([[5, 5, 5, 5],
             [5, 2, 3, 5],
             [5, 2, 3, 5],
             [5, 5, 5, 5]], dtype=uint8)
      >>> rst_file = open("/path/to/your/raster.tif", "rb")
      >>> rst_bytes = rst_file.read()
      >>> rst = GDALRaster(rst_bytes)
      >>> rst.is_vsi_based
      True
      >>> rst.name  # Stored in a random path in the vsimem filesystem.
      '/vsimem/da300bdb-129d-49a8-b336-e410a9428dad'

  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

  srid

    L’identifiant de système de référence spatiale (SRID) de l’objet matriciel. Cette propriété est un raccourci pour définir ou obtenir le SRID à partir de l’attribut `srs`.

        >>> rst = GDALRaster({"width": 10, "height": 20, "srid": 4326})
        >>> rst.srid
        4326
        >>> rst.srid = 3086
        >>> rst.srid
        3086
        >>> rst.srs.srid  # This is equivalent
        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)

    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(srs, driver=None, name=None, resampling='NearestNeighbour', max_error=0.0)

    Transforme cet objet matriciel en un système de référence spatiale (`srs`) différent. ``srs``peut être un objet `SpatialReference` ou tout autre contenu accepté par `SpatialReference` (y compris une chaîne WKT de référence spatiale, une chaîne PROJ ou un code SRID nombre entier).

    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_srs = SpatialReference(4326)
        >>> target = rst.transform(target_srs)
        >>> target.origin
        [-82.98492744885776, 27.601924753080144]

  info

    Renvoie une chaîne avec un résumé de la matrice. C’est équivalent à l’utilitaire en ligne de commande gdalinfo.

  metadata

    Les métadonnées de cette matrice, représentée sous forme de dictionnaire imbriqué. La clé de premier niveau est le domaine de métadonnées. Le deuxième niveau contient les noms et valeurs d’éléments de métadonnées de chaque domaine.

    Pour définir ou mettre à jour un élément de métadonnée, passez l’élément de métadonnée correspondant à la méthode en utilisant la structure imbriquée décrite ci-dessus. Seules les clés présentes dans le dictionnaire donné sont mises à jour ; les autres métadonnées ne sont pas modifiées.

    Pour supprimer un élément de métadonnée, utilisez `None` comme valeur de métadonnée.

        >>> rst = GDALRaster({"width": 10, "height": 20, "srid": 4326})
        >>> rst.metadata
        {}
        >>> rst.metadata = {"DEFAULT": {"OWNER": "Django", "VERSION": "1.0"}}
        >>> rst.metadata
        {'DEFAULT': {'OWNER': 'Django', 'VERSION': '1.0'}}
        >>> rst.metadata = {"DEFAULT": {"OWNER": None, "VERSION": "2.0"}}
        >>> rst.metadata
        {'DEFAULT': {'VERSION': '2.0'}}

  vsi_buffer

    Une représentation binaire de cette matrice. Renvoie `None` pour les matrices qui ne sont pas stockées dans le système de fichiers virtuel de GDAL.

  is_vsi_based

    Une valeur booléenne indiquant si cette matrice est stockée dans le système de fichiers virtuel de GDAL.

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

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

  statistics(refresh=False, approximate=False)

    Calcule des statistiques sur les valeurs de pixel de cette bande. La valeur renvoyée est un tuple ayant la structure suivante : `(minimum, maximum, moyenne, déviation standard)`.

    Si le paramètre `approximate` est défini à `True`, les statistiques peuvent être calculées à partir d’aperçus ou d’un sous-ensemble des tuiles d’images.

    Si le paramètre `refresh` est défini à `True`, les statistiques seront calculées directement à partir des données et le cache sera mis à jour avec les résultats.

    Si une valeur de cache persistante est trouvée, cette valeur est renvoyée. Pour les formats matriciels utilisant les services Persistent Auxiliary Metadata (PAM), les statistiques peuvent être mises en cache dans un fichier annexe. Dans certains cas, ces métadonnées peuvent être désynchronisées avec les valeurs de pixels ou provoquer le renvoi de valeurs d’un appel précédent, ce qui ne correspond pas à la valeur du paramètre `approximate`. Dans de tels cas, utilisez le paramètre `refresh` afin d’obtenir des valeurs à jour et de pouvoir les stocker dans le cache.

    Pour des bandes vides (où toutes les valeurs de pixels sont « pas de données »), toutes les statistiques renvoient `None`.

    Les statistiques peuvent aussi être récupérées directement en accédant aux propriétés `min`, `max`, `mean` et `std`.

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

  mean

    La moyenne de toutes les valeurs de pixels de la bande (à l’exclusion de la valeur « no data »).

  std

    La déviation standard de toutes les valeurs de pixels 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.

    Pour supprimer une valeur « no data » existante, définissez cette propriété à `None`.

  datatype(as_string=False)

    Le type de données contenu dans la bande, sous forme de nombre entier entre 0 (inconnu) et 14. Si `as_string` vaut `True`, le type de données est renvoyé sous forme de chaîne. Consultez la colonne «Type de pixel GDAL» dans le tableau des valeurs de types de données pour connaître les valeurs possibles.

  color_interp(as_string=False)

    L’interprétation de couleur de la bande, sous forme de nombre entier entre 0 et 16. Si `as_string` vaut `True`, le type de données est renvoyé sous forme de chaîne avec les valeurs possibles suivantes : `GCI_Undefined`, `GCI_GrayIndex`, `GCI_PaletteIndex`, `GCI_RedBand`, `GCI_GreenBand`, `GCI_BlueBand`, `GCI_AlphaBand`, `GCI_HueBand`, `GCI_SaturationBand`, `GCI_LightnessBand`, `GCI_CyanBand`, `GCI_MagentaBand`, `GCI_YellowBand`, `GCI_BlackBand`, `GCI_YCbCr_YBand`, `GCI_YCbCr_CbBand` et `GCI_YCbCr_CrBand`. `GCI_YCbCr_CrBand` représente aussi `GCI_Max` parce que les deux correspondent à l’entier 16, mais seul `GCI_YCbCr_CrBand` est renvoyé sous forme de chaîne.

  data(data=None, offset=None, size=None, shape=None)

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

    Si le nombre d’éléments des données est différent du bloc de pixels cible, le paramètre `shape` doit être fourni. La forme `shape` est un tuple qui définit la largeur et la hauteur des données d’entrée en pixels. Les données sont ensuite recopiées pour mettre à jour les valeurs de pixels du bloc sélectionné. C’est utile par exemple pour remplir une bande entière avec une seule valeur.

    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)
        >>> bnd.data([1], shape=(1, 1))
        >>> bnd.data()
        array([[1, 1, 1, 1],
               [1, 1, 1, 1],
               [1, 1, 1, 1],
               [1, 1, 1, 1]], dtype=uint8)
        >>> bnd.data(range(4), shape=(1, 4))
        array([[0, 0, 0, 0],
               [1, 1, 1, 1],
               [2, 2, 2, 2],
               [3, 3, 3, 3]], dtype=uint8)

  metadata

    Les métadonnées de cette bande. La fonctionnalité est identique à `GDALRaster.metadata`.

### Création de géométries matricielles à partir de données

Cette section explique comment créer des géométries matricielles à partir de zéro en utilisant le paramètre `ds_input`.

Une nouvelle géométrie matricielle est créée lorsqu’un `dict` est transmis au constructeur `GDALRaster`. Ce dictionnaire contient les paramètres définissant le nouvel objet, tels que l’origine, la taille ou le système de référence spatial. Il peut aussi contenir des données de pixels et des informations sur le format à utiliser. La géométrie matricielle résultante peut donc être basée sur un fichier ou en mémoire, en fonction du pilote indiqué.

Il n’existe pas de standard de description de données matricielles dans un dictionnaire ou une variante JSON. La définition du dictionnaire d’initialisation pour la classe `GDALRaster` est donc spécifique à Django. Elle s’inspire du format geojson, mais ce dernier est pour l’instant limité aux formats vectoriels.

On peut trouver des exemples d’utilisation des différentes clés de dictionnaire lors de la création de géométries vectorielles dans la documentation des attributs et méthodes correspondants des classes `GDALRaster` et `GDALBand`.

#### Le dictionnaire `ds_input`

Seules quelques clés sont obligatoires dans le dictionnaire `ds_input` servant à créer la géométrie matricielle : `width`, `height` et `srid`. Tous les autres paramètres ont des valeurs par défaut (voir le tableau ci-dessous). La liste des clés pouvant figurer dans le dictionnaire `ds_input` est étroitement liée mais pas totalement identique aux propriétés de `GDALRaster`. Beaucoup de ces paramètres ont une correspondance directe à ces propriétés ; les autres sont décrits ci-dessous.

Le tableau suivant décrit toutes les clés pouvant être définies dans le dictionnaire `ds_input`.

Clé | Valeur par défaut | Utilisation
--- | --- | ---
`srid` | obligatoire | Correspond à l’attribut `srid`
`width` | obligatoire | Correspond à l’attribut `width`
`height` | obligatoire | Correspond à l’attribut `height`
`driver` | `MEM` | Correspond à l’attribut `driver`
`name` | `''` | Voir ci-dessous
`origin` | `0` | Correspond à l’attribut `origin`
`scale` | `0` | Correspond à l’attribut `scale`
`skew` | `0` | Correspond à l’attribut `width`
`bands` | `[]` | Voir ci-dessous
`nr_of_bands` | `0` | Voir ci-dessous
`datatype` | `6` | Voir ci-dessous
`papsz_options` | `{}` | Voir ci-dessous

name

  Chaîne représentant le nom de la géométrie matricielle. Lors de la création d’un objet basé sur un fichier, ce paramètre doit correspondre au chemin du fichier de la nouvelle géométrie matricielle. Si le nom commence par `/vsimem/`, la géométrie est créée dans le système de fichiers virtuel de GDAL.

datatype

  Nombre entier représentant le type de données de toutes les bandes. Vaut `6` (Float32) par défaut. Toutes les bandes de la nouvelle géométrie matricielle ont obligatoirement le même type de données. La correspondance des valeurs est :

  Valeur | Type de pixel GDAL | Description
  --- | --- | ---
  1 | GDT_Byte | Nombre entier non signé de 8 bits
  2 | GDT_UInt16 | Nombre entier non signé de 16 bits
  3 | GDT_Int16 | Nombre entier signé de 16 bits
  4 | GDT_UInt32 | Nombre entier non signé de 32 bits
  5 | GDT_Int32 | Nombre entier signé de 32 bits
  6 | GDT_Float32 | Nombre à virgule flottante de 32 bits
  7 | GDT_Float64 | Nombre à virgule flottante de 64 bits
  12 | GDT_UInt64 | Nombre entier non signé de 64 bits (GDAL 3.5+)
  13 | GDT_Int64 | Nombre entier signé de 64 bits (GDAL 3.5+)
  14 | GDT_Int8 | Nombre entier signé de 8 bits (GDAL 3.7+)

nr_of_bands

  Nombre entier représentant le nombre de bandes de la géométrie matricielle. Il n’est pas obligatoire de transmettre des données de bandes lors de la création. Si le nombre de bandes n’est pas indiqué, il est automatiquement déduit de la longueur de la valeur d’entrée `bands`. Ce nombre ne peut plus être modifié après la création.

bands

  Une liste de dictionnaires `band_input` contenant les données de bandes initiales. Les indices de bandes créés seront les mêmes que dans cette liste. La définition du dictionnaire de bande en valeur d’entrée est décrit ci-dessous. Si les données de bande ne sont pas fournies, les valeurs des bandes sont initialisées sous forme de tableau de zéros et la valeur `no data` est définie à `None`.

papsz_options

  Un dictionnaire avec des options de création de géométrie matricielle. Les paires clé-valeur du dictionnaire d’entrée sont transmises au pilote lors de la création de l’objet.

  Les options disponibles sont spécifiques au pilote et sont décrites dans la documentation de chaque pilote.

  Les valeurs dans le dictionnaire ne sont pas sensibles à la casse et sont automatiquement converties dans le bon format de chaîne lors de la création.

  L’exemple suivant utilise certaines des options disponibles pour le pilote GTiff. Le résultat est une géométrie matricielle compressée avec un système interne de tuiles. Les tuiles internes ont une taille de bloc de 23 par 23 :

      >>> GDALRaster(
      ...     {
      ...         "driver": "GTiff",
      ...         "name": "/path/to/new/file.tif",
      ...         "srid": 4326,
      ...         "width": 255,
      ...         "height": 255,
      ...         "nr_of_bands": 1,
      ...         "papsz_options": {
      ...             "compress": "packbits",
      ...             "tiled": "yes",
      ...             "blockxsize": 23,
      ...             "blockysize": 23,
      ...         },
      ...     }
      ... )

#### Le dictionnaire `band_input`

La clé `bands` dans le dictionnaire `ds_input` est une liste de dictionnaires `band_input`. Chacun de ces dictionnaires peut contenir des valeurs de pixels et la valeur `no data` à définir pour les bandes de la nouvelle géométrie matricielle. Le tableau des données peut avoir la pleine taille du nouvel objet ou être plus petit. Pour les tableaux plus petits que la taille de la nouvelle matrice, les clés `size`, `shape` et `offset` contrôlent les valeurs de pixels. Les clés correspondantes sont transmises à la méthode `data()`. Elles jouent le même rôle que lorsque vous définissez des données de bandes avec cette méthode. Le tableau suivant décrit les clés pouvant être utilisées.

Clé | Valeur par défaut | Utilisation
--- | --- | ---
`nodata_value` | `None` | Correspond à l’attribut `nodata_value`
`data` | Identique à `nodata_value` ou `0` | Transmis à la méthode `data()`
`size` | `(largeur, hauteur)` de la matrice | Transmis à la méthode `data()`
`shape` | Comme pour `size` | Transmis à la méthode `data()`
`offset` | `(0, 0)` | Transmis à la méthode `data()`

### Utilisation du système de fichiers virtuel de GDAL

GDAL peut accéder à des fichiers stockés sur le système de fichiers, mais prend aussi en charge les systèmes de fichiers virtuels pour abstraire l’accès à d’autres types de fichiers, tels que des fichiers compressés, chiffrés ou distants.

#### Utilisation du système de fichiers virtuel basé en mémoire

GDAL possède un système de fichiers interne basé sur la mémoire qui permet de traiter des blocs de mémoire comme des fichiers. Il peut être utilisé pour lire et écrire des objets `GDALRaster` vers et à partir de tampons de fichiers binaires.

Cela se révèle utile dans des contextes web où les objets matriciels peuvent être obtenus comme tampons depuis un stockage distant ou renvoyés à partir d’une vue sans être écrits sur disque.

Les objets `GDALRaster` sont créés dans le système de fichiers virtuel lorsqu’un objet de type `bytes` est fourni en entrée ou lorsque le chemin de fichier commence par `/vsimem/`.

L’entrée binaire sous forme de `bytes` doit être une représentation binaire complète d’un fichier. Par exemple :

    # Read a raster as a file object from a remote source.
    >>> from urllib.request import urlopen
    >>> dat = urlopen("https://example.com/raster.tif").read()
    # Instantiate a raster from the bytes object.
    >>> rst = GDALRaster(dat)
    # The name starts with /vsimem/, indicating that the raster lives in the
    # virtual filesystem.
    >>> rst.name
    '/vsimem/da300bdb-129d-49a8-b336-e410a9428dad'

Pour créer un nouvelle géométrie matricielle basée sur un fichier virtuel à partir de rien, utilisez le dictionnaire `ds_input` et fournissez un paramètre `name` commençant par `/vsimem/` (pour plus de détails sur la forme du dictionnaire, voir Création de géométries matricielles à partir de données). Pour les matrices basées sur des fichiers virtuels, l’attribut `vsi_buffer` renvoie la représentation binaire de la matrice.

Voici comment créer une géométrie matricielle et la renvoyer comme fichier dans une réponse `HttpResponse`:

    >>> from django.http import HttpResponse
    >>> rst = GDALRaster(
    ...     {
    ...         "name": "/vsimem/temporarymemfile",
    ...         "driver": "tif",
    ...         "width": 6,
    ...         "height": 6,
    ...         "srid": 3086,
    ...         "origin": [500000, 400000],
    ...         "scale": [100, -100],
    ...         "bands": [{"data": range(36), "nodata_value": 99}],
    ...     }
    ... )
    >>> HttpResponse(rast.vsi_buffer, "image/tiff")

#### Utilisation d’autres systèmes de fichiers virtuels

En fonction de la construction locale de GDAL, d’autres systèmes de fichiers virtuels peuvent être pris en charge. Vous pouvez les utiliser en complétant le chemin donné par le préfixe adéquat `/vsi*/`. Consultez la documentation des systèmes de fichiers virtuels GDAL pour plus de détails.

##### Matrices bitmap compressées

Au lieu de décompresser le fichier et d’instancier la matrice résultante, GDAL peut accéder directement à des fichiers compressés en utilisant les systèmes de fichiers virtuels `/vsizip/`, `/vsigzip/` ou `/vsitar/`:

    >>> from django.contrib.gis.gdal import GDALRaster
    >>> rst = GDALRaster("/vsizip/path/to/your/file.zip/path/to/raster.tif")
    >>> rst = GDALRaster("/vsigzip/path/to/your/file.gz")
    >>> rst = GDALRaster("/vsitar/path/to/your/file.tar/path/to/raster.tif")

##### Matrices bitmap réseau

Pour autant qu’il ait été construit avec les options adéquates, GDAL peut prendre en charge les ressources en ligne et les fournisseurs de stockage de manière transparente.

Pour accéder à un fichier matriciel public sans authentification, vous pouvez utiliser `/vsicurl/`:

    >>> from django.contrib.gis.gdal import GDALRaster
    >>> rst = GDALRaster("/vsicurl/https://example.com/raster.tif")
    >>> rst.name
    '/vsicurl/https://example.com/raster.tif'

Pour des fournisseurs de stockage commerciaux (par ex. `/vsis3/`), le système devrait être préalablement configuré pour l’authentification et peut-être pour d’autres réglages (voir la documentation des systèmes de fichiers virtuels GDAL pour les options disponibles).

## Réglages

### `GDAL_LIBRARY_PATH`

A string specifying the location of the GDAL library. Typically, this setting is only used if the GDAL library is in a non-standard location (e.g., `/home/john/lib/libgdal.so`).

## Exceptions

exception GDALException

  L’exception GDAL de base, indiquant une erreur liée à GDAL.

exception SRSException

  Une exception levée quand une erreur survient lors de la construction ou de l’usage d’un objet à système de référence spatiale.