PageRenderTime 444ms CodeModel.GetById 261ms app.highlight 2ms RepoModel.GetById 180ms app.codeStats 0ms

/docs/ref/contrib/gis/measure.txt

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