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 ;
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 ;
use hectare;
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