osmnxr_core/lib.rs
1//! Street-network graph algorithms for OpenStreetMap-style networks.
2//!
3//! `osmnxr-core` is the compute core of the R package
4//! [osmnxr](https://strategicprojects.github.io/osmnxr/) (OSMnx for R). It
5//! holds the graph math and nothing else: no I/O, no geometry types, no
6//! coordinate reference systems. A caller hands it edge lists of 0-based node
7//! indices with weights, and gets back node paths, edge indices, distances
8//! and scores. The crate has no dependencies.
9//!
10//! # Modules
11//!
12//! - [`graph`]: a compressed-sparse-row (CSR) directed graph built from
13//! parallel `from`/`to`/`weight` vectors.
14//! - [`routing`]: Dijkstra, shortest paths that report the edges traversed
15//! (parallel edges included), Yen's k shortest paths, distance matrices, a
16//! travelling-salesman heuristic, the Pareto front of bicriteria paths
17//! (Martins' label-setting, exact constrained shortest paths) and the LARAC
18//! Lagrangian relaxation for large graphs.
19//! - [`centrality`]: betweenness (Brandes) and closeness.
20//! - [`metrics`]: basic network statistics, compass bearings and the
21//! orientation entropy of a street grid.
22//! - [`simplify`]: topology simplification (chains of degree-2 nodes between
23//! endpoints) and connected components.
24//! - [`spatial`]: grid-indexed snapping of points to the nearest polyline.
25//!
26//! # Conventions
27//!
28//! Nodes are `0 .. n_nodes`; edges are directed, so a two-way street is two
29//! edges. Weights must be nonnegative and finite. Functions that return edges
30//! give indices into the caller's input order, so attributes and geometry can
31//! be recovered exactly. Unreachable targets are `f64::INFINITY` distances,
32//! empty paths or `None`, never a made-up value.
33//!
34//! # Example
35//!
36//! ```
37//! use osmnxr_core::graph::Graph;
38//! use osmnxr_core::routing::{dijkstra, shortest_path_route};
39//!
40//! // a square 0 -> 1 -> 2 -> 3 -> 0 with a diagonal 0 -> 2
41//! let from = [0, 1, 2, 3, 0];
42//! let to = [1, 2, 3, 0, 2];
43//! let weight = [1.0, 1.0, 1.0, 1.0, 1.5];
44//! let g = Graph::from_edges(&from, &to, &weight, 4);
45//!
46//! let dist = dijkstra(&g, 0);
47//! assert_eq!(dist, vec![0.0, 1.0, 1.5, 2.5]);
48//!
49//! let (path, _slots, cost) = shortest_path_route(&g, 0, 3).unwrap();
50//! assert_eq!(path, vec![0, 2, 3]);
51//! assert_eq!(cost, 2.5);
52//! ```
53
54pub mod centrality;
55pub mod graph;
56pub mod metrics;
57pub mod routing;
58pub mod simplify;
59pub mod spatial;
60
61pub use graph::Graph;