C++-to-Rust bindings for Valhalla Routing Engine, powered by cxx.
valhalla-rs provides drop-in infrastructure (cargo add valhalla and you're ready) for utility projects that need to access Valhalla's road graph data, expose additional Valhalla functionality, or benefit from calling Valhalla's routing engine in-process.
valhalla-debug demonstrates this use case.
Features:
- Tile access: Read Valhalla tiles and access road graph edges (
DirectedEdge,EdgeInfo) and nodes (NodeInfo) - see tiles_tests for examples - Live traffic: Write live traffic information directly to memory-mapped traffic.tar - see tiles_tests for examples
- Actor API: Route building and routing operations similar to Valhalla's Python bindings - see actor_tests for examples
TODOs:
- Logging: Redirect Valhalla logging to Rust's
tracingcrate or provide an interface for redirecting it to a custom logger. - Reading individual tile files: Support reading info from Valhalla tiles from
tile_dir(individual file per tile). Currently onlytile_extract(single tiles.tar file) is supported. - Historical traffic: All minor functionality for out-of-the-box historical traffic support. Currently minor stuff should be done manually, such as converting
GraphIdto the tile file name or writing historical speeds (free flow, congested, 5m bins) to the csv files.
Design choices:
valhalla::GraphReaderis intended to be as simple as possible and hold no mutable inner state, leaving the caching and other optimizations to the caller. This allows for easy reuse of the sameGraphReaderinstance across multiple threads.valhalla::Actoraccepts onlyproto::Optionsand notproto::Apior Valhalla JSON request to have small strongly-typed API. Still, there is a convenience method to convert JSON intoproto::Optionscalledvalhalla::Actor::parse_json_request().valhalla::EdgeInfo::shapedirection is aligned with the edge direction. For comparison, in C++ Valhalla user should revert the shape based onDirectedEdge::forwardflag (so both forward and reverse edges can use the sameEdgeInfo). Because of how C++-to-Rust bindings work, additional allocation is required any way, so it was simpler to just always return the shape in the correct direction.
Run cargo add valhalla or add this to your Cargo.toml:
[dependencies]
valhalla = "0.6"Since Valhalla heavily relies on system libraries, you need to install the following dependencies to build this project:
sudo apt-get update && sudo apt-get install -y --no-install-recommends clang pkg-config build-essential cmake libboost-dev liblz4-dev libprotobuf-dev protobuf-compiler zlib1g-devSee the Dockerfile for a complete reference setup, or the Valhalla documentation for other platforms.
This project provides Rust bindings for the Valhalla routing engine and distributes (via crates.io) the Valhalla source code. The entire project is licensed under the MIT License.
The original Valhalla license is available at valhalla/COPYING.