diff options
Diffstat (limited to 'parts/django/docs/ref/contrib/gis/measure.txt')
| -rw-r--r-- | parts/django/docs/ref/contrib/gis/measure.txt | 180 |
1 files changed, 0 insertions, 180 deletions
diff --git a/parts/django/docs/ref/contrib/gis/measure.txt b/parts/django/docs/ref/contrib/gis/measure.txt deleted file mode 100644 index 6971788..0000000 --- a/parts/django/docs/ref/contrib/gis/measure.txt +++ /dev/null @@ -1,180 +0,0 @@ -.. _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. |