<!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 v1.2 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.2',
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 v1.2 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 v1.2 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="n">d1</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="n">d2</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="n">d1</span><span class="o">.</span><span class="n">mi</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="n">d2</span><span class="o">.</span><span class="n">km</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="n">d1</span> <span class="o">+</span> <span class="n">d2</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="n">d2</span> <span class="o">-</span> <span class="n">d1</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="n">a</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="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="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><th class="head">Unit Attribute</th>
<th class="head">Full name or alias(es)</th>
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="docutils literal"><span class="pre">km</span></tt></td>
<td>Kilometre, Kilometer</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">mi</span></tt></td>
<td>Mile</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">m</span></tt></td>
<td>Meter, Metre</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">yd</span></tt></td>
<td>Yard</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">ft</span></tt></td>
<td>Foot, Foot (International)</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">survey_ft</span></tt></td>
<td>U.S. Foot, US survey foot</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">inch</span></tt></td>
<td>Inches</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">cm</span></tt></td>
<td>Centimeter</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">mm</span></tt></td>
<td>Millimetre, Millimeter</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">um</span></tt></td>
<td>Micrometer, Micrometre</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">british_ft</span></tt></td>
<td>British foot (Sears 1922)</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">british_yd</span></tt></td>
<td>British yard (Sears 1922)</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">british_chain_sears</span></tt></td>
<td>British chain (Sears 1922)</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">indian_yd</span></tt></td>
<td>Indian yard, Yard (Indian)</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">sears_yd</span></tt></td>
<td>Yard (Sears)</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">clarke_ft</span></tt></td>
<td>Clarke's Foot</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">chain</span></tt></td>
<td>Chain</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">chain_benoit</span></tt></td>
<td>Chain (Benoit)</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">chain_sears</span></tt></td>
<td>Chain (Sears)</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">british_chain_benoit</span></tt></td>
<td>British chain (Benoit 1895 B)</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">british_chain_sears_truncated</span></tt></td>
<td>British chain (Sears 1922 truncated)</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">gold_coast_ft</span></tt></td>
<td>Gold Coast foot</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">link</span></tt></td>
<td>Link</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">link_benoit</span></tt></td>
<td>Link (Benoit)</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">link_sears</span></tt></td>
<td>Link (Sears)</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">clarke_link</span></tt></td>
<td>Clarke's link</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">fathom</span></tt></td>
<td>Fathom</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">rod</span></tt></td>
<td>Rod</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">nm</span></tt></td>
<td>Nautical Mile</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">nm_uk</span></tt></td>
<td>Nautical Mile (UK)</td>
</tr>
<tr><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="n">dist</span><span class="o">.</span><span class="n">km</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="n">a</span><span class="o">.</span><span class="n">sq_km</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 v1.2 documentation</a>
<ul><li><a href="../../index.html">API Reference</a>
<ul><li><a href="../index.html"><tt class="docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal 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" size="18" />
<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">Oct 20, 2010</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>
distrib
>
Arklinux
>
devel
>
i586
>
media
>
main
>
by-pkgid
>
5fcb1fedf34660bc240dc59b7bfcebc4
>
files
>
356
