mirror of
https://github.com/django/django.git
synced 2025-09-18 06:59:12 +00:00
f81e6e3a53
Lines in the docs files were manually adjusted to conform to the 79 columns limit per line (plus newline), improving readability and consistency across the content.
213 lines
6.5 KiB
Plaintext
213 lines
6.5 KiB
Plaintext
===================
|
|
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
|
|
================================= ========================================
|
|
|
|
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.
|