| 1 |
=================== |
| 2 |
Measurement Objects |
| 3 |
=================== |
| 4 |
|
| 5 |
.. module:: django.contrib.gis.measure |
| 6 |
:synopsis: GeoDjango's distance and area measurement objects. |
| 7 |
|
| 8 |
The :mod:`django.contrib.gis.measure` module contains objects that allow |
| 9 |
for convenient representation of distance and area units of measure. [#]_ |
| 10 |
Specifically, it implements two objects, :class:`Distance` and |
| 11 |
:class:`Area` -- both of which may be accessed via the |
| 12 |
:class:`D` and :class:`A` convenience aliases, respectively. |
| 13 |
|
| 14 |
Example |
| 15 |
======= |
| 16 |
|
| 17 |
:class:`Distance` objects may be instantiated using a keyword argument indicating the |
| 18 |
context of the units. In the example below, two different distance objects are |
| 19 |
instantiated in units of kilometers (``km``) and miles (``mi``): |
| 20 |
|
| 21 |
.. code-block:: pycon |
| 22 |
|
| 23 |
>>> from django.contrib.gis.measure import D, Distance |
| 24 |
>>> d1 = Distance(km=5) |
| 25 |
>>> print(d1) |
| 26 |
5.0 km |
| 27 |
>>> d2 = D(mi=5) # `D` is an alias for `Distance` |
| 28 |
>>> print(d2) |
| 29 |
5.0 mi |
| 30 |
|
| 31 |
For conversions, access the preferred unit attribute to get a converted |
| 32 |
distance quantity: |
| 33 |
|
| 34 |
.. code-block:: pycon |
| 35 |
|
| 36 |
>>> print(d1.mi) # Converting 5 kilometers to miles |
| 37 |
3.10685596119 |
| 38 |
>>> print(d2.km) # Converting 5 miles to kilometers |
| 39 |
8.04672 |
| 40 |
|
| 41 |
Moreover, arithmetic operations may be performed between the distance |
| 42 |
objects: |
| 43 |
|
| 44 |
.. code-block:: pycon |
| 45 |
|
| 46 |
>>> print(d1 + d2) # Adding 5 miles to 5 kilometers |
| 47 |
13.04672 km |
| 48 |
>>> print(d2 - d1) # Subtracting 5 kilometers from 5 miles |
| 49 |
1.89314403881 mi |
| 50 |
|
| 51 |
Two :class:`Distance` objects multiplied together will yield an :class:`Area` |
| 52 |
object, which uses squared units of measure: |
| 53 |
|
| 54 |
.. code-block:: pycon |
| 55 |
|
| 56 |
>>> a = d1 * d2 # Returns an Area object. |
| 57 |
>>> print(a) |
| 58 |
40.2336 sq_km |
| 59 |
|
| 60 |
To determine what the attribute abbreviation of a unit is, the ``unit_attname`` |
| 61 |
class method may be used: |
| 62 |
|
| 63 |
.. code-block:: pycon |
| 64 |
|
| 65 |
>>> print(Distance.unit_attname("US Survey Foot")) |
| 66 |
survey_ft |
| 67 |
>>> print(Distance.unit_attname("centimeter")) |
| 68 |
cm |
| 69 |
|
| 70 |
.. _supported_units: |
| 71 |
|
| 72 |
Supported units |
| 73 |
=============== |
| 74 |
|
| 75 |
================================= ======================================== |
| 76 |
Unit Attribute Full name or alias(es) |
| 77 |
================================= ======================================== |
| 78 |
``km`` Kilometre, Kilometer |
| 79 |
``mi`` Mile |
| 80 |
``m`` Meter, Metre |
| 81 |
``yd`` Yard |
| 82 |
``ft`` Foot, Foot (International) |
| 83 |
``survey_ft`` U.S. Foot, US survey foot |
| 84 |
``inch`` Inches |
| 85 |
``cm`` Centimeter |
| 86 |
``mm`` Millimetre, Millimeter |
| 87 |
``um`` Micrometer, Micrometre |
| 88 |
``british_ft`` British foot (Sears 1922) |
| 89 |
``british_yd`` British yard (Sears 1922) |
| 90 |
``british_chain_sears`` British chain (Sears 1922) |
| 91 |
``indian_yd`` Indian yard, Yard (Indian) |
| 92 |
``sears_yd`` Yard (Sears) |
| 93 |
``clarke_ft`` Clarke's Foot |
| 94 |
``chain`` Chain |
| 95 |
``chain_benoit`` Chain (Benoit) |
| 96 |
``chain_sears`` Chain (Sears) |
| 97 |
``british_chain_benoit`` British chain (Benoit 1895 B) |
| 98 |
``british_chain_sears_truncated`` British chain (Sears 1922 truncated) |
| 99 |
``gold_coast_ft`` Gold Coast foot |
| 100 |
``link`` Link |
| 101 |
``link_benoit`` Link (Benoit) |
| 102 |
``link_sears`` Link (Sears) |
| 103 |
``clarke_link`` Clarke's link |
| 104 |
``fathom`` Fathom |
| 105 |
``rod`` Rod |
| 106 |
``furlong`` Furlong, Furrow Long |
| 107 |
``nm`` Nautical Mile |
| 108 |
``nm_uk`` Nautical Mile (UK) |
| 109 |
``german_m`` German legal metre |
| 110 |
================================= ======================================== |
| 111 |
|
| 112 |
.. note:: |
| 113 |
|
| 114 |
:class:`Area` attributes are the same as :class:`Distance` attributes, |
| 115 |
except they are prefixed with ``sq_`` (area units are square in nature). |
| 116 |
For example, ``Area(sq_m=2)`` creates an :class:`Area` object |
| 117 |
representing two square meters. |
| 118 |
|
| 119 |
In addition to unit with the ``sq_`` prefix, the following units are also |
| 120 |
supported on :class:`Area`: |
| 121 |
|
| 122 |
================================= ======================================== |
| 123 |
Unit Attribute Full name or alias(es) |
| 124 |
================================= ======================================== |
| 125 |
``ha`` Hectare |
| 126 |
================================= ======================================== |
| 127 |
|
| 128 |
.. versionchanged:: 5.1 |
| 129 |
|
| 130 |
Support for the ``ha`` unit was added. |
| 131 |
|
| 132 |
Measurement API |
| 133 |
=============== |
| 134 |
|
| 135 |
``Distance`` |
| 136 |
------------ |
| 137 |
|
| 138 |
.. class:: Distance(**kwargs) |
| 139 |
|
| 140 |
To initialize a distance object, pass in a keyword corresponding to the |
| 141 |
desired :ref:`unit attribute name <supported_units>` set with desired |
| 142 |
value. For example, the following creates a distance object representing 5 |
| 143 |
miles: |
| 144 |
|
| 145 |
.. code-block:: pycon |
| 146 |
|
| 147 |
>>> dist = Distance(mi=5) |
| 148 |
|
| 149 |
.. method:: __getattr__(unit_att) |
| 150 |
|
| 151 |
Returns the distance value in units corresponding to the given unit |
| 152 |
attribute. For example: |
| 153 |
|
| 154 |
.. code-block:: pycon |
| 155 |
|
| 156 |
>>> print(dist.km) |
| 157 |
8.04672 |
| 158 |
|
| 159 |
.. classmethod:: unit_attname(unit_name) |
| 160 |
|
| 161 |
Returns the distance unit attribute name for the given full unit name. For |
| 162 |
example: |
| 163 |
|
| 164 |
.. code-block:: pycon |
| 165 |
|
| 166 |
>>> Distance.unit_attname("Mile") |
| 167 |
'mi' |
| 168 |
|
| 169 |
.. class:: D |
| 170 |
|
| 171 |
Alias for :class:`Distance` class. |
| 172 |
|
| 173 |
``Area`` |
| 174 |
-------- |
| 175 |
|
| 176 |
.. class:: Area(**kwargs) |
| 177 |
|
| 178 |
To initialize an area object, pass in a keyword corresponding to the |
| 179 |
desired :ref:`unit attribute name <supported_units>` set with desired |
| 180 |
value. For example, the following creates an area object representing 5 |
| 181 |
square miles: |
| 182 |
|
| 183 |
.. code-block:: pycon |
| 184 |
|
| 185 |
>>> a = Area(sq_mi=5) |
| 186 |
|
| 187 |
.. method:: __getattr__(unit_att) |
| 188 |
|
| 189 |
Returns the area value in units corresponding to the given unit attribute. |
| 190 |
For example: |
| 191 |
|
| 192 |
.. code-block:: pycon |
| 193 |
|
| 194 |
>>> print(a.sq_km) |
| 195 |
12.949940551680001 |
| 196 |
|
| 197 |
.. classmethod:: unit_attname(unit_name) |
| 198 |
|
| 199 |
Returns the area unit attribute name for the given full unit name. For |
| 200 |
example: |
| 201 |
|
| 202 |
.. code-block:: pycon |
| 203 |
|
| 204 |
>>> Area.unit_attname("Kilometer") |
| 205 |
'sq_km' |
| 206 |
|
| 207 |
.. class:: A |
| 208 |
|
| 209 |
Alias for :class:`Area` class. |
| 210 |
|
| 211 |
.. rubric:: Footnotes |
| 212 |
.. [#] `Robert Coup <https://koordinates.com/>`_ is the initial author of the measure objects, |
| 213 |
and was inspired by Brian Beck's work in `geopy <https://github.com/geopy/geopy/>`_ |
| 214 |
and Geoff Biggs' PhD work on dimensioned units for robotics. |