OpenTrace ML

OpenTrace ML is a pre-alpha Python and Go project for building road-intelligence applications from computer-vision detections, incremental traffic forecasts, and privacy-aware map signals.

The project provides small, model-independent building blocks rather than a hosted routing service. Applications can adopt one component without coupling their detector, forecasting model, map matcher, or routing engine to the rest of the stack.

OpenTrace ML does not yet ship a trained detector, live API, routing service, web application, third-party dataset, or production map-matcher integration. These are staged in the roadmap.

flowchart TD
    V["Vision detections"] --> E["Shared road events"]
    T["Traffic observations"] --> F["Incremental forecasts"]
    G["Consented GPS"] --> P["Private trace preparation"]
    P --> M["Map-matcher contract"]
    E --> R["GeoJSON and route scores"]
    F --> R
    M --> R

Raw coordinates remain inside the private trace-processing boundary. Public outputs should be thresholded aggregates that have passed documented human review; OpenTrace never treats one unmatched trace as a missing road.

OpenTrace ML supports Python 3.10, 3.11, and 3.12.

git clone https://github.com/vrajpatell/opentrace-ml.git
cd opentrace-ml
python -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'

Install optional public-data and OpenStreetMap integrations only when needed:

pip install -e '.[data,geo]'

The native Go module supports Go 1.26 and 1.27:

go get github.com/vrajpatell/opentrace-ml/go

See the Go quick start and performance contracts. Python remains the training and data-science surface; Go is the dependency-light execution surface.

The repository fixtures are original, tiny, and require no dataset download or network service.

# Convert a sample road-damage annotation into a GeoJSON survey layer.
python examples/road_damage_route_demo.py tests/fixtures/rdd_sample.xml

# Exercise the map-matcher contract with a synthetic GPX fixture.
OPENTRACE_PSEUDONYM_KEY='replace-with-a-secret' \
  python examples/map_match_fixture.py

# Compare four traffic models on original synthetic data, entirely offline.
python examples/benchmark_traffic_models.py --synthetic-demo

# Run the complete test suite.
python -m pytest -q

# Run the native Go core, race tests, and example.
(cd go && go test -race ./... && go run ./examples/basic)

Evaluate each road-damage label separately while preserving frame and IoU matching:

from opentrace_ml import per_class_detection_metrics

report = per_class_detection_metrics(ground_truth, predictions, iou_threshold=0.5)
pothole_f1 = report["pothole"].f1
json_ready = report.as_dict()

Labels that appear only in predictions or only in ground truth are included in the report, making false positives and missed damage classes visible.

Train a small multilayer perceptron on your own regular traffic series:

import pandas as pd
from opentrace_ml import NeuralTrafficForecaster
from opentrace_ml.datasets import select_hourly_traffic_window

frame = select_hourly_traffic_window(pd.read_csv("traffic.csv"), samples=720)
model = NeuralTrafficForecaster(lags=24, random_state=42).fit_frame(frame)
forecast = model.forecast(
    frame["date_time"].iloc[-1] + pd.Timedelta(hours=1), periods=24
)

The network uses past traffic and calendar features, with input and target scaling learned only from training examples. It runs on CPU using the existing scikit-learn dependency. Fit it again to learn new observations; use OnlineTrafficForecaster when incremental updates are needed.

Compare it with persistence, a daily seasonal baseline, and the online linear model before deciding whether it helps your application:

pip install -e '.[data]'
python examples/benchmark_traffic_models.py --uci
# Or use an already downloaded CSV (plain or gzip-compressed).
python examples/benchmark_traffic_models.py --csv /path/to/traffic.csv.gz

The JSON report includes aggregate and lead-time errors, training warnings, data-window selection, seed, and dependency versions. Forecast evaluation rejects duplicate timestamps and gaps; the hourly window helper collapses only agreeing duplicate readings and never fills gaps. Neural forecasts are experimental point estimates, with no calibrated uncertainty or Go export yet. See the neural forecasting guide for the evaluation protocol, compatibility changes, and contribution ideas.

from opentrace_ml import GeoPoint, detections_to_geojson, geolocate_detections
from opentrace_ml.vision import parse_pascal_voc

detections = parse_pascal_voc("India_000001.xml", timestamp_seconds=5.0)
trace = [
    GeoPoint(22.3072, 73.1812, 0.0),
    GeoPoint(22.3080, 73.1830, 10.0),
]

located = geolocate_detections(detections, trace)
geojson = detections_to_geojson(located)

The Python traffic forecaster can export a data-only model snapshot. Go loads the scaler, learned coefficients, intercept, and lag history without Python or CGo. Prediction is O(lags); recursive forecasting is O(horizon × lags).

python examples/export_traffic_model.py --synthetic-demo --output /tmp/opentrace-traffic.json
(cd go && go run ./examples/forecast /tmp/opentrace-traffic.json \
  2026-09-04T00:00:00Z 2026-09-04T01:00:00Z)

See portable traffic inference for the Python and Go APIs, timestamp/cadence rules, benchmarks, and numerical parity tests.

Trace preparation requires explicit consent, replaces the raw trip identifier with an HMAC pseudonym, removes exact duplicate samples and implausible speed jumps, and normalizes timestamps. Never use a hardware device ID as trip_id.

import os

from opentrace_ml import load_gpx_points, prepare_trace

points = load_gpx_points("trip.gpx")
trace = prepare_trace(
    points,
    trip_id="export-123",
    secret_key=os.environ["OPENTRACE_PSEUDONYM_KEY"],
    consent_granted=True,
)

trace.points still contains sensitive coordinates. Keep it inside the private pipeline and publish only reviewed, aggregated outputs. Read the privacy-safe trace stage and map-matching stage before integrating real traces.

For deployment guidance on pseudonym key rotation, compromise response, and trace-data retention, see Privacy and key management.

These examples require the corresponding optional dependency or a user-provided dataset download:

# Download the CC BY 4.0 UCI dataset and forecast 24 hours.
python examples/forecast_uci.py

# Read an already downloaded and extracted RDD2022 directory.
python examples/rdd_annotations.py /path/to/RDD2022

# Download an OSM driving graph and print its size.
python examples/osm_graph.py

# Backtest the traffic forecaster on public UCI data.
python examples/traffic_backtest.py

New contributors can start with one bounded issue:

If you are unsure where to begin, introduce yourself in GitHub Discussions with your interests in Python, ML, computer vision, GIS, routing, privacy, testing, or documentation. You can also comment on an issue before starting work.

1. Read CONTRIBUTING.md and DATA_LICENSES.md.
2. Fork the repository and create a focused branch.
3. Add tests for externally visible behavior.
4. Run ruff check . and python -m pytest -q.
5. Open a pull request describing the behavior and data/licensing impact.

Do not commit datasets, private GPS traces, credentials, or model weights.

Dataset files are downloaded by the user and remain under their original licences. See DATA_LICENSES.md before downloading, redistributing, or publishing derived data.

RDD2022-derived detections are application-layer signals, not an authorized source for editing OpenStreetMap. OpenTrace does not upload them to OSM.

See the architecture notes, current-stage use cases, and roadmap for the design boundaries and planned integrations.

Version 0.1.0 is pre-alpha. APIs may change while the first reproducible computer-vision, forecasting, and route-intelligence integrations are developed.

OpenTrace ML source code is licensed under the Apache License 2.0.

External datasets, map data, model weights, and generated derivative databases are not covered by Apache-2.0. Each resource remains subject to its original licence and attribution requirements. See DATA_LICENSES.md.