|This page is about the "old" Osmium. For the new version see http://osmcode.org/libosmium .|
Handlers tie together the other parts of Osmium to do one specific job, often some kind of transformation of OSM data. They define callbacks that get called for every object that is read from some input file.
Osmium comes with some handlers, but chances are you want to write your own for specific uses.
All handlers should use Osmium::Handler::Base
as a public base class. It defines some empty methods that can be (but don't have to be) overwritten in your subclass. You can also derive your handler from Osmium::Handler::Forward
which forwards all calls to another handler.
The following methods are available:
- node(const shared_ptr<Osmium::OSM::Node
- way(const shared_ptr<Osmium::OSM::Way
- relation(const shared_ptr<Osmium::OSM::Relation
- area(const shared_ptr<Osmium::OSM::Area
The init() and final() methods are called just before and right after parsing the input. They can be used for initialization and cleanup, but you can also just use the constructors and destructors of your class for that.
For every object node(), way(), or relation() will be called, respectively.
When there are several objects of the same type in a row the before_*() function will be called before them and the after_*() function after them. If your input file is sorted as OSM files normally are, i.e. all nodes, then all ways, then all relations, this will call before_nodes() once, then for all the nodes node(), then after_nodes(), then before_ways(), and so on. This will also work properly if the input file contains, say, first all relations, than all ways and then all nodes.
But if you have nodes, ways, and relations intermixed in an input file these handlers will probably not be called in a useful way for you. You can use osmosis --sort to sort your input file first.
The area() callback is special. It will only be called if you have the multipolygon handler before your handler. There are no before/after_areas() callbacks. Use init() and final() instead.
For some applications reading the input file once is not enough. Instead they read the input twice (or more times). To assemble multipolygons for instance, the input is read twice. On the first pass the application builds a list of multipolygon relations in memory, on the second pass it adds ways to those multipolygons and builds the geometries.
Most handlers work in single pass mode only, but some handlers might supply different callbacks for different stages.