# Documentation Django 3.1.9.dev

# Objets de mesure

Le module `django.contrib.gis.measure` contient des objets qui permettent une représentation pratique des unités de mesure de distance et d’aire. [1] Spécifiquement, il implémente deux objets, `Distance` et `Area` qui sont aussi accessibles par les alias simplifiés `D` et `A`, respectivement.

## Exemple

Les objets `Distance` peuvent être créés en utilisant un paramètre nommé indiquant le contexte des unités. Dans l’exemple ci-dessous, deux objets distances différents sont créés dans les unités kilomètre (`km`) et miles (`mi`) :

    >>> from django.contrib.gis.measure import D, Distance
    >>> d1 = Distance(km=5)
    >>> print(d1)
    5.0 km
    >>> d2 = D(mi=5) # `D` is an alias for `Distance`
    >>> print(d2)
    5.0 mi

Pour les conversions, accédez à l’attribut correspondant à l’unité souhaitée pour obtenir la mesure convertie de la distance :

    >>> print(d1.mi) # Converting 5 kilometers to miles
    3.10685596119
    >>> print(d2.km) # Converting 5 miles to kilometers
    8.04672

De plus, des opérations arithmétiques peuvent être effectuées entre des objets de distance :

    >>> print(d1 + d2) # Adding 5 miles to 5 kilometers
    13.04672 km
    >>> print(d2 - d1) # Subtracting 5 kilometers from 5 miles
    1.89314403881 mi

Deux objets `Distance` multipliés ensemble génèrent un objet `Area` qui utilise une unité de mesure au carré :

    >>> a = d1 * d2 # Returns an Area object.
    >>> print(a)
    40.2336 sq_km

Pour savoir quel est l’attribut abrégé de l’unité, il est possible d’utiliser la méthode de classe `unit_attname`:

    >>> print(Distance.unit_attname('US Survey Foot'))
    survey_ft
    >>> print(Distance.unit_attname('centimeter'))
    cm

## Unités prises en charge

Attribut d’unité | Nom complet ou alias
--- | ---
`km` | Kilometre, Kilometer
`mi` | Mile
`m` | Meter, Metre
`yd` | Yard
`ft` | Foot, Foot (International)
`survey_ft` | U.S. Foot, US survey foot
`inch` | Inches
`cm` | Centimeter
`mm` | Millimetre, Millimeter
`um` | Micrometer, Micrometre
`british_ft` | British foot (Sears 1922)
`british_yd` | British yard (Sears 1922)
`british_chain_sears` | British chain (Sears 1922)
`indian_yd` | Indian yard, Yard (Indian)
`sears_yd` | Yard (Sears)
`clarke_ft` | Clarke’s Foot
`chain` | Chain
`chain_benoit` | Chain (Benoit)
`chain_sears` | Chain (Sears)
`british_chain_benoit` | British chain (Benoit 1895 B)
`british_chain_sears_truncated` | British chain (Sears 1922 truncated)
`gold_coast_ft` | Gold Coast foot
`link` | Link
`link_benoit` | Link (Benoit)
`link_sears` | Link (Sears)
`clarke_link` | Clarke’s link
`fathom` | Fathom
`rod` | Rod
`furlong` | Furlong (sillon), Furrow Long
`nm` | Nautical Mile
`nm_uk` | Nautical Mile (UK)
`german_m` | German legal metre

Note

Les attributs `Area` sont les mêmes que les attributs `Distance`, sauf qu’ils sont préfixés par `sq_` (square = au carré). Par exemple, `Area(sq_m=2)` crée un objet `Area` représentant deux mètres carrés.

## API de mesures

### `Distance`

class `Distance`(**kwargs)

  Pour initialiser un objet distance, passez-lui un paramètre nommé correspondant au nom d’attribut de l’unité souhaitée et contenant la valeur souhaitée. L’exemple suivant crée un objet distance représentant 5 miles :

      >>> dist = Distance(mi=5)

  `__getattr__`(unit_att)

  Renvoie la mesure de distance en unité correspondante à l’attribut d’unité indiqué. Par exemple :

      >>> print(dist.km)
      8.04672

  classmethod `unit_attname`(unit_name)

  Renvoie le nom d’attribut d’unité de distance correspondant au nom complet d’unité indiqué. Par exemple :

      >>> Distance.unit_attname('Mile')
      'mi'

class `D`

  Alias de la classe `Distance`.

### `Area`

class `Area`(**kwargs)

  Pour initialiser un objet aire, passez-lui un paramètre nommé correspondant au nom d’attribut de l’unité souhaitée et contenant la valeur souhaitée. L’exemple suivant crée un objet aire représentant 5 miles carrés

      >>> a = Area(sq_mi=5)

  `__getattr__`(unit_att)

  Renvoie la mesure d’aire en unité correspondante à l’attribut d’unité indiqué. Par exemple :

      >>> print(a.sq_km)
      12.949940551680001

  classmethod `unit_attname`(unit_name)

  Renvoie le nom d’attribut d’unité d’aire correspondant au nom complet d’unité indiqué. Par exemple :

      >>> Area.unit_attname('Kilometer')
      'sq_km'

class `A`

  Alias de la classe `Area`.

Notes de bas de page

[1] | Robert Coup est l’auteur initial des objets de mesure et a été inspiré par le travail de Brian Beck dans geopy et par celui de Geoff Biggs dans son doctorat sur les unités dimensionnées pour la robotique.