Single-file GOL 2.0
Reorganizes .osm.pbf snapshots into zoom-pyramid tiles, tag categories, and Hilbert-ordered R-trees so queries read only overlapping branches.
regol is an independent, pure-Rust GeoDesk GOL 2.0 reader, spatial query engine, and OSM PBF compiler—built for country- and continent-scale lookups with no C, SQLite, or native GeoDesk dependencies.
# Build a GOL 2.0 file from OpenStreetMap PBF
$ regol build region.osm.pbf region.gol
# Query cafés in a GeoJSON polygon as GeoJSONL
$ regol query region.gol 'na[amenity=cafe]' \
--area district.geojson \
-f geojsonl > cafes.geojsonl
# Export roads in a bounding box to CSV
$ regol query region.gol 'w[highway]' \
--bbox=-0.14,51.49,-0.10,51.52 \
-f csv --keys id,name,highway
use regol::{Library, Query, Result};
fn main() -> Result<()> {
let library = Library::open("region.gol")?;
let cafes = Query::parse("na[amenity=cafe]")?
.prepare(&library)?;
println!("Total cafés: {}", cafes.count()?);
for feature in cafes.iter() {
let feature = feature?;
if let Some(name) = feature.tag("name")? {
println!("{}: {}", feature.id(), name);
}
}
Ok(())
}
Reorganizes .osm.pbf snapshots into zoom-pyramid tiles, tag categories, and Hilbert-ordered R-trees so queries read only overlapping branches.
Zero C toolchains, SQLite staging databases, or external GeoDesk runtimes. Enforces #![forbid(unsafe_code)] when mmap is not enabled.
Embed regol inside Rust applications or use regol-cli to build, inspect, verify CRC32C checksums, query, and export GIS and OSM formats.
Generic over positioned byte reads (Source): run on local disks, bounded caches, immutable memory maps, or custom HTTP/object-storage backends.
regol build compiles raw or zlib-compressed .osm.pbf snapshots in parallel in memory and atomically publishes the finished .gol file—ready for local queries or remote range-read serving.
--preset vector-tiles for S3 range reads and --preset compact for smaller metadata headers.--target-tile-kib), even zoom steps (--even-zooms), border duplication, and per-tile R-tree fanout.build Cargo feature to compile GOLs straight from Rust via regol::build.Prepare a GeoDesk Query Language (GOQL) selector once to resolve tag dictionary codes and category bitmasks, then reuse it across bounding boxes, spatial filters, parallel counts, and zero-allocation streaming scans.
Intersects, Within, Contains, CoveredBy, Touches, Overlaps, Crosses, Disjoint, and WithinDistance.FeatureSets with and, or, without, and traverse member_set, parent_set, and connected_to.uom SI quantities.
regol-cli bundles build, info, check, and query into one standalone binary. Queries memory-map immutable files, load the string dictionary on demand, and encode large exports in parallel while preserving query order.
Export matching features as count, ids, geojson, geojsonl, wkt, csv, xml, or pbf—with GeoJSON antimeridian splitting, polar cap closure, configurable coordinate precision, custom CSV columns, and --complete-relations for self-contained PBF extracts.
# Inspect metadata, indexed keys, and tile counts
$ regol info region.gol
# Verify CRC32C checksums, R-tree bounds, and links
$ regol check region.gol
# Extract a PBF slice for a bounding box
$ regol query region.gol 'w[highway]' \
--bbox=-0.14,51.49,-0.10,51.52 \
-f pbf > roads.osm.pbf
# Export building areas inside a GeoJSON polygon
$ regol query region.gol 'a[building]' \
--area boundary.geojson \
-f geojson > buildings.geojson
Cross-engine benchmarks comparing regol on regional OpenStreetMap extracts are maintained in gol-bench. Placeholder figures below will be replaced with reproducible runs before release.
| Workload | regol | Reference | Notes |
|---|---|---|---|
| PBF → GOL build | TBD |
TBD |
Great Britain .osm.pbf, multi-threaded build |
| GOL file size | TBD |
TBD |
Default layout (16 MiB target tiles) |
| Full-region tag count | TBD |
TBD |
na[amenity=cafe], warm mmap, parallel count |
| Bbox query & GeoJSON export | TBD |
TBD |
w[highway], parallel ordered encoding |
| Polygon spatial filter | TBD |
TBD |
a[building] with --area GeoJSON boundary |
Placeholder table — hardware specs, dataset snapshot dates, exact CLI flags, and median timings across runs will be published alongside the benchmark scripts.
Requires Rust 1.85 or later. Install the standalone command-line tool or add the regol library to your Cargo project.
The regol-cli crate provides the regol binary with build, info, check, and query.
cargo install --locked regol-cli
regol build region.osm.pbf region.gol
regol query region.gol 'na[amenity=cafe]'
Optional Cargo features: parallel (default), mmap, build, and way-checkpoints.
[dependencies]
regol = "0.2"
# Optional PBF builder & mmap features:
# regol = { version = "0.2",
# features = ["mmap", "build"] }
regol is licensed under the Apache License, Version 2.0. Explore the full API documentation, cargo feature matrix, and GOL 2.0 format compatibility notes.