pbf-craft 1.0.2

A Rust library for reading and writing OpenSteetMap PBF file format.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96

# pbf-craft

A pure-Rust library for reading and writing OpenStreetMap **PBF** (Protocolbuffer Binary
Format) files.

## Features

- **Multiple readers** for different scenarios:
  - [`PbfReader`](https://docs.rs/pbf-craft/latest/pbf_craft/readers/struct.PbfReader.html) —
    sequential streaming reader, with parallel filtering
    ([`par_find`](https://docs.rs/pbf-craft/latest/pbf_craft/readers/struct.PbfReader.html#method.par_find))
    and byte progress reporting.
  - [`IterableReader`](https://docs.rs/pbf-craft/latest/pbf_craft/readers/struct.IterableReader.html) —
    iterator-based reader with [`ReaderProgress`](https://docs.rs/pbf-craft/latest/pbf_craft/readers/struct.ReaderProgress.html).
  - [`IndexedReader`](https://docs.rs/pbf-craft/latest/pbf_craft/readers/struct.IndexedReader.html) —
    random access by element id, backed by a `.pif` index file, with an in-memory blob cache
    and dependency resolution.
- **Dense and sparse** node encoding; reads `raw`, `zlib`, `lz4` and `zstd` blobs; writes
  `zlib`-compressed blobs.
- **Result-based error handling**: malformed or truncated input surfaces as errors, not
  panics.
- Pure Rust, no C dependencies.

## Usage

Add this to your `Cargo.toml`:

```toml
[dependencies]
pbf-craft = "1"
```

Reading a PBF file:

```rust
use pbf_craft::readers::PbfReader;

let mut reader = PbfReader::from_path("resources/andorra-latest.osm.pbf").unwrap();
reader.read(|header, element| {
    if let Some(header_reader) = header {
        // Process header
    }
    if let Some(element) = element {
        // Process element
    }
}).unwrap();
```

Finding an element using the index feature. `IndexedReader` creates an index file for the
PBF file, which allows you to quickly locate and retrieve an element when looking for it
using its ID. `IndexedReader` has a cache option, with which you can fetch an element with
its dependencies more efficiently.

```rust
use pbf_craft::models::ElementType;
use pbf_craft::readers::IndexedReader;

let mut indexed_reader = IndexedReader::from_path_with_cache("resources/andorra-latest.osm.pbf", 1000).unwrap();
let element_list = indexed_reader.get_with_deps(&ElementType::Way, 1055523837).unwrap();
```

Writing a PBF file:

```rust
use pbf_craft::models::{Element, Node};
use pbf_craft::writers::PbfWriter;

let mut writer = PbfWriter::from_path(std::env::temp_dir().join("output.osm.pbf"), true).unwrap();
writer.write(Element::Node(Node::default())).unwrap();
writer.finish().unwrap();
```

## Data format notes

- **Coordinates**: `Node`/`WayNode`/`Bound` coordinates are i64 **nanodegrees** (the raw
  PBF unit; divide by 1e9 for degrees).
- **Ordering**: the PBF format does not require sorted elements, but the conventional
  layout (all nodes by id, then all ways by id, then all relations by id) is assumed by
  `IndexedReader` and most other tools. `PbfWriter` stores elements in the order written —
  the caller is responsible for the order; `IndexedReader` rejects unordered files with an
  error when building its index.
- **Compression**: reading supports `raw`, `zlib`, `lz4` and `zstd` blobs; writing produces
  `zlib`-compressed blobs.
- **visible flag**: elements default to `visible = true` (per spec, the flag is assumed true
  when absent). Elements explicitly marked `visible = false` are written with the required
  `HistoricalInformation` feature declared in the header.
- **Error handling**: all fallible operations return `anyhow::Result`; malformed input
  surfaces as errors rather than panics.

## MSRV

Current stable Rust (1.70+). This crate is tested against the latest stable toolchain.

## License

MIT