123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214 |
- ===================
- Measurement Objects
- ===================
- .. module:: django.contrib.gis.measure
- :synopsis: GeoDjango's distance and area measurement objects.
- The :mod:`django.contrib.gis.measure` module contains objects that allow
- for convenient representation of distance and area units of measure. [#]_
- Specifically, it implements two objects, :class:`Distance` and
- :class:`Area` -- both of which may be accessed via the
- :class:`D` and :class:`A` convenience aliases, respectively.
- Example
- =======
- :class:`Distance` objects may be instantiated using a keyword argument indicating the
- context of the units. In the example below, two different distance objects are
- instantiated in units of kilometers (``km``) and miles (``mi``):
- .. code-block:: pycon
- >>> 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
- For conversions, access the preferred unit attribute to get a converted
- distance quantity:
- .. code-block:: pycon
- >>> print(d1.mi) # Converting 5 kilometers to miles
- 3.10685596119
- >>> print(d2.km) # Converting 5 miles to kilometers
- 8.04672
- Moreover, arithmetic operations may be performed between the distance
- objects:
- .. code-block:: pycon
- >>> print(d1 + d2) # Adding 5 miles to 5 kilometers
- 13.04672 km
- >>> print(d2 - d1) # Subtracting 5 kilometers from 5 miles
- 1.89314403881 mi
- Two :class:`Distance` objects multiplied together will yield an :class:`Area`
- object, which uses squared units of measure:
- .. code-block:: pycon
- >>> a = d1 * d2 # Returns an Area object.
- >>> print(a)
- 40.2336 sq_km
- To determine what the attribute abbreviation of a unit is, the ``unit_attname``
- class method may be used:
- .. code-block:: pycon
- >>> print(Distance.unit_attname("US Survey Foot"))
- survey_ft
- >>> print(Distance.unit_attname("centimeter"))
- cm
- .. _supported_units:
- Supported units
- ===============
- ================================= ========================================
- Unit Attribute Full name or alias(es)
- ================================= ========================================
- ``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, Furrow Long
- ``nm`` Nautical Mile
- ``nm_uk`` Nautical Mile (UK)
- ``german_m`` German legal metre
- ================================= ========================================
- .. note::
- :class:`Area` attributes are the same as :class:`Distance` attributes,
- except they are prefixed with ``sq_`` (area units are square in nature).
- For example, ``Area(sq_m=2)`` creates an :class:`Area` object
- representing two square meters.
- In addition to unit with the ``sq_`` prefix, the following units are also
- supported on :class:`Area`:
- ================================= ========================================
- Unit Attribute Full name or alias(es)
- ================================= ========================================
- ``ha`` Hectare
- ================================= ========================================
- .. versionchanged:: 5.1
- Support for the ``ha`` unit was added.
- Measurement API
- ===============
- ``Distance``
- ------------
- .. class:: Distance(**kwargs)
- To initialize a distance object, pass in a keyword corresponding to the
- desired :ref:`unit attribute name <supported_units>` set with desired
- value. For example, the following creates a distance object representing 5
- miles:
- .. code-block:: pycon
- >>> dist = Distance(mi=5)
- .. method:: __getattr__(unit_att)
- Returns the distance value in units corresponding to the given unit
- attribute. For example:
- .. code-block:: pycon
- >>> print(dist.km)
- 8.04672
- .. classmethod:: unit_attname(unit_name)
- Returns the distance unit attribute name for the given full unit name. For
- example:
- .. code-block:: pycon
- >>> Distance.unit_attname("Mile")
- 'mi'
- .. class:: D
- Alias for :class:`Distance` class.
- ``Area``
- --------
- .. class:: Area(**kwargs)
- To initialize an area object, pass in a keyword corresponding to the
- desired :ref:`unit attribute name <supported_units>` set with desired
- value. For example, the following creates an area object representing 5
- square miles:
- .. code-block:: pycon
- >>> a = Area(sq_mi=5)
- .. method:: __getattr__(unit_att)
- Returns the area value in units corresponding to the given unit attribute.
- For example:
- .. code-block:: pycon
- >>> print(a.sq_km)
- 12.949940551680001
- .. classmethod:: unit_attname(unit_name)
- Returns the area unit attribute name for the given full unit name. For
- example:
- .. code-block:: pycon
- >>> Area.unit_attname("Kilometer")
- 'sq_km'
- .. class:: A
- Alias for :class:`Area` class.
- .. rubric:: Footnotes
- .. [#] `Robert Coup <https://koordinates.com/>`_ is the initial author of the measure objects,
- and was inspired by Brian Beck's work in `geopy <https://github.com/geopy/geopy/>`_
- and Geoff Biggs' PhD work on dimensioned units for robotics.
|