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
| 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
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
uomSI system withf64storage. 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.
- Feature
Id - An OSM identifier qualified by object type. Display uses forms such as
N1. - Feature
Links - Bounded lazy traversal of a feature-reference table. Shared decoding handles forward parent tables and backward way-node tables.
- Feature
Set - 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::membersto retain original member order and repetitions. - Features
- Streaming spatial traversal. Uses memory proportional to tree depth, not result count. An error terminates the iterator.
- Integrity
Report - 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.
- Original
WayNode Ids - Iterator over the stored original node IDs of a way.
- Parent
Ways - 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.
- Prepared
Query - 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.
- Query
Executor - Reusable query workers with bounded, unordered result delivery.
- Query
Iter - Streaming results of
Library::selectorLibrary::select_in. - Query
Results - Lazy unordered results, scoped to a
QueryExecutor::with_querycall. The second lifetime covers the prepared query and scoped worker launcher. - Selector
- A category mask and a conjunction of tag predicates.
- Spatial
Filter - 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.
- WayCheckpoint
Index - 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§
- Dictionary
Loading - When to read and validate the global string dictionary.
- Error
- An I/O, format, query or resource-limit error returned by the reader.
- Feature
Type - The underlying OSM object type. Area classification is available via
Feature::is_area. - Geometry
- Explicitly owned geometry. Streaming coordinates/members avoid these allocations.
- Spatial
Predicate - 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.