Skip to main content

Crate regol

Crate regol 

Source
Expand description

§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

FeatureUse
parallel (default)Use an explicit QueryExecutor pool for counts, iteration and reductions. Set default-features = false for a serial reader.
httpOpen URLs with HTTP/3 or pooled HTTP/1.1 range GETs using system trust roots. Linux builds use the system OpenSSL development package.
mmapRead from a memory-mapped file. The backing file must stay unmodified and untruncated for the lifetime of the mapping.
buildCompile 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-checkpointsIndex long ways for repeated vertex and original-node-ID lookups. Original IDs must be present in the GOL.
experimental-tag-sidecarsBuild 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

Modules§

build
Compile an OSM PBF snapshot into a new GOL 2.0 library.
source
Storage backends for crate::Library. Choose storage when opening a file.
tag_sidecar
Experimental mmap sidecars for immutable GOL files on Unix.
units
Physical measurements use the standard uom SI system with f64 storage. Use the unit modules here to construct a quantity or obtain a value for display.

Structs§

Bounds
An axis-aligned, inclusive rectangle in integer Mercator coordinates.
Coordinates
Fallible iterator over the integer Mercator vertices of a way.
Feature
A small borrowed handle. Does not allocate or retain decoded geometry/tags.
FeatureId
An OSM identifier qualified by object type. Display uses forms such as N1.
FeatureLinks
Bounded lazy traversal of a feature-reference table. Shared decoding handles forward parent tables and backward way-node tables.
FeatureSet
A reusable selection from one open library. Set operations combine conditions and iteration visits candidates once, without materializing the result. Member and parent sets retain handles to their direct targets, keyed by typed OSM ID. Set order is unspecified. Use Feature::members to retain original member order and repetitions.
Features
Streaming spatial traversal. Uses memory proportional to tree depth, not result count. An error terminates the iterator.
IntegrityReport
Counts observed after a complete, successful check of the active snapshot.
Latitude
Latitude north of the equator, from −90° through +90° inclusive.
Library
A GOL file with its string dictionary and spatial indexes. Features borrow this library.
Limits
Resource ceilings for untrusted files. Iterators fail rather than silently truncate when a limit is reached. Defaults can be adjusted for large data.
LonLat
Geographic coordinates with distinct, validated axes.
Longitude
Longitude east of Greenwich, from −180° through +180° inclusive.
Member
A feature referenced by a relation, together with its role.
Members
Fallible iterator over relation members in stored order.
OriginalWayNodeIds
Iterator over the stored original node IDs of a way.
ParentWays
Fallible iterator over ways containing the requested vertex.
Point
Integer Mercator coordinates used by GOL, without lossy projection.
Polygon
An exterior ring followed by zero or more interior rings. Rings are closed; their input orientation is preserved. Coordinates remain integer Mercator.
Predicate
A GOQL tag condition for a programmatically constructed selector.
PreparedQuery
A reusable query bound to a particular library’s string codes and indexes.
Properties
Library metadata as lazy UTF-8 key/value pairs.
Query
Reusable GOQL selectors. Compilation allocates and evaluation streams.
QueryExecutor
Reusable query workers with bounded, unordered result delivery.
QueryIter
Streaming results of Library::select or Library::select_in.
QueryResults
Lazy unordered results, scoped to a QueryExecutor::with_query call. The second lifetime covers the prepared query and scoped worker launcher.
Selector
A category mask and a conjunction of tag predicates.
SpatialFilter
A reusable exact spatial predicate against one geometry or feature.
Tag
A decoded OSM tag.
Tags
Fallible iterator over a feature’s tag table.
Types
GOQL categories: area ways/relations belong to AREA, not WAY/RELATION.
WayCheckpointIndex
Optional restart points for a single immutable GOL with original node IDs.
WayNode
A vertex in a way, with its original node ID when recoverable.
WayNodes
Fallible iterator over a way’s vertices in geometry order.

Enums§

DictionaryLoading
When to read and validate the global string dictionary.
Error
An I/O, format, query or resource-limit error returned by the reader.
FeatureType
The underlying OSM object type. Area classification is available via Feature::is_area.
Geometry
Explicitly owned geometry. Streaming coordinates/members avoid these allocations.
SpatialPredicate
The relationship required of each candidate relative to the filter operand.
TagValue
Numeric tags stay numeric without allocating a temporary decimal string. Display preserves the encoded decimal scale.

Type Aliases§

Result
A result from reading, querying or decoding a GOL.