Crate pbfhogg 

A fast reader and writer for the OpenStreetMap PBF file format (*.osm.pbf).

Usage

Add this to your Cargo.toml:

[dependencies]
pbfhogg = "0.3"

Example: Count ways

Here’s a simple example that counts all the OpenStreetMap way elements in a file:

use pbfhogg::{ElementReader, Element};

let reader = ElementReader::from_path("tests/test.osm.pbf")?;
let mut ways = 0_u64;

// Increment the counter by one for each way.
reader.for_each(|element| {
    if let Element::Way(_) = element {
        ways += 1;
    }
})?;

println!("Number of ways: {ways}");

Example: Count ways in parallel

In this second example, we also count the ways but make use of all cores by decoding the file in parallel:

use pbfhogg::{ElementReader, Element};

let reader = ElementReader::from_path("tests/test.osm.pbf")?;

// Count the ways
let ways = reader.par_map_reduce(
    |element| {
        match element {
            Element::Way(_) => 1,
            _ => 0,
        }
    },
    || 0_u64,      // Zero is the identity value for addition
    |a, b| a + b   // Sum the partial results
)?;

println!("Number of ways: {ways}");

Example: Write a PBF file

Build blocks with [BlockBuilder] and write them with [PbfWriter]:

use pbfhogg::write::block_builder::{BlockBuilder, HeaderBuilder};
use pbfhogg::write::writer::{PbfWriter, Compression};

let header_bytes = HeaderBuilder::new()
    .bbox(9.0, 54.0, 13.0, 58.0)
    .sorted()
    .build()?;
let mut writer = PbfWriter::to_path(
    "output.osm.pbf".as_ref(),
    Compression::default(),
    &header_bytes,
)?;

let mut bb = BlockBuilder::new();
bb.add_node(1, 556_761_000, 125_683_000, [("name", "Copenhagen")], None);

// Flush the block to the writer - compression dispatches to rayon
if let Some(block_bytes) = bb.take()? {
    writer.write_primitive_block(block_bytes)?;
}
writer.flush()?;

Example: In-memory writing

For tests or small PBFs, use [PbfWriter::new] with any Write impl:

use pbfhogg::write::block_builder::{BlockBuilder, HeaderBuilder};
use pbfhogg::write::writer::{PbfWriter, Compression};

let header_bytes = HeaderBuilder::new().sorted().build()?;
let mut buf = std::io::Cursor::new(Vec::new());
let mut writer = PbfWriter::new(&mut buf, Compression::default());
writer.write_header(&header_bytes)?;

let mut bb = BlockBuilder::new();
// ... add elements, write blocks synchronously ...
writer.flush()?;

Re-exports

pub use read::blob::Blob;

pub use read::blob::BlobDecode;

pub use read::blob::BlobHeader;

pub use read::blob::BlobReader;

pub use read::blob::BlobReaderSource;

pub use read::blob::BlobType;

pub use read::blob::ByteOffset;

pub use read::blob::MAX_BLOB_HEADER_SIZE;

pub use read::blob::MAX_BLOB_MESSAGE_SIZE;

pub use read::block::BlockElementsIter;

pub use read::block::BlockType;

pub use read::block::GroupIter;

pub use read::block::GroupNodeIter;

pub use read::block::GroupRelationIter;

pub use read::block::GroupWayIter;

pub use read::block::HeaderBBox;

pub use read::block::HeaderBlock;

pub use read::block::PrimitiveBlock;

pub use read::block::PrimitiveGroup;

pub use read::dense::DenseNode;

pub use read::dense::DenseNodeInfo;

pub use read::dense::DenseNodeInfoIter;

pub use read::dense::DenseNodeIter;

pub use read::dense::DenseRawTagIter;

pub use read::dense::DenseTagIter;

pub use read::elements::Element;

pub use read::elements::Info;

pub use read::elements::MemberId;

pub use read::elements::MemberType;

pub use read::elements::Node;

pub use read::elements::RawTagIter;

pub use read::elements::RelMember;

pub use read::elements::RelMemberIter;

pub use read::elements::Relation;

pub use read::elements::TagIter;

pub use read::elements::Way;

pub use read::elements::WayNodeLocation;

pub use read::elements::WayNodeLocationsIter;

pub use read::elements::WayRefIter;

pub use read::indexed::IdRanges;

pub use read::indexed::IndexedReader;

pub use read::reader::ElementReader;

pub use read::reader::PipelinedBlocks;

pub use read::blob;

pub use read::block;

pub use read::dense;

pub use read::elements;

pub use read::indexed;

pub use read::reader;

pub use write::block_builder;

pub use write::writer;

Modules

debug

geo

Shared geometry primitives for spatial operations.

geocode_index

Reverse geocoding index: binary format, reader, and builder.

osc

OpenStreetMap change format (OSC).

read

write

Structs

BlobBbox

Spatial bounding box in decimicrodegrees (10⁻⁷ degrees).

BlobFilter

Filter for skipping blobs by element type during pipelined reads.

Error

An error that can occur when reading or writing PBF files.

Enums

BlobError

An error that occurs when decoding a blob.

ErrorKind

The specific type of an error.

Type Aliases

Result

A type alias for Result<T, pbfhogg::Error>.