/usr/share/doc/pyosmium-doc/html/intro.html is in pyosmium-doc 2.11.3-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 | <!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>Basic Usage — Pyosmium 2.11.3 documentation</title>
<link rel="stylesheet" href="_static/classic.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '2.11.3',
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="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="top" title="Pyosmium 2.11.3 documentation" href="index.html" />
<link rel="next" title="Pyosmium Reference" href="reference.html" />
<link rel="prev" title="Welcome to Pyosmium’s documentation!" href="index.html" />
</head>
<body role="document">
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="reference.html" title="Pyosmium Reference"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="index.html" title="Welcome to Pyosmium’s documentation!"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">Pyosmium 2.11.3 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="basic-usage">
<h1>Basic Usage<a class="headerlink" href="#basic-usage" title="Permalink to this headline">¶</a></h1>
<p>The following chapter gives a practical introduction on how to use Pyosmium.
It is assumed that you already have a basic knowledge about the
<a class="reference external" href="http://wiki.openstreetmap.org/wiki/Elements">OSM data model</a>.</p>
<p>For a more detailed introduction into the design of the osmium library, the
reader is referred to the <a class="reference external" href="http://osmcode.org/libosmium/manual/libosmium-manual.html">osmium documentation</a>.</p>
<div class="section" id="reading-osm-data">
<h2>Reading OSM Data<a class="headerlink" href="#reading-osm-data" title="Permalink to this headline">¶</a></h2>
<div class="section" id="using-handler-classes">
<h3>Using Handler Classes<a class="headerlink" href="#using-handler-classes" title="Permalink to this headline">¶</a></h3>
<p>OSM file parsing by osmium is built around the concept of handlers. A handler
is a class with a set of callback functions. Each function processes exactly
one type of object as it is read from the file.</p>
<p>Let’s start with a very simple handler that counts the nodes in the
input file:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">osmium</span>
<span class="k">class</span> <span class="nc">CounterHandler</span><span class="p">(</span><span class="n">osmium</span><span class="o">.</span><span class="n">SimpleHandler</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="n">osmium</span><span class="o">.</span><span class="n">SimpleHandler</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span>
<span class="bp">self</span><span class="o">.</span><span class="n">num_nodes</span> <span class="o">=</span> <span class="mi">0</span>
<span class="k">def</span> <span class="nf">node</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">n</span><span class="p">):</span>
<span class="bp">self</span><span class="o">.</span><span class="n">num_nodes</span> <span class="o">+=</span> <span class="mi">1</span>
</pre></div>
</div>
<p>A handler first of all needs to inherit from one of the handler classes.
At the moment this is always <a class="reference internal" href="ref_osmium.html#osmium.SimpleHandler" title="osmium.SimpleHandler"><code class="xref py py-class docutils literal"><span class="pre">osmium.SimpleHandler</span></code></a>. Then it
needs to implement functions for each object type it wants to process. In
out case it is exactly one function <cite>node()</cite>. All other potential callbacks
can be safely ignored.</p>
<p>Now the handler needs to be applied to an OSM file. The easiest way to
accomplish that is to call the <a class="reference internal" href="ref_osmium.html#osmium.SimpleHandler.apply_file" title="osmium.SimpleHandler.apply_file"><code class="xref py py-meth docutils literal"><span class="pre">apply_file()</span></code></a>
convenience function, which in its simplest form only requires the file name
as a parameter. The main routine of the node counting application
therefore looks like this:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s1">'__main__'</span><span class="p">:</span>
<span class="n">h</span> <span class="o">=</span> <span class="n">CounterHandler</span><span class="p">()</span>
<span class="n">h</span><span class="o">.</span><span class="n">apply_file</span><span class="p">(</span><span class="s2">"test.osm.pbf"</span><span class="p">)</span>
<span class="nb">print</span><span class="p">(</span><span class="s2">"Number of nodes: </span><span class="si">%d</span><span class="s2">"</span> <span class="o">%</span> <span class="n">h</span><span class="o">.</span><span class="n">num_nodes</span><span class="p">)</span>
</pre></div>
</div>
<p>That already finishes our node counting program.</p>
</div>
<div class="section" id="inspecting-the-osm-objects">
<h3>Inspecting the OSM objects<a class="headerlink" href="#inspecting-the-osm-objects" title="Permalink to this headline">¶</a></h3>
<p>Counting nodes is actually boring because it completely ignores the
content of the nodes. So let’s change the handler to only count hotels
(normally tagged with <code class="docutils literal"><span class="pre">tourism=hotel</span></code>). They may be tagged as nodes, ways
or relations, so handler functions for all three types need to be implemented:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">osmium</span>
<span class="k">class</span> <span class="nc">HotelCounterHandler</span><span class="p">(</span><span class="n">osmium</span><span class="o">.</span><span class="n">SimpleHandler</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="n">osmium</span><span class="o">.</span><span class="n">SimpleHandler</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span>
<span class="bp">self</span><span class="o">.</span><span class="n">num_nodes</span> <span class="o">=</span> <span class="mi">0</span>
<span class="k">def</span> <span class="nf">count_hotel</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">tags</span><span class="p">):</span>
<span class="k">if</span> <span class="n">tags</span><span class="p">[</span><span class="s1">'tourism'</span><span class="p">]</span> <span class="o">==</span> <span class="s1">'hotel'</span><span class="p">:</span>
<span class="bp">self</span><span class="o">.</span><span class="n">num_nodes</span> <span class="o">+=</span> <span class="mi">1</span>
<span class="k">def</span> <span class="nf">node</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">n</span><span class="p">):</span>
<span class="bp">self</span><span class="o">.</span><span class="n">count_hotel</span><span class="p">(</span><span class="n">n</span><span class="o">.</span><span class="n">tags</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">way</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">w</span><span class="p">):</span>
<span class="bp">self</span><span class="o">.</span><span class="n">count_hotel</span><span class="p">(</span><span class="n">w</span><span class="o">.</span><span class="n">tags</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">relation</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">r</span><span class="p">):</span>
<span class="bp">self</span><span class="o">.</span><span class="n">count_hotel</span><span class="p">(</span><span class="n">r</span><span class="o">.</span><span class="n">tags</span><span class="p">)</span>
</pre></div>
</div>
<p>A reference to the object is always given as the only parameter to the
handler functions. The objects have some common methods and attributes,
listed in <a class="reference internal" href="ref_osm.html#osmium.osm.OSMObject" title="osmium.osm.OSMObject"><code class="xref py py-class docutils literal"><span class="pre">osmium.osm.OSMObject</span></code></a>, and some that are specific to
each type. As all objects have tags, it is possible to reuse the same
implementation for all types. The main function remains the same.</p>
<p>It is important to remember that the object
references that are handed to the handler are only temporary. They will
become invalid as soon as the function returns. Handler functions <em>must</em>
copy any data that should be kept for later use into their own data
structures. This also includes attributes like tag lists.</p>
</div>
<div class="section" id="handling-geometries">
<h3>Handling Geometries<a class="headerlink" href="#handling-geometries" title="Permalink to this headline">¶</a></h3>
<p>Because of the way that OSM data is structured, osmium needs to internally
cache node geometries, when the handler wants to process the geometries of
ways and areas. The <code class="xref py py-meth docutils literal"><span class="pre">apply_file()</span></code> method cannot
deduct by itself, if this cache is needed. Therefore locations need to be
explicitly enabled by setting the location parameter to true:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">h</span><span class="o">.</span><span class="n">apply_file</span><span class="p">(</span><span class="s2">"test.osm.pbf"</span><span class="p">,</span> <span class="n">locations</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">idx</span><span class="o">=</span><span class="s1">'sparse_mem_array'</span><span class="p">)</span>
</pre></div>
</div>
<p>The third parameter <cite>idx</cite> is optional and states what kind of cache
osmium is supposed to use. The default <cite>sparse_mem_array</cite> is a good
choice for small to medium size extracts of OSM data. If you plan to
process the whole planet file, <cite>dense_mmap_array</cite> is better suited.
If you want the cache to be persistent across invocations, you
can use <cite>dense_file_array</cite> giving an additional file location for the
cache like that:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">h</span><span class="o">.</span><span class="n">apply_file</span><span class="p">(</span><span class="s2">"test.osm.pbf"</span><span class="p">,</span> <span class="n">locations</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">idx</span><span class="o">=</span><span class="s1">'sparse_file_array,example.nodecache'</span><span class="p">)</span>
</pre></div>
</div>
<p>where <cite>example.nodecache</cite> is the name of the cache file.</p>
</div>
<div class="section" id="interfacing-with-shapely">
<h3>Interfacing with Shapely<a class="headerlink" href="#interfacing-with-shapely" title="Permalink to this headline">¶</a></h3>
<p>Pyosmium is a library for processing OSM files and therefore offers almost
no functionality for processing geometries further. There are other libraries
for that puspose. To interface with these libraries you can simply convert the
osmium geometries into WKB or WKT format and import the result. The following
example uses the libgeos wrapper <a class="reference external" href="http://toblerity.org/shapely/index.html">Shapely</a> to compute the total way length:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">osmium</span>
<span class="kn">import</span> <span class="nn">shapely.wkb</span> <span class="k">as</span> <span class="nn">wkblib</span>
<span class="c1"># A global factory that creates WKB from a osmium geometry</span>
<span class="n">wkbfab</span> <span class="o">=</span> <span class="n">osmium</span><span class="o">.</span><span class="n">geom</span><span class="o">.</span><span class="n">WKBFactory</span><span class="p">()</span>
<span class="k">class</span> <span class="nc">WayLenHandler</span><span class="p">(</span><span class="n">osmium</span><span class="o">.</span><span class="n">SimpleHandler</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="n">osmium</span><span class="o">.</span><span class="n">SimpleHandler</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span>
<span class="bp">self</span><span class="o">.</span><span class="n">total</span> <span class="o">=</span> <span class="mi">0</span>
<span class="k">def</span> <span class="nf">way</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">w</span><span class="p">):</span>
<span class="n">wkb</span> <span class="o">=</span> <span class="n">wkbfab</span><span class="o">.</span><span class="n">create_linestring</span><span class="p">(</span><span class="n">w</span><span class="p">)</span>
<span class="n">line</span> <span class="o">=</span> <span class="n">wkblib</span><span class="o">.</span><span class="n">loads</span><span class="p">(</span><span class="n">wkb</span><span class="p">,</span> <span class="nb">hex</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="c1"># Length is computed in WGS84 projection, which is practically meaningless.</span>
<span class="c1"># Lets pretend we didn't notice, it is an example after all.</span>
<span class="bp">self</span><span class="o">.</span><span class="n">total</span> <span class="o">+=</span> <span class="n">line</span><span class="o">.</span><span class="n">length</span>
<span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s1">'__main__'</span><span class="p">:</span>
<span class="n">h</span> <span class="o">=</span> <span class="n">WayLenHandler</span><span class="p">()</span>
<span class="n">h</span><span class="o">.</span><span class="n">apply_file</span><span class="p">(</span><span class="s2">"test.osm.pbf"</span><span class="p">,</span> <span class="n">locations</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="nb">print</span><span class="p">(</span><span class="s2">"Total length: </span><span class="si">%f</span><span class="s2">"</span> <span class="o">%</span> <span class="n">h</span><span class="o">.</span><span class="n">total</span><span class="p">)</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="writing-osm-data">
<h2>Writing OSM Data<a class="headerlink" href="#writing-osm-data" title="Permalink to this headline">¶</a></h2>
<p><a class="reference internal" href="ref_osmium.html#osmium.SimpleWriter" title="osmium.SimpleWriter"><code class="xref py py-class docutils literal"><span class="pre">osmium.SimpleWriter</span></code></a> is the main class that takes care of
writing out OSM data to a file. The file name must be given when the
writer is constructed. Its suffix determines the format of the data.
For example:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">writer</span> <span class="o">=</span> <span class="n">osmium</span><span class="o">.</span><span class="n">SimpleWriter</span><span class="p">(</span><span class="s1">'nodes.osm.bz2'</span><span class="p">)</span>
</pre></div>
</div>
<p>opens a new writer for a packed OSM XML file. Objects can be written
by using one of the writers <code class="docutils literal"><span class="pre">add_*</span></code> functions.</p>
<p>A simple handler, that only writes out all the nodes from the input
file into out new <code class="docutils literal"><span class="pre">nodes.osm.bz2</span></code> file would look like this:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">osmium</span>
<span class="k">class</span> <span class="nc">NodeWriter</span><span class="p">(</span><span class="n">osmium</span><span class="o">.</span><span class="n">SimpleHandler</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">writer</span><span class="p">):</span>
<span class="n">osmium</span><span class="o">.</span><span class="n">SimpleHandler</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span>
<span class="bp">self</span><span class="o">.</span><span class="n">writer</span> <span class="o">=</span> <span class="n">writer</span>
<span class="k">def</span> <span class="nf">node</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">n</span><span class="p">):</span>
<span class="bp">self</span><span class="o">.</span><span class="n">writer</span><span class="o">.</span><span class="n">add_node</span><span class="p">(</span><span class="n">n</span><span class="p">)</span>
</pre></div>
</div>
<p>This example shows that an unmodified object can be written out directly
to the writer. Normally, however, you want to modify some data. The native
osmium OSM types are immutable and cannot be changed directly. Therefore
you have create a copy that can be changed. The <code class="docutils literal"><span class="pre">node</span></code>, <code class="docutils literal"><span class="pre">way</span></code> and <code class="docutils literal"><span class="pre">relation</span></code>
objects offer a convenient <code class="docutils literal"><span class="pre">replace()</span></code> function to achieve exactly that.
The function makes a copy and a the same time replaces all attibutes where
new values are given as parameters to the function.</p>
<p>Let’s say you want to
remove all the user names from your nodes before saving them to the new
file (maybe to save some space), then the <code class="docutils literal"><span class="pre">node()</span></code> handler callback above
needs to be changed like that:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">NodeWriter</span><span class="p">(</span><span class="n">osmium</span><span class="o">.</span><span class="n">SimpleHandler</span><span class="p">):</span>
<span class="o">...</span>
<span class="k">def</span> <span class="nf">node</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">n</span><span class="p">):</span>
<span class="bp">self</span><span class="o">.</span><span class="n">writer</span><span class="o">.</span><span class="n">add_node</span><span class="p">(</span><span class="n">n</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span><span class="n">user</span><span class="o">=</span><span class="s2">""</span><span class="p">))</span>
</pre></div>
</div>
<p><code class="docutils literal"><span class="pre">replace()</span></code> creates a new instance of an <code class="docutils literal"><span class="pre">osmium.osm.mutable</span></code> object. These
classes are python implementations of the native object types in <code class="docutils literal"><span class="pre">osmium.osm</span></code>.
They have exactly the same attributes but they are mutable.</p>
<p>A writer is able to process the mutable datatypes just like the native osmium
types. In fact, a writer is able to process any python object. It just expects
suitably named attributes and will simply assume sensible default values for
attributes that are missing.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">It is important to understand that <code class="docutils literal"><span class="pre">replace()</span></code> only makes a shallow copy
of the object. Tag, node and member lists are still native osmium objects.
Normally this is what you want because the writer is much faster writing
these native objects than pythonized copies. However, it means that you
cannot use <code class="docutils literal"><span class="pre">replace()</span></code> to create a copy of the object that can be kept
after the handler callback has finished.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Basic Usage</a><ul>
<li><a class="reference internal" href="#reading-osm-data">Reading OSM Data</a><ul>
<li><a class="reference internal" href="#using-handler-classes">Using Handler Classes</a></li>
<li><a class="reference internal" href="#inspecting-the-osm-objects">Inspecting the OSM objects</a></li>
<li><a class="reference internal" href="#handling-geometries">Handling Geometries</a></li>
<li><a class="reference internal" href="#interfacing-with-shapely">Interfacing with Shapely</a></li>
</ul>
</li>
<li><a class="reference internal" href="#writing-osm-data">Writing OSM Data</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="index.html"
title="previous chapter">Welcome to Pyosmium’s documentation!</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="reference.html"
title="next chapter">Pyosmium Reference</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/intro.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<div><input type="text" name="q" /></div>
<div><input type="submit" value="Go" /></div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="reference.html" title="Pyosmium Reference"
>next</a> |</li>
<li class="right" >
<a href="index.html" title="Welcome to Pyosmium’s documentation!"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">Pyosmium 2.11.3 documentation</a> »</li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2015-2017, Sarah Hoffmann.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.4.9.
</div>
</body>
</html>
|