par_osm_rust/lib.rs
1//! Shared OpenStreetMap-compatible fetch, cache, parse, and normalization utilities.
2//!
3//! `par-osm-rust` is the data-source crate used by `osm-to-bedrock` and
4//! `osm-world`. It owns network and cache concerns only: OSM/Overpass fetching,
5//! optional Overture Maps fetching, source merge policy, raw cache management,
6//! OSM XML/PBF parsing, SRTM tile downloads, and HGT elevation lookup. It
7//! intentionally does not depend on Minecraft, WGPU, UI frameworks, renderer
8//! types, or application UI state.
9//!
10//! # High-level source orchestration
11//!
12//! Use [`sources::fetch_map_data`] when an application wants one shared path for
13//! OSM/Overpass plus optional Overture Maps data:
14//!
15//! ```no_run
16//! use par_osm_rust::filter::FeatureFilter;
17//! use par_osm_rust::overture::{OvertureParams, OvertureTheme};
18//! use par_osm_rust::sources::{
19//! fetch_map_data, OvertureFailureMode, PoiSourceMode, SourceOptions,
20//! };
21//!
22//! # fn main() -> anyhow::Result<()> {
23//! let bbox = (38.0, -121.0, 38.01, -120.99); // south, west, north, east
24//! let options = SourceOptions {
25//! filter: FeatureFilter::default(),
26//! overpass_url: None,
27//! use_overpass_cache: true,
28//! overture: OvertureParams {
29//! enabled: true,
30//! themes: vec![OvertureTheme::Place],
31//! ..OvertureParams::default()
32//! },
33//! poi_source_mode: PoiSourceMode::OverturePreferred,
34//! overture_failure_mode: OvertureFailureMode::FallbackToOsm,
35//! };
36//! let mut progress = |_: f32, _: &str| {};
37//! let result = fetch_map_data(bbox, &options, &mut progress)?;
38//! println!("source status: {:?}", result.status);
39//! # Ok(())
40//! # }
41//! ```
42//!
43//! Important: [`sources::PoiSourceMode::OverturePreferred`] is the default POI
44//! policy, but Overture is fetched only when [`overture::OvertureParams::enabled`]
45//! is `true`. Default [`sources::SourceOptions`] performs an OSM/Overpass fetch
46//! only.
47//!
48//! # Lower-level modules
49//!
50//! - [`overpass`] builds safe Overpass QL queries and fetches raw OSM XML.
51//! - [`osm_cache`] stores URL-aware raw Overpass XML cache entries.
52//! - [`overture`] invokes the optional `overturemaps` CLI and normalizes GeoJSON.
53//! - [`sources`] merges OSM and Overture data with POI source policy and fallback.
54//! - [`osm`] parses PBF/XML and writes normalized OSM XML.
55//! - [`srtm`] and [`elevation`] download/read HGT elevation data.
56//! - [`cache`] resolves shared cache directories and migrates legacy caches.
57
58pub mod cache;
59pub mod elevation;
60pub mod filter;
61pub mod osm;
62pub mod osm_cache;
63pub mod overpass;
64pub mod overture;
65pub mod sources;
66pub mod srtm;