Crate libosmium

Libosmium

Rust binding and wrapper around the excellent libosmium c++ library.

Maintenance

This crate was started out of necessity for a larger project. Therefore, it won’t get much attention unless I need another feature or find a bug. But feel free to contribute.

What it does

This crate exposes libosmium’s osm object classes (i.e. OSMObject, Node, Way, etc.) and the Handler interface to read those from a file (currently only .pbf).

Since libosmium has its own memory management, all objects are only exposed via references. So most of the types on rust’s side are empty enums which can’t be instantiated.

To expose these c++ classes’ methods, this crate uses a small c++ shim (namely src/libosmium.cpp) which reexports them as un-mangled functions taking pointers. Methods whose behaviour is trivial enough are simply implemented directly in rust to avoid unnecessary boilerplate.

Build dependencies

This package builds libosmium and therefore needs its dependencies.

Install for debian:

apt install build-essential libboost-dev libprotozero-dev zlib1g-dev

Install for arch:

pacman -Sy cmake make boost-libs protozero zlib

Where to start

As stated above this crate is for reading osm objects from a file. Therefore, you should start with the Handler trait which does exactly that.

Re-exports

pub use handler::Handler;

Modules

handler

defines the heart of this crate, the Handler.

node_ref_list

defines types storing a list of nodes.

tag_list

defines the TagList as well as its iterator.

Macros

tag_list

Nice syntax for creating an OwnedTagList using literals.

Structs

Item

This type is the base class responsible for libosmium’s custom memory management.

ItemBuffer

Buffer to clone OSM items into

Location

A gps coordinate in angles of latitude and longitude

NodeRef

Reference to a Node

Enums

Area

An area, as the name suggests, is some mapped area with tags.

ItemRef

Enum for converting an Item reference into a reference of its actual subclass.

Node

A Node is some point on the map with associated tags.

OSMObject

Base class for OSM ’s objects:

Way

A way is a tagged list of Nodes.

Constants

PRECISION

The precision longitude and latitude are stored with.