1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
|
.. _ref-measure:
===================
Measurement Objects
===================
.. module:: django.contrib.gis.measure
:synopsis: GeoDjango's distance and area measurment 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``)::
>>> from django.contrib.gis.measure import Distance, D
>>> d1 = Distance(km=5)
>>> print d1
5.0 km
>>> d2 = D(mi=5) # `D` is an alias for `Distance`
>>> print d2
5.0 mi
Conversions are easy, just access the preferred unit attribute to get a
converted distance quantity::
>>> 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::
>>> 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::
>>> 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::
>>> 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
``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.
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::
>>> dist = Distance(mi=5)
.. method:: __getattr__(unit_att)
Returns the distance value in units corresponding to the given unit
attribute. For example::
>>> print dist.km
8.04672
.. classmethod:: unit_attname(unit_name)
Returns the distance unit attribute name for the given full unit name.
For example::
>>> Distance.unit_attname('Mile')
'mi'
.. class:: D
Alias for :class:`Distance` class.
``Area``
--------
.. class:: Area(**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 square miles::
>>> a = Area(sq_mi=5)
.. method:: __getattr__(unit_att)
Returns the area value in units corresponding to the given unit
attribute. For example::
>>> 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::
>>> Area.unit_attname('Kilometer')
'sq_km'
.. class:: A
Alias for :class:`Area` class.
.. rubric:: Footnotes
.. [#] `Robert Coup <http://koordinates.com/>`_ is the initial author of the measure objects,
and was inspired by Brian Beck's work in `geopy <http://code.google.com/p/geopy/>`_
and Geoff Biggs' PhD work on dimensioned units for robotics.
|
