# Documentation Django 5.2.8

# Utilitaire d’importation de données `LayerMapping`

La classe `LayerMapping` fournit une manière de faire correspondre du contenu provenant de fichiers de données spatiales (par ex. des fichiers shape) avec des modèles GeoDjango.

Cet utilitaire a été fabriqué à partir des besoins personnels de son auteur qui a ressenti le besoin d’éliminer de la répétition de code provenant de l’extraction d’objets géométriques et de champs de données à partir d’une couche vectorielle, de les convertir dans un autre système de coordonnées (par ex. WGS84) et de les insérer dans un modèle GeoDjango.

Note

L’utilisation de `LayerMapping` nécessite GDAL.

Avertissement

GIS data sources, like shapefiles, may be very large. If you find that `LayerMapping` is using too much memory, set `DEBUG` to `False` in your settings. When `DEBUG` is set to `True`, Django automatically logs every SQL query – and when SQL statements contain geometries, this may consume more memory than is typical.

## Exemple

1. Vous avez besoin d’une source de données prise en charge par GDAL, comme un fichier shape (nous utiliserons ici un fichier shape simple formé de trois polygones) :

    >>> from django.contrib.gis.gdal import DataSource
    >>> ds = DataSource("test_poly.shp")
    >>> layer = ds[0]
    >>> print(layer.fields)  # Exploring the fields in the layer, we only want the 'str' field.
    ['float', 'int', 'str']
    >>> print(len(layer))  # getting the number of features in the layer (should be 3)
    3
    >>> print(layer.geom_type)  # Should be 'Polygon'
    Polygon
    >>> print(layer.srs)  # WGS84 in WKT
    GEOGCS["GCS_WGS_1984",
        DATUM["WGS_1984",
            SPHEROID["WGS_1984",6378137,298.257223563]],
        PRIMEM["Greenwich",0],
        UNIT["Degree",0.017453292519943295]]

1. Nous définissons ensuite le modèle Django correspondant (assurez-vous d’utiliser `migrate`) :

       from django.contrib.gis.db import models

       class TestGeo(models.Model):
           name = models.CharField(max_length=25)  # corresponds to the 'str' field
           poly = models.PolygonField(srid=4269)  # we want our model in a different SRID

           def __str__(self):
               return "Name: %s" % self.name

2. Utilisez `LayerMapping` pour extraire tous les éléments et les placer dans la base de données :

    >>> from django.contrib.gis.utils import LayerMapping
    >>> from geoapp.models import TestGeo
    >>> mapping = {
    ...     "name": "str",  # The 'name' model field maps to the 'str' layer field.
    ...     "poly": "POLYGON",  # For geometry fields use OGC name.
    ... }  # The mapping is a dictionary
    >>> lm = LayerMapping(TestGeo, "test_poly.shp", mapping)
    >>> lm.save(verbose=True)  # Save the layermap, imports the data.
    Saved: Name: 1
    Saved: Name: 2
    Saved: Name: 3

Here, `LayerMapping` transformed the three geometries from the shapefile in their original spatial reference system (WGS84) to the spatial reference system of the GeoDjango model (NAD83). If no spatial reference system is defined for the layer, use the `source_srs` keyword with a `SpatialReference` object to specify one.

## API de `LayerMapping`

class LayerMapping(model, data_source, mapping, layer=0, source_srs=None, encoding=None, transaction_mode='commit_on_success', transform=True, unique=True, using='default')

Voici les paramètres positionnels et nommés pouvant être utilisés durant la création d’instances d’objets `LayerMapping`.

Paramètre | Description
--- | ---
`model` | Le modèle géographique, pas une instance.
`data_source` | The path to the OGR-supported data source file (e.g., a shapefile). Also accepts `django.contrib.gis.gdal.DataSource` instances.
`mapping` | Un dictionnaire : les clés sont des chaînes correspondant aux champs de modèle et les valeurs correspondent aux noms de champs des éléments OGR ou, dans le cas où le champ de modèle est géographique, au type géométrique OGR, par ex. `'POINT'`, `'LINESTRING'`, `'POLYGON'`.

Paramètres nommés |
--- | ---
`layer` | L’indice de la couche à utiliser dans la source de données (0 par défaut).
`source_srs` | Use this to specify the source SRS manually (for example, some shapefiles don’t come with a `'.prj'` file). An integer SRID, WKT or PROJ strings, and `django.contrib.gis.gdal.SpatialReference` objects are accepted.
`encoding` | Specifies the character set encoding of the strings in the OGR data source. For example, `'latin-1'`, `'utf-8'`, and `'cp437'` are all valid encoding parameters.
`transaction_mode` | Peut être `'commit_on_success'` (par défaut) ou `'autocommit'`.
`transform` | Setting this to False will disable coordinate transformations. In other words, geometries will be inserted into the database unmodified from their original state in the data source.
`unique` | Setting this to the name, or a tuple of names, from the given model will create models unique only to the given name(s). Geometries from each feature will be added into the collection associated with the unique model. Forces the transaction mode to be `'autocommit'`.
`using` | Définit la base de données à utiliser lors de l’importation de données spatiales. La valeur par défaut est `'default'`.

### Paramètres nommés de `save()`

LayerMapping.save(verbose=False, fid_range=False, step=False, progress=False, silent=False, stream=sys.stdout, strict=False)

The `save()` method also accepts keywords. These keywords are used for controlling output logging, error handling, and for importing specific feature ranges.

Paramètre nommé de `save` | Description
--- | ---
`fid_range` | May be set with a slice or tuple of (begin, end) feature ID’s to map from the data source. In other words, this keyword enables the user to selectively import a subset range of features in the geographic data source.
`progress` | When this keyword is set, status information will be printed giving the number of features processed and successfully saved. By default, progress information will be printed every 1000 features processed, however, this default may be overridden by setting this keyword with an integer for the desired interval.
`silent` | Par défaut, les notifications d’erreurs non fatales sont affichées sur `sys.stdout`, mais ce paramètre booléen peut être défini pour désactiver ces notifications.
`step` | Lorsqu’il contient un nombre entier, définit l’intervalle d’enregistrement par transaction. Par exemple, si `step=1000`, une transaction est validée (commit) après le 1000e élément, après le 2000e élément, etc.
`stream` | Status information will be written to this file handle. Defaults to using `sys.stdout`, but any object with a `write` method is supported.
`strict` | Execution of the model mapping will cease upon the first error encountered. The default value (`False`) behavior is to attempt to continue.
`verbose` | Si défini à `True`, des informations s’affichent après chaque enregistrement de modèle dans la base de données.

## Dépannage

### Consommation excessive de mémoire

As noted in the warning at the top of this section, Django stores all SQL queries when `DEBUG=True`. Set `DEBUG=False` in your settings, and this should stop excessive memory use when running `LayerMapping` scripts.

### MySQL : erreur `max_allowed_packet`

Si vous rencontrez l’erreur suivante lorsque vous utilisez la fonctionnalité `LayerMapping` avec MySQL :

    OperationalError: (1153, "Got a packet bigger than 'max_allowed_packet' bytes")

Then the solution is to increase the value of the `max_allowed_packet` setting in your MySQL configuration. For example, the default value may be something low like one megabyte – the setting may be modified in MySQL’s configuration file (`my.cnf`) in the `[mysqld]` section:

    max_allowed_packet = 10M