pbf_craft/
lib.rs

1//! A pure-Rust library for reading and writing OpenStreetMap **PBF** (Protocolbuffer
2//! Binary Format) files.
3//!
4//! # Modules
5//!
6//! - [`models`] — the OSM element model: [`models::Node`], [`models::Way`],
7//!   [`models::Relation`] and the [`models::Element`] enum, with coordinates in
8//!   integer nanodegrees.
9//! - [`readers`] — a family of readers for different scenarios:
10//!   - [`readers::PbfReader`] — sequential streaming reader (single- or multi-threaded
11//!     filtering via [`readers::PbfReader::par_find`]).
12//!   - [`readers::IterableReader`] — iterator-based reader with byte progress reporting
13//!     ([`readers::ReaderProgress`]).
14//!   - [`readers::IndexedReader`] — random access by element id, backed by a `.pif` index
15//!     file, with an in-memory blob cache and dependency resolution
16//!     ([`readers::IndexedReader::get_with_deps`]).
17//! - [`writers`] — [`writers::PbfWriter`], a streaming writer producing zlib-compressed
18//!   blobs with dense-node support.
19//!
20//! # Examples
21//!
22//! Read PBF data from a file:
23//!
24//! ```rust
25//! use pbf_craft::readers::PbfReader;
26//!
27//! let mut reader = PbfReader::from_path("resources/andorra-latest.osm.pbf").unwrap();
28//! reader.read(|header, element| {
29//!     if let Some(header_reader) = header {
30//!         // Process header
31//!     }
32//!     if let Some(element) = element {
33//!         // Process element
34//!     }
35//! }).unwrap();
36//! ```
37//!
38//! Read PBF data with dependencies:
39//!
40//! ```rust
41//! use pbf_craft::models::ElementType;
42//! use pbf_craft::readers::IndexedReader;
43//!
44//! let mut indexed_reader =
45//!     IndexedReader::from_path_with_cache("resources/andorra-latest.osm.pbf", 1000).unwrap();
46//! let element_list = indexed_reader.get_with_deps(&ElementType::Way, 12345678).unwrap();
47//! ```
48//!
49//! Write PBF data to a file:
50//!
51//! ```rust
52//! use pbf_craft::models::{Element, Node};
53//! use pbf_craft::writers::PbfWriter;
54//!
55//! let mut writer = PbfWriter::from_path(std::env::temp_dir().join("output.osm.pbf"), true).unwrap();
56//! writer.write(Element::Node(Node::default())).unwrap();
57//! writer.finish().unwrap();
58//! ```
59//!
60//! # Data format notes
61//!
62//! - **Coordinates**: `Node`/`WayNode`/`Bound` coordinates are i64 **nanodegrees** (the raw
63//!   PBF unit; divide by 1e9 for degrees).
64//! - **Ordering**: the PBF format does not require sorted elements, but the conventional
65//!   layout (all nodes by id, then all ways by id, then all relations by id) is assumed by
66//!   `IndexedReader` and most other tools. `PbfWriter` stores elements in the order written —
67//!   the caller is responsible for the order.
68//! - **Compression**: reading supports `raw`, `zlib`, `lz4` and `zstd` blobs; writing
69//!   produces `zlib`-compressed blobs.
70//! - **visible flag**: elements default to `visible = true` (per spec, the flag is assumed
71//!   true when absent). Elements explicitly marked `visible = false` are written with the
72//!   required `HistoricalInformation` feature declared in the header.
73//! - **Error handling**: all fallible operations return `anyhow::Result`; malformed or
74//!   truncated input surfaces as errors rather than panics.
75// Generated protobuf code emits `unused_parens` (a rustc lint) that `#![allow(clippy::all)]`
76// inside `mod proto` cannot suppress (parent-module inner attributes do not reach child
77// modules). Silence it crate-wide for the generated files.
78#![allow(unused_parens)]
79
80mod codecs;
81/// Contains models for elements of OpenStreetMap data.
82pub mod models;
83/// Contains readers for reading PBF data.
84pub mod readers;
85mod utils;
86/// Contains writers for writing PBF data.
87pub mod writers;
88
89mod proto {
90    #![allow(renamed_and_removed_lints)]
91    #![allow(mismatched_lifetime_syntaxes)]
92    #![allow(clippy::all)]
93    include!(concat!(env!("OUT_DIR"), "/mod.rs"));
94}
95
96#[macro_use]
97extern crate anyhow;
pbf_craft/lib.rs

pbf_craft/
lib.rs
