regol 0.2.0

Independent GeoDesk GOL 2.0 reader and OSM PBF builder
Documentation

regol

Read GeoDesk GOL 2.0 files in Rust. Select OpenStreetMap features by tag and location, read their geometry, and traverse way nodes and relation members. The optional builder compiles OSM PBF snapshots into new GOL files.

Query a library

For the crates.io release, add regol = "0.2" to [dependencies]. From a source checkout, use cargo add --path /path/to/regol in your application.

use regol::{Library, Query, Result};

fn main() -> Result<()> {
    let path = std::env::args_os().nth(1)
        .unwrap_or_else(|| "tests/fixtures/basic.gol".into());
    let library = Library::open(path)?;
    let cafes = Query::parse("na[amenity=cafe]")?;
    let prepared = cafes.prepare(&library)?;
    for feature in prepared.iter() {
        let feature = feature?;
        println!("{}", feature.id());
    }
    Ok(())
}

Pass a GOL path as the first argument. The fallback uses the packaged sample, which prints N1. Preparing a query resolves tags against a specific library. Reuse the prepared query for iteration, bounded queries or counts. Iteration is lazy, so handle errors both when opening the file and when reading results. Feature::tags and Feature::coordinates stream values, while Feature::geometry constructs an owned geometry.

Library::open uses positioned reads. Library::new accepts borrowed bytes, owned bytes or a custom source::Source. Bounding-box queries use stored feature bounds and include boundary contact. For exact rectangle intersection use Geometry::intersects_bounds. Library::with_limits bounds work such as traversal, recursion and coordinate decoding.

With the http feature, source::HttpSource::open(url) opens an immutable GOL on an HTTP(S) server that supports byte ranges. Pass it to Library::with_dictionary_loading(source, Limits::default(), DictionaryLoading::OnDemand) for a lazy dictionary. Reuse the library across bounded queries to share connections and cached ranges. Direct HTTPS prefers HTTP/3 and falls back to pooled HTTP/1.1. HttpSource::protocol() reports the current selection. For bounded queries with uncached data, QueryExecutor can overlap range reads by running each tile through feature matching on the same worker. Use with_query for unordered results or try_fold_reduce to accumulate on the workers. PreparedQuery::in_bounds provides ordered traversal. A full scan can retain the entire object in memory. The opening 128 KiB read selects the range size for this handle. Use HttpSource::with_page_size(url, bytes) for a fixed size. To interrupt pending network requests from another thread, call library.source().cancel_requests(). This closes active QUIC streams and pooled TCP connections for every query sharing that source.

Spatial queries and feature sets

This example reads a building by its typed OSM ID and finds cafés that intersect its footprint, including cafés on the boundary.

use regol::{FeatureId, FeatureType, Library, Query, Result, SpatialFilter, SpatialPredicate};
use regol::units::area::hectare;

fn main() -> Result<()> {
    let library = Library::open("tests/fixtures/ids.gol")?;
    let all = library.feature_set();
    let boundary_id = FeatureId { kind: FeatureType::Way, id: 11 };
    if let Some(boundary) = all.get(boundary_id)? {
        let filter = SpatialFilter::from_feature(SpatialPredicate::Intersects, boundary)?;
        let cafes = all.select(Query::parse("na[amenity=cafe]")?).spatial(filter);
        for cafe in cafes.iter() {
            println!("{}", cafe?.id());
        }
        println!("Boundary area: {:.1} ha", boundary.area()?.get::<hectare>());
    }
    Ok(())
}

Use Query::prepare and PreparedQuery::spatial to reuse a tag query or a spatial filter across repeated searches. FeatureSet provides intersection, union, difference, membership tests and typed-ID lookup. A global ID lookup can scan the whole library. Use in_bounds when you know the approximate location. member_set, members_with_role, parent_set and connected_to support queries over OSM relationships. Use Feature::members for ordered relation members, including repetitions.

length, perimeter and distance return spherical lengths, and area returns spherical area. regol::units re-exports the standard uom quantities and unit modules. WithinDistance takes a Length, so a measured distance can be used directly as a threshold. centroid returns an integer Mercator Point. Point::lon_lat yields a LonLat with distinct longitude and latitude angles. Use Bounds::from_lon_lat to build a query window from two geographic corners. To verify stored checksums and traverse the active snapshot's feature data, call Library::check_integrity.

Cargo features

Feature Use
parallel (default) Use an explicit QueryExecutor pool for counts, iteration and reductions. Set default-features = false for a serial reader.
http Open URLs with HTTP/3 or pooled HTTP/1.1 range GETs using system trust roots. Linux builds use the system OpenSSL development package.
mmap Read from a memory-mapped file. The backing file must stay unmodified and untruncated for the lifetime of the mapping.
build Compile a raw or zlib-compressed OSM PBF snapshot with build::build_pbf using the pure-Rust multi-threaded pipeline (no C compiler or SQLite required).
way-checkpoints Index long ways for repeated vertex and original-node-ID lookups. Original IDs must be present in the GOL.
experimental-tag-sidecars Build and query auxiliary tag indexes on Unix. Requires mmap and immutable backing files.

The reader and builder require Rust 1.85 or later. The regol CLI (covering build, query, info, and check) is distributed separately as regol-cli (cargo install --locked regol-cli). The builder stages and encodes objects in parallel in memory and atomically publishes the finished GOL file beside the destination.

Licensed under Apache-2.0. API reference · Project homepage