Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.
osmpbf
A Rust library for reading the OpenStreetMap PBF file format (*.osm.pbf). It strives to offer the best performance using parallelization and lazy-decoding with a simple interface while also exposing iterators for items of every level in a PBF file.
Usage
Add this to your Cargo.toml
:
[]
= "0.1"
and this to your crate root:
extern crate osmpbf;
Here's a simple example that counts all the ways in a file:
extern crate osmpbf;
use *;
In this second example, we also count the ways but make use of all cores by decoding the file in parallel:
use *;
The PBF format
To effectively use the more lower-level features of this library it is useful to
have an overview of the structure of a PBF file. For a more detailed format
description see here or take a
look at the .proto
files in this repository.
The PBF format as a hierarchy (square brackets []
denote arrays):
Blob[]
├── HeaderBlock
└── PrimitiveBlock
└── Group[]
├── Node[]
├── DenseNodes
├── Way[]
└── Relation[]
At the highest level a PBF file consists of a sequence of Blobs. Each Blob can be decoded into either a HeaderBlock or a PrimitiveBlock.
Iterating over Blobs is very fast, but decoding might involve a more expensive decompression step. So especially for larger files it is advisable to parallelize at the Blob level as each Blob can be decompressed independently.
Usually the first Blob of a file decodes to a HeaderBlock which holds global information for all following PrimitiveBlocks, such as a list of required parser features.
A PrimitiveBlock contains an array of Groups (named PrimitiveGroup
in
osmformat.proto). Each Group only contains one element type: Node, Way,
Relation or DenseNodes. A DenseNodes item is an alternative and space-saving
representation of a Node array. So, do not forget to check for DenseNodes when
aggregating all nodes in a file.
Elements reference each other using integer IDs. Corresponding elements could be stored in any Blob, so finding them can involve iterating over the whole file. Some files declare an optional feature "Sort.Type_then_ID" in the HeaderBlock to indicate that elements are stored sorted by their type and then ID. This can be used to dramatically reduce the search space.
License
This project is licensed under either of
- Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.