<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <title>Measurement Objects — Django 1.5.8 documentation</title> <link rel="stylesheet" href="../../../_static/default.css" type="text/css" /> <link rel="stylesheet" href="../../../_static/pygments.css" type="text/css" /> <script type="text/javascript"> var DOCUMENTATION_OPTIONS = { URL_ROOT: '../../../', VERSION: '1.5.8', COLLAPSE_INDEX: false, FILE_SUFFIX: '.html', HAS_SOURCE: true }; </script> <script type="text/javascript" src="../../../_static/jquery.js"></script> <script type="text/javascript" src="../../../_static/underscore.js"></script> <script type="text/javascript" src="../../../_static/doctools.js"></script> <link rel="top" title="Django 1.5.8 documentation" href="../../../index.html" /> <link rel="up" title="GeoDjango" href="index.html" /> <link rel="next" title="GEOS API" href="geos.html" /> <link rel="prev" title="GeoQuerySet API Reference" href="geoquerysets.html" /> <script type="text/javascript" src="../../../templatebuiltins.js"></script> <script type="text/javascript"> (function($) { if (!django_template_builtins) { // templatebuiltins.js missing, do nothing. return; } $(document).ready(function() { // Hyperlink Django template tags and filters var base = "../../templates/builtins.html"; if (base == "#") { // Special case for builtins.html itself base = ""; } // Tags are keywords, class '.k' $("div.highlight\\-html\\+django span.k").each(function(i, elem) { var tagname = $(elem).text(); if ($.inArray(tagname, django_template_builtins.ttags) != -1) { var fragment = tagname.replace(/_/, '-'); $(elem).html("<a href='" + base + "#" + fragment + "'>" + tagname + "</a>"); } }); // Filters are functions, class '.nf' $("div.highlight\\-html\\+django span.nf").each(function(i, elem) { var filtername = $(elem).text(); if ($.inArray(filtername, django_template_builtins.tfilters) != -1) { var fragment = filtername.replace(/_/, '-'); $(elem).html("<a href='" + base + "#" + fragment + "'>" + filtername + "</a>"); } }); }); })(jQuery); </script> </head> <body> <div class="document"> <div id="custom-doc" class="yui-t6"> <div id="hd"> <h1><a href="../../../index.html">Django 1.5.8 documentation</a></h1> <div id="global-nav"> <a title="Home page" href="../../../index.html">Home</a> | <a title="Table of contents" href="../../../contents.html">Table of contents</a> | <a title="Global index" href="../../../genindex.html">Index</a> | <a title="Module index" href="../../../py-modindex.html">Modules</a> </div> <div class="nav"> « <a href="geoquerysets.html" title="GeoQuerySet API Reference">previous</a> | <a href="../../index.html" title="API Reference" accesskey="U">up</a> | <a href="geos.html" title="GEOS API">next</a> »</div> </div> <div id="bd"> <div id="yui-main"> <div class="yui-b"> <div class="yui-g" id="ref-contrib-gis-measure"> <div class="section" id="s-module-django.contrib.gis.measure"> <span id="s-measurement-objects"></span><span id="s-ref-measure"></span><span id="module-django.contrib.gis.measure"></span><span id="measurement-objects"></span><span id="ref-measure"></span><h1>Measurement Objects<a class="headerlink" href="#module-django.contrib.gis.measure" title="Permalink to this headline">¶</a></h1> <p>The <a class="reference internal" href="#module-django.contrib.gis.measure" title="django.contrib.gis.measure: GeoDjango's distance and area measurment objects."><tt class="xref py py-mod docutils literal"><span class="pre">django.contrib.gis.measure</span></tt></a> module contains objects that allow for convenient representation of distance and area units of measure. <a class="footnote-reference" href="#id3" id="id1">[1]</a> Specifically, it implements two objects, <a class="reference internal" href="#django.contrib.gis.measure.Distance" title="django.contrib.gis.measure.Distance"><tt class="xref py py-class docutils literal"><span class="pre">Distance</span></tt></a> and <a class="reference internal" href="#django.contrib.gis.measure.Area" title="django.contrib.gis.measure.Area"><tt class="xref py py-class docutils literal"><span class="pre">Area</span></tt></a> – both of which may be accessed via the <a class="reference internal" href="#django.contrib.gis.measure.D" title="django.contrib.gis.measure.D"><tt class="xref py py-class docutils literal"><span class="pre">D</span></tt></a> and <a class="reference internal" href="#django.contrib.gis.measure.A" title="django.contrib.gis.measure.A"><tt class="xref py py-class docutils literal"><span class="pre">A</span></tt></a> convenience aliases, respectively.</p> <div class="section" id="s-example"> <span id="example"></span><h2>Example<a class="headerlink" href="#example" title="Permalink to this headline">¶</a></h2> <p><a class="reference internal" href="#django.contrib.gis.measure.Distance" title="django.contrib.gis.measure.Distance"><tt class="xref py py-class docutils literal"><span class="pre">Distance</span></tt></a> 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 (<tt class="docutils literal"><span class="pre">km</span></tt>) and miles (<tt class="docutils literal"><span class="pre">mi</span></tt>):</p> <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">django.contrib.gis.measure</span> <span class="kn">import</span> <span class="n">Distance</span><span class="p">,</span> <span class="n">D</span> <span class="gp">>>> </span><span class="n">d1</span> <span class="o">=</span> <span class="n">Distance</span><span class="p">(</span><span class="n">km</span><span class="o">=</span><span class="mi">5</span><span class="p">)</span> <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">d1</span><span class="p">)</span> <span class="go">5.0 km</span> <span class="gp">>>> </span><span class="n">d2</span> <span class="o">=</span> <span class="n">D</span><span class="p">(</span><span class="n">mi</span><span class="o">=</span><span class="mi">5</span><span class="p">)</span> <span class="c"># `D` is an alias for `Distance`</span> <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">d2</span><span class="p">)</span> <span class="go">5.0 mi</span> </pre></div> </div> <p>Conversions are easy, just access the preferred unit attribute to get a converted distance quantity:</p> <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">d1</span><span class="o">.</span><span class="n">mi</span><span class="p">)</span> <span class="c"># Converting 5 kilometers to miles</span> <span class="go">3.10685596119</span> <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">d2</span><span class="o">.</span><span class="n">km</span><span class="p">)</span> <span class="c"># Converting 5 miles to kilometers</span> <span class="go">8.04672</span> </pre></div> </div> <p>Moreover, arithmetic operations may be performed between the distance objects:</p> <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">d1</span> <span class="o">+</span> <span class="n">d2</span><span class="p">)</span> <span class="c"># Adding 5 miles to 5 kilometers</span> <span class="go">13.04672 km</span> <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">d2</span> <span class="o">-</span> <span class="n">d1</span><span class="p">)</span> <span class="c"># Subtracting 5 kilometers from 5 miles</span> <span class="go">1.89314403881 mi</span> </pre></div> </div> <p>Two <a class="reference internal" href="#django.contrib.gis.measure.Distance" title="django.contrib.gis.measure.Distance"><tt class="xref py py-class docutils literal"><span class="pre">Distance</span></tt></a> objects multiplied together will yield an <a class="reference internal" href="#django.contrib.gis.measure.Area" title="django.contrib.gis.measure.Area"><tt class="xref py py-class docutils literal"><span class="pre">Area</span></tt></a> object, which uses squared units of measure:</p> <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">a</span> <span class="o">=</span> <span class="n">d1</span> <span class="o">*</span> <span class="n">d2</span> <span class="c"># Returns an Area object.</span> <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">a</span><span class="p">)</span> <span class="go">40.2336 sq_km</span> </pre></div> </div> <p>To determine what the attribute abbreviation of a unit is, the <tt class="docutils literal"><span class="pre">unit_attname</span></tt> class method may be used:</p> <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">Distance</span><span class="o">.</span><span class="n">unit_attname</span><span class="p">(</span><span class="s">'US Survey Foot'</span><span class="p">))</span> <span class="go">survey_ft</span> <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">Distance</span><span class="o">.</span><span class="n">unit_attname</span><span class="p">(</span><span class="s">'centimeter'</span><span class="p">))</span> <span class="go">cm</span> </pre></div> </div> </div> <div class="section" id="s-supported-units"> <span id="s-id2"></span><span id="supported-units"></span><span id="id2"></span><h2>Supported units<a class="headerlink" href="#supported-units" title="Permalink to this headline">¶</a></h2> <table class="docutils"> <colgroup> <col width="45%" /> <col width="55%" /> </colgroup> <thead valign="bottom"> <tr class="row-odd"><th class="head">Unit Attribute</th> <th class="head">Full name or alias(es)</th> </tr> </thead> <tbody valign="top"> <tr class="row-even"><td><tt class="docutils literal"><span class="pre">km</span></tt></td> <td>Kilometre, Kilometer</td> </tr> <tr class="row-odd"><td><tt class="docutils literal"><span class="pre">mi</span></tt></td> <td>Mile</td> </tr> <tr class="row-even"><td><tt class="docutils literal"><span class="pre">m</span></tt></td> <td>Meter, Metre</td> </tr> <tr class="row-odd"><td><tt class="docutils literal"><span class="pre">yd</span></tt></td> <td>Yard</td> </tr> <tr class="row-even"><td><tt class="docutils literal"><span class="pre">ft</span></tt></td> <td>Foot, Foot (International)</td> </tr> <tr class="row-odd"><td><tt class="docutils literal"><span class="pre">survey_ft</span></tt></td> <td>U.S. Foot, US survey foot</td> </tr> <tr class="row-even"><td><tt class="docutils literal"><span class="pre">inch</span></tt></td> <td>Inches</td> </tr> <tr class="row-odd"><td><tt class="docutils literal"><span class="pre">cm</span></tt></td> <td>Centimeter</td> </tr> <tr class="row-even"><td><tt class="docutils literal"><span class="pre">mm</span></tt></td> <td>Millimetre, Millimeter</td> </tr> <tr class="row-odd"><td><tt class="docutils literal"><span class="pre">um</span></tt></td> <td>Micrometer, Micrometre</td> </tr> <tr class="row-even"><td><tt class="docutils literal"><span class="pre">british_ft</span></tt></td> <td>British foot (Sears 1922)</td> </tr> <tr class="row-odd"><td><tt class="docutils literal"><span class="pre">british_yd</span></tt></td> <td>British yard (Sears 1922)</td> </tr> <tr class="row-even"><td><tt class="docutils literal"><span class="pre">british_chain_sears</span></tt></td> <td>British chain (Sears 1922)</td> </tr> <tr class="row-odd"><td><tt class="docutils literal"><span class="pre">indian_yd</span></tt></td> <td>Indian yard, Yard (Indian)</td> </tr> <tr class="row-even"><td><tt class="docutils literal"><span class="pre">sears_yd</span></tt></td> <td>Yard (Sears)</td> </tr> <tr class="row-odd"><td><tt class="docutils literal"><span class="pre">clarke_ft</span></tt></td> <td>Clarke’s Foot</td> </tr> <tr class="row-even"><td><tt class="docutils literal"><span class="pre">chain</span></tt></td> <td>Chain</td> </tr> <tr class="row-odd"><td><tt class="docutils literal"><span class="pre">chain_benoit</span></tt></td> <td>Chain (Benoit)</td> </tr> <tr class="row-even"><td><tt class="docutils literal"><span class="pre">chain_sears</span></tt></td> <td>Chain (Sears)</td> </tr> <tr class="row-odd"><td><tt class="docutils literal"><span class="pre">british_chain_benoit</span></tt></td> <td>British chain (Benoit 1895 B)</td> </tr> <tr class="row-even"><td><tt class="docutils literal"><span class="pre">british_chain_sears_truncated</span></tt></td> <td>British chain (Sears 1922 truncated)</td> </tr> <tr class="row-odd"><td><tt class="docutils literal"><span class="pre">gold_coast_ft</span></tt></td> <td>Gold Coast foot</td> </tr> <tr class="row-even"><td><tt class="docutils literal"><span class="pre">link</span></tt></td> <td>Link</td> </tr> <tr class="row-odd"><td><tt class="docutils literal"><span class="pre">link_benoit</span></tt></td> <td>Link (Benoit)</td> </tr> <tr class="row-even"><td><tt class="docutils literal"><span class="pre">link_sears</span></tt></td> <td>Link (Sears)</td> </tr> <tr class="row-odd"><td><tt class="docutils literal"><span class="pre">clarke_link</span></tt></td> <td>Clarke’s link</td> </tr> <tr class="row-even"><td><tt class="docutils literal"><span class="pre">fathom</span></tt></td> <td>Fathom</td> </tr> <tr class="row-odd"><td><tt class="docutils literal"><span class="pre">rod</span></tt></td> <td>Rod</td> </tr> <tr class="row-even"><td><tt class="docutils literal"><span class="pre">nm</span></tt></td> <td>Nautical Mile</td> </tr> <tr class="row-odd"><td><tt class="docutils literal"><span class="pre">nm_uk</span></tt></td> <td>Nautical Mile (UK)</td> </tr> <tr class="row-even"><td><tt class="docutils literal"><span class="pre">german_m</span></tt></td> <td>German legal metre</td> </tr> </tbody> </table> <div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last"><a class="reference internal" href="#django.contrib.gis.measure.Area" title="django.contrib.gis.measure.Area"><tt class="xref py py-class docutils literal"><span class="pre">Area</span></tt></a> attributes are the same as <a class="reference internal" href="#django.contrib.gis.measure.Distance" title="django.contrib.gis.measure.Distance"><tt class="xref py py-class docutils literal"><span class="pre">Distance</span></tt></a> attributes, except they are prefixed with <tt class="docutils literal"><span class="pre">sq_</span></tt> (area units are square in nature). For example, <tt class="docutils literal"><span class="pre">Area(sq_m=2)</span></tt> creates an <a class="reference internal" href="#django.contrib.gis.measure.Area" title="django.contrib.gis.measure.Area"><tt class="xref py py-class docutils literal"><span class="pre">Area</span></tt></a> object representing two square meters.</p> </div> </div> <div class="section" id="s-measurement-api"> <span id="measurement-api"></span><h2>Measurement API<a class="headerlink" href="#measurement-api" title="Permalink to this headline">¶</a></h2> <div class="section" id="s-distance"> <span id="distance"></span><h3><tt class="docutils literal"><span class="pre">Distance</span></tt><a class="headerlink" href="#distance" title="Permalink to this headline">¶</a></h3> <dl class="class"> <dt id="django.contrib.gis.measure.Distance"> <em class="property">class </em><tt class="descname">Distance</tt>(<em>**kwargs</em>)<a class="headerlink" href="#django.contrib.gis.measure.Distance" title="Permalink to this definition">¶</a></dt> <dd><p>To initialize a distance object, pass in a keyword corresponding to the desired <a class="reference internal" href="#supported-units"><em>unit attribute name</em></a> set with desired value. For example, the following creates a distance object representing 5 miles:</p> <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">dist</span> <span class="o">=</span> <span class="n">Distance</span><span class="p">(</span><span class="n">mi</span><span class="o">=</span><span class="mi">5</span><span class="p">)</span> </pre></div> </div> <dl class="method"> <dt id="django.contrib.gis.measure.Distance.__getattr__"> <tt class="descname">__getattr__</tt>(<em>unit_att</em>)<a class="headerlink" href="#django.contrib.gis.measure.Distance.__getattr__" title="Permalink to this definition">¶</a></dt> <dd></dd></dl> <p>Returns the distance value in units corresponding to the given unit attribute. For example:</p> <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">dist</span><span class="o">.</span><span class="n">km</span><span class="p">)</span> <span class="go">8.04672</span> </pre></div> </div> <dl class="classmethod"> <dt id="django.contrib.gis.measure.Distance.unit_attname"> <em class="property">classmethod </em><tt class="descname">unit_attname</tt>(<em>unit_name</em>)<a class="headerlink" href="#django.contrib.gis.measure.Distance.unit_attname" title="Permalink to this definition">¶</a></dt> <dd></dd></dl> <p>Returns the distance unit attribute name for the given full unit name. For example:</p> <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">Distance</span><span class="o">.</span><span class="n">unit_attname</span><span class="p">(</span><span class="s">'Mile'</span><span class="p">)</span> <span class="go">'mi'</span> </pre></div> </div> </dd></dl> <dl class="class"> <dt id="django.contrib.gis.measure.D"> <em class="property">class </em><tt class="descname">D</tt><a class="headerlink" href="#django.contrib.gis.measure.D" title="Permalink to this definition">¶</a></dt> <dd><p>Alias for <a class="reference internal" href="#django.contrib.gis.measure.Distance" title="django.contrib.gis.measure.Distance"><tt class="xref py py-class docutils literal"><span class="pre">Distance</span></tt></a> class.</p> </dd></dl> </div> <div class="section" id="s-area"> <span id="area"></span><h3><tt class="docutils literal"><span class="pre">Area</span></tt><a class="headerlink" href="#area" title="Permalink to this headline">¶</a></h3> <dl class="class"> <dt id="django.contrib.gis.measure.Area"> <em class="property">class </em><tt class="descname">Area</tt>(<em>**kwargs</em>)<a class="headerlink" href="#django.contrib.gis.measure.Area" title="Permalink to this definition">¶</a></dt> <dd><p>To initialize a distance object, pass in a keyword corresponding to the desired <a class="reference internal" href="#supported-units"><em>unit attribute name</em></a> set with desired value. For example, the following creates a distance object representing 5 square miles:</p> <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">a</span> <span class="o">=</span> <span class="n">Area</span><span class="p">(</span><span class="n">sq_mi</span><span class="o">=</span><span class="mi">5</span><span class="p">)</span> </pre></div> </div> <dl class="method"> <dt id="django.contrib.gis.measure.Area.__getattr__"> <tt class="descname">__getattr__</tt>(<em>unit_att</em>)<a class="headerlink" href="#django.contrib.gis.measure.Area.__getattr__" title="Permalink to this definition">¶</a></dt> <dd></dd></dl> <p>Returns the area value in units corresponding to the given unit attribute. For example:</p> <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">a</span><span class="o">.</span><span class="n">sq_km</span><span class="p">)</span> <span class="go">12.949940551680001</span> </pre></div> </div> <dl class="classmethod"> <dt id="django.contrib.gis.measure.Area.unit_attname"> <em class="property">classmethod </em><tt class="descname">unit_attname</tt>(<em>unit_name</em>)<a class="headerlink" href="#django.contrib.gis.measure.Area.unit_attname" title="Permalink to this definition">¶</a></dt> <dd></dd></dl> <p>Returns the area unit attribute name for the given full unit name. For example:</p> <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">Area</span><span class="o">.</span><span class="n">unit_attname</span><span class="p">(</span><span class="s">'Kilometer'</span><span class="p">)</span> <span class="go">'sq_km'</span> </pre></div> </div> </dd></dl> <dl class="class"> <dt id="django.contrib.gis.measure.A"> <em class="property">class </em><tt class="descname">A</tt><a class="headerlink" href="#django.contrib.gis.measure.A" title="Permalink to this definition">¶</a></dt> <dd><p>Alias for <a class="reference internal" href="#django.contrib.gis.measure.Area" title="django.contrib.gis.measure.Area"><tt class="xref py py-class docutils literal"><span class="pre">Area</span></tt></a> class.</p> </dd></dl> <p class="rubric">Footnotes</p> <table class="docutils footnote" frame="void" id="id3" rules="none"> <colgroup><col class="label" /><col /></colgroup> <tbody valign="top"> <tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td><a class="reference external" href="http://koordinates.com/">Robert Coup</a> is the initial author of the measure objects, and was inspired by Brian Beck’s work in <a class="reference external" href="http://code.google.com/p/geopy/">geopy</a> and Geoff Biggs’ PhD work on dimensioned units for robotics.</td></tr> </tbody> </table> </div> </div> </div> </div> </div> </div> <div class="yui-b" id="sidebar"> <div class="sphinxsidebar"> <div class="sphinxsidebarwrapper"> <h3><a href="../../../contents.html">Table Of Contents</a></h3> <ul> <li><a class="reference internal" href="#">Measurement Objects</a><ul> <li><a class="reference internal" href="#example">Example</a></li> <li><a class="reference internal" href="#supported-units">Supported units</a></li> <li><a class="reference internal" href="#measurement-api">Measurement API</a><ul> <li><a class="reference internal" href="#distance"><tt class="docutils literal"><span class="pre">Distance</span></tt></a></li> <li><a class="reference internal" href="#area"><tt class="docutils literal"><span class="pre">Area</span></tt></a></li> </ul> </li> </ul> </li> </ul> <h3>Browse</h3> <ul> <li>Prev: <a href="geoquerysets.html">GeoQuerySet API Reference</a></li> <li>Next: <a href="geos.html">GEOS API</a></li> </ul> <h3>You are here:</h3> <ul> <li> <a href="../../../index.html">Django 1.5.8 documentation</a> <ul><li><a href="../../index.html">API Reference</a> <ul><li><a href="../index.html"><tt class="docutils literal"><span class="pre">contrib</span></tt> packages</a> <ul><li><a href="index.html">GeoDjango</a> <ul><li>Measurement Objects</li></ul> </li></ul></li></ul></li></ul> </li> </ul> <h3>This Page</h3> <ul class="this-page-menu"> <li><a href="../../../_sources/ref/contrib/gis/measure.txt" rel="nofollow">Show Source</a></li> </ul> <div id="searchbox" style="display: none"> <h3>Quick search</h3> <form class="search" action="../../../search.html" method="get"> <input type="text" name="q" /> <input type="submit" value="Go" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> <p class="searchtip" style="font-size: 90%"> Enter search terms or a module, class or function name. </p> </div> <script type="text/javascript">$('#searchbox').show(0);</script> </div> </div> <h3>Last update:</h3> <p class="topless">May 15, 2014</p> </div> </div> <div id="ft"> <div class="nav"> « <a href="geoquerysets.html" title="GeoQuerySet API Reference">previous</a> | <a href="../../index.html" title="API Reference" accesskey="U">up</a> | <a href="geos.html" title="GEOS API">next</a> »</div> </div> </div> <div class="clearer"></div> </div> </body> </html>