python/lib/django_1_4/docs/ref/contrib/gis/measure.txt

   1 .. _ref-measure:
   2
   3 ===================
   4 Measurement Objects
   5 ===================
   6
   7 .. module:: django.contrib.gis.measure
   8    :synopsis: GeoDjango's distance and area measurment objects.
   9
  10 The :mod:`django.contrib.gis.measure` module contains objects that allow
  11 for convenient representation of distance and area units of measure. [#]_
  12 Specifically, 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
  16 Example
  17 =======
  18
  19 :class:`Distance` objects may be instantiated using a keyword argument indicating the
  20 context of the units.  In the example below, two different distance objects are
  21 instantiated 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
  31 Conversions are easy, just access the preferred unit attribute to get a
  32 converted 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
  39 Moreover, arithmetic operations may be performed between the distance
  40 objects::
  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
  47 Two :class:`Distance` objects multiplied together will yield an :class:`Area`
  48 object, which uses squared units of measure::
  49
  50     >>> a = d1 * d2 # Returns an Area object.
  51     >>> print a
  52     40.2336 sq_km
  53
  54 To determine what the attribute abbreviation of a unit is, the ``unit_attname``
  55 class 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
  64 Supported units
  65 ===============
  66
  67 =================================  ========================================
  68 Unit 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
 110 Measurement 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.