RoadRisk Vision

RoadRisk Vision is a privacy-first, post-drive dashcam analyzer. Record a trip with a phone, transfer the video to a PC, then create an annotated video and a versioned dataset of road-risk events. It combines HybridNets road perception, YOLOX object detection, object tracking, optional camera calibration and optional GPS telemetry.

Important

RoadRisk Vision is a research and driver-awareness tool. It does not control a vehicle, replace an attentive driver, or provide certified collision alerts.

What this fork adds

The upstream HybridNets repository supplies the preserved road and lane perception baseline. The RoadRisk Vision layer developed in this fork adds:

• a bounded, offline pipeline for normalizing and analyzing phone videos;
• YOLOX road-user detection, tracking, calibration and optional GPS telemetry;
• evidence-gated risk events, exposure-normalized telematics features and versioned JSON/CSV artifacts;
• a Typer CLI and local Streamlit dashboard for calibration, execution and post-drive review;
• hermetic tests, licensed synthetic fixtures, model checksum locking and a reproducible hardware benchmark.

This distinction matters: the fork extends an existing perception model into a local analysis product; it does not claim authorship of HybridNets itself.

Project ownership

Amine Manai initiated the RoadRisk Vision fork and implemented its post-drive architecture, perception integration, telemetry, tracking and risk pipeline, CLI and dashboard, privacy contracts, actuarial exports, and release benchmark. Later community contributions added hermetic CLI tests, exported JSON schemas, and lens-distortion calibration. HybridNets remains upstream work, as credited below.

What it produces

• Silent annotated H.264 video with lanes, objects and advisory warning states.
• events.jsonl with reproducible event identifiers and evidence.
• trip_summary.json and a flattened trip_summary.csv.
• timeline.json for the local dashboard.
• manifest.json with configuration, model provenance and run status.

Quick start

Python 3.11 and FFmpeg are required. The default test backend works without downloading AI weights; real model weights are downloaded explicitly.

py -3.11 -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev,dashboard]"
roadrisk doctor
roadrisk models download
roadrisk analyze trip.mp4 --backend mock
roadrisk dashboard

roadrisk doctor is read-only. It distinguishes missing and unsupported FFmpeg installations and prints tested platform-specific setup guidance.

For real inference, install the inference extras and follow docs/models.md. RoadRisk Vision never downloads weights during analysis.

Architecture

phone video + optional telemetry + optional calibration
                         |
                  FFmpeg normalization
                         |
                 bounded frame stream
                         |
          HybridNets D3 -> YOLOX-S -> tracking
                         |
               geometry and risk engine
                         |
      annotated video + timeline + research exports

The GPU stages run sequentially to target GPUs with 4 GB VRAM. Numeric distance and TTC are omitted unless the camera is calibrated and the estimate is stable.

Project status

Version v0.1.0 provides the complete PC post-drive workflow: phone-video normalization, HybridNets + YOLOX-S perception, two-stage ByteTrack association, optional calibration and telemetry, annotated video, dashboard review and versioned research exports. The RTX 2050 release benchmark processed all 300 frames of the licensed 1080p/30 fixture in 4.94x source duration while remaining inside every memory/performance gate. See the full reproducible result and roadmap.

Contributing

Contributions are welcome. Start with CONTRIBUTING.md, the documentation index, and issues labelled good first issue. Never commit private driving footage, GPS traces, credentials, model weights or generated run directories.

Upstream and licenses

RoadRisk Vision is a fork of datvuthanh/HybridNets, preserved at tag baseline/upstream-8735a699. HybridNets is MIT licensed. The optional YOLOX integration is based on Megvii YOLOX and remains subject to its Apache-2.0 license. See NOTICE.

Actuarial relevance

The project exports exposure and driving-risk features: analyzed duration, valid distance, event counts, severity and exposure-normalized rates. It does not estimate premiums, claim frequency or claim severity. Events are called risk_events; the term near miss is reserved for an explicitly defined, measurable low-TTC event.

Generate a portfolio-style research summary with roadrisk exposure-report. See the actuarial telematics guide for the exact boundary between driving features and genuine actuarial claims modelling.