osrm-binding

Rust bindings for OSRM (Open Source Routing Machine), providing an idiomatic and type-safe interface to access core OSRM functionalities (route, table, trip) from Rust.

🚀 Features

• 🗺️ Calculate routes, trips, and distance/duration tables using OSRM
• 🦀 Fully written in Rust
• 💡 Simple and safe API for high-performance routing
• 🧪 Includes integration tests for route and table APIs

📦 Installation

Add the crate to your Cargo.toml:

cargo add osrm-binding

Building Dependencies

This library requires OSRM to be built and linked. Below are instructions for setting up the dependencies.

Local Installation (Ubuntu 24.04)

Install the required system dependencies:

sudo apt update
sudo apt install build-essential git cmake pkg-config \
                libbz2-dev libxml2-dev libzip-dev libboost-all-dev \
                lua5.2 liblua5.2-dev libtbb-dev libfmt-dev

Dockerfile

Use the following Dockerfile to build your application in a containerized environment:

FROM rust:1.88.0-bookworm AS builder

WORKDIR /usr/src/app
COPY Cargo.toml Cargo.lock ./
COPY ./src ./src

RUN apt-get update && \
    apt-get -y --no-install-recommends --no-install-suggests install \
        ca-certificates \
        cmake \
        g++ \
        gcc \
        git \
        libboost1.81-all-dev \
        libbz2-dev \
        liblua5.4-dev \
        libtbb-dev \
        libxml2-dev \
        libzip-dev \
        lua5.4 \
        make \
        pkg-config \
        libfmt-dev

RUN ls -la /usr/lib/x86_64-linux-gnu/libboost_thread*

RUN cargo build --release -vv

FROM debian:bookworm-slim

WORKDIR /usr/src/app
COPY --from=builder /usr/src/app/target/release/my-bin ./

RUN apt-get update && \
    apt-get install -y --no-install-recommends --no-install-suggests \
        expat \
        libboost-date-time1.81.0 \
        libboost-iostreams1.81.0 \
        libboost-program-options1.81.0 \
        libboost-thread1.81.0 \
        liblua5.4-0 \
        libtbb12 && \
        rm -rf /var/lib/apt/lists/* && \
        ldconfig /usr/local/lib

CMD ["./my-bin"]

Note: Replace my-bin with your actual binary name. This Dockerfile installs OSRM build dependencies and runtime libraries.

🛠️ Usage

Initialization

Initialize the OSRM engine with a preprocessed OSRM data file (e.g., generated via osrm-extract and osrm-contract):

use osrm_binding::{OsrmEngine, Algorithm};

let engine = OsrmEngine::new("/path/to/france-latest.osrm", Algorithm::MLD)
    .expect("Failed to initialize OSRM engine");

Route Calculation

Build and execute a route request:

use osrm_binding::{RouteRequestBuilder, Point};

let request = RouteRequestBuilder::default()
    .points(vec![
        Point { longitude: 2.3522, latitude: 48.8566 }, // Paris
        Point { longitude: 5.3698, latitude: 43.2965 }, // Marseille
    ])
    .build()
    .unwrap();

let result = engine.route(&request).unwrap();
println!("{:?}", result.routes.first().unwrap());

Table (Distance/Duration Matrix)

Compute a distance/duration table:

use osrm_binding::{TableRequest, Point};

let request = TableRequest {
    sources: vec![Point { longitude: 2.3522, latitude: 48.8566 }],
    destinations: vec![
        Point { longitude: 5.3698, latitude: 43.2965 },
        Point { longitude: 4.8357, latitude: 45.7640 },
    ],
};

let response = engine.table(&request).unwrap();
println!("{:?}", response.durations);

Simple Route

For quick single-origin to single-destination routing:

use osrm_binding::Point;

let result = engine.simple_route(
    Point { longitude: 2.3522, latitude: 48.8566 },
    Point { longitude: 5.3698, latitude: 43.2965 },
).unwrap();

println!("Duration: {}s, Distance: {}m", result.duration, result.distance);

Trip API

Optimize a trip with multiple waypoints:

use osrm_binding::{TripRequest, Point};

let request = TripRequest {
    points: vec![
        Point { longitude: 2.3522, latitude: 48.8566 },
        Point { longitude: 4.8357, latitude: 45.7640 },
        Point { longitude: 5.3698, latitude: 43.2965 },
    ],
};

let trip = engine.trip(&request).unwrap();
println!("{:?}", trip);

🔬 Tests

To run the tests, set the environment variable for your OSRM data file and execute:

export OSRM_TEST_DATA_PATH="/absolute/path/to/france-latest.osrm"
cargo test

Ensure your .osrm file is prepared using osrm-extract and osrm-contract.

🚀 Performance

Native performance using cargo bench

calculate_multiple_routes_around_paris_10km_mld
                        time:   [5.4872 ms 5.6545 ms 5.8246 ms]

calculate_multiple_routes_around_paris_100km_mld
                        time:   [13.063 ms 13.877 ms 14.652 ms]
Found 2 outliers among 100 measurements (2.00%)
  2 (2.00%) low mild

calculate_multiple_routes_around_paris_10km_ch
                        time:   [3.8034 ms 3.8599 ms 3.9175 ms]
Found 1 outliers among 100 measurements (1.00%)
  1 (1.00%) high mild

calculate_multiple_routes_around_paris_100km_ch
                        time:   [5.9891 ms 6.2444 ms 6.4946 ms]
Found 1 outliers among 100 measurements (1.00%)
  1 (1.00%) low mild

📖 License

This project is licensed under the MIT License.

✨ Contributions

Contributions are welcome! Feel free to open issues or pull requests to improve performance, add more OSRM API bindings, or enhance usability.

Made with ❤️ in Rust.