From OpenStreetMap Wiki
Jump to: navigation, search

Osmium gives you a large number of building blocks that you can assemble in different ways. The blocks belong to the following major components. See the API documentation for the gory details.

OSM Objects

Namespace: Osmium::OSM

These are the basic building blocks for OSM data. There are classes for OSM objects (Osmium::OSM::Node

, Osmium::OSM::Way

, and Osmium::OSM::Relation

) and a Pseudo-OSM-Object Osmium::OSM::Area

and the parts they are made of such as Osmium::OSM::Tag

, Osmium::OSM::TagList

, Osmium::OSM::RelationMember

, etc. All other components build on these.

This component can be used independently from the rest of the toolkit.


Namespace: Osmium::Geometry

Contains the classes Point, LineString, Polygon and MultiPolygon. They describe the geometries that can be created from OSM objects and have methods to convert those geometries into several formats.

Geometries are created as follows:

from Osmium::OSM::Node

and Osmium::Geometry::Polygon
from Osmium::OSM::Way
(forward or reverse, consecutive duplicate coordinates are removed)
from Osmium::OSM::Relation
and Osmium::OSM::Way
(see Osmium/Multipolygon for details)

Geometries can be converted into the following formats:

  • GEOS geometries
  • OGR geometries (to help in converting OSM data into any OGR supported format)
  • WKT, WKB or HexWKB format (optionally including the SRID)
  • Shapelib geometries (for export to Shapefiles)
  • If you are using the Javascript component, you can also create arrays from geometries for GeoJSON export.

OSM Files

Class: Osmium::OSMFile

Describe OSM files of different types (normal current OSM data, OSM data with object history) and encodings (PBF, XML, XML compressed with gzip or bzip2).

Transparently handles compressing and uncompressing (using the gzip or bzip2 command line programs, respectively). Can get files from a URL (using curl).

Handles input from files or STDIN and output to files or STDOUT.

The OSMFile class does not actually read or write files, but works as a factory class for readers and writers.


Namespace: Osmium::Input

Read OSM files with different formats and calls into handlers for each object.


Namespace: Osmium::Handler

Osmium handlers take OSM data object by object as they come from the input component and do something with it. Usually several different handlers will be connected in an application. Some of them will be handlers provided by Osmium for common tasks, some of the handlers will be written by you for special cases.

Osmium includes the following handlers:

Gets coordinates from nodes as they are read and stores them. Add those coordinates to the ways so that way geometries can be built.
Shows all objects with their attributes and tags for debugging.
Add last time an object version is valid to object. (Can be used when working with history data.)
Find bounding box from node coordinates.
Assembles multipolyons from relations. See Multipolygon for details.
Shows progress on terminal. Intended to be used together with other handlers.
Extract objects valid in a given timestamp range from history data.
Collects some basic statistics about the input file and writes it to an Sqlite file. This is mostly intended to be a simple example of handler usw.

There are some programs in the examples directory that use those handlers.

Writing your own handler is easy. See Handler.


Namespace: Osmium::Output

Output of OSM data into files. Output classes are handlers, too.


Namespace: Osmium::Export

Output of structured data in several different formats:

  • CSV
  • Shapefiles


Namespace: Osmium::Storage

Osmium is mainly used in streaming mode, i.e. OSM objects are read and immediately handled in some way. This allows working with huge amounts of data. But sometimes this is not enough. Sometimes part of the data has to be stored in main memory or on disk. The classes in the storage component help with that. They supply different kinds of ways of storing data.

Class: Osmium::Storage::ById

Used to keep node positions that are needed later to compute way and multipolygon geometries.

Class: Osmium::Storage::ObjectStore

Keep OSM objects in RAM. This is a convenient way of keeping complete OSM objects in RAM. But note that OSM objects are large, you can only keep a few of them around.


Namespace: Osmium::Javascript

See Osmium/Javascript.