Debian Codegraph @

docs/ref/contrib/gis/measure.txt

raw
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.