measure.txt 6.6 KB

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