Try the live demo · runs entirely in your browser, nothing uploaded
Rakshak (रक्षक, "protector") tells an accident scene apart from ordinary traffic. It trains in minutes on a laptop CPU from a few hundred labelled photos, and exports to a ~6 MB ONNX model that runs in Python, on the edge, or directly in a web page.
git clone https://github.com/4ryanwalia/Rakshak---Car.git && cd Rakshak---Car
pip install -e ".[onnx]"
rakshak predict dashcam_frame.jpg # a trained checkpoint ships with the repo image verdict confidence
--------------------------------------------------------------------------
dashcam_frame.jpg Accident 98.3%
1 of 1 images flagged as accidents
- Why this exists
- Quickstart
- Results
- How it works
- Command line
- Python API
- Deploying the model
- Using your own data
- Project layout
- Limitations
- Roadmap
- Contributing
- Support the project
Automatic crash detection shortens the gap between a collision and the ambulance arriving, and that gap is measured in lives. There is plenty of published research on it and very little you can actually run.
Rakshak is the small, honest version: a real package, a real test suite, and a model you can execute in your browser before you decide whether to clone anything.
| Trains on CPU | Two-phase transfer learning on a frozen ImageNet backbone. No GPU, no cloud account. |
| Small model | MobileNetV3-Small by default — about 6 MB as ONNX, tens of milliseconds per image. |
| Honest metrics | Precision, recall, F1 and ROC-AUC on the accident class, not just accuracy. |
| Runs anywhere | Normalisation and softmax are folded into the ONNX graph, so every runtime agrees with Python. |
| Actually tested | 66 tests across the data split, freezing logic, checkpoints and the CLI, on three operating systems. |
| Bring your own data | Any two-folder dataset works; class imbalance is handled automatically. |
git clone https://github.com/4ryanwalia/Rakshak---Car.git
cd Rakshak---Car
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e ".[onnx]"If pip starts pulling a multi-gigabyte CUDA build you do not need, install the CPU wheels first:
pip install torch torchvision --index-url https://download.pytorch.org/whl/cpurakshak trainRakshak - training
============================================================
device cpu
backbone mobilenet_v3_small
image size 224
split 202 train / 50 val / 100 test
train class balance accident: 102 non_accident: 100
phase 1: head only (592,898 of 1,519,906 parameters trainable)
...
phase 2: fine-tune (1,519,906 of 1,519,906 parameters trainable)
...
saved checkpoint -> models/rakshak.pt
Training is optional. A trained checkpoint is committed at
models/rakshak.pt (and the same model as ONNX at
docs/assets/model/rakshak.onnx), so the commands below work immediately
after cloning.
rakshak evaluate --split Test
rakshak predict some_image.jpg
rakshak predict "Project/Test/Accident" --jsonMeasured on the 100-image held-out test set, which is never seen during
training or validation. Reproduce with rakshak evaluate --split Test.
| Metric | Score | What it means |
|---|---|---|
| Accuracy | 79.0% | Share of test images classified correctly |
| Recall (accident) | 86.3% | Share of real accidents the model catches |
| Precision (accident) | 75.9% | Share of accident alerts that are correct |
| F1 (accident) | 80.7% | Balance of precision and recall |
| ROC AUC | 0.854 | Ranking quality across every threshold |
Confusion matrix (rows = actual, columns = predicted):
| predicted accident | predicted no accident | |
|---|---|---|
| actual accident | 44 | 7 |
| actual no accident | 14 | 35 |
Backbone MobileNetV3-Small · 224×224 input · seed 42 · CPU. Please read Limitations before quoting these numbers — the test set shares its collection method with the training set, so this is an upper bound, not a field measurement.
Missing an accident and raising a false alarm are not equally bad. Recall on the accident class is the number that matters most — it is the share of real crashes the system would actually flag. Model selection during training uses F1 on the accident class for the same reason.
You can trade one for the other at inference time without retraining:
rakshak predict frames/ --threshold 0.3 # catch more, at the cost of false alarms
rakshak predict frames/ --threshold 0.7 # fewer false alarms, misses more Project/ ┌──────────────────────────┐
├─ Train/Accident │ 1. Load and split │ 80/20 train/val on a
├─ Train/Non Accident │ seeded, reproducible │ fixed seed. Test/ is
└─ Test/ └────────────┬─────────────┘ never touched here.
│ ▼
┌────────────────────────────────────────────────────┐
│ 2. Phase one — frozen backbone │ Only the classifier
│ ImageNet MobileNetV3 ──► fresh 2-way head │ head learns.
└────────────────────────┬───────────────────────────┘
▼
┌────────────────────────────────────────────────────┐
│ 3. Phase two — unfreeze everything │ LR drops 10x so the
│ lr 1e-3 ──► 1e-4, cosine decay │ features adapt
└────────────────────────┬───────────────────────────┘ rather than shatter.
▼
┌────────────────────────────────────────────────────┐
│ 4. Keep the best epoch by validation F1 │ Early stopping on
└────────────────────────┬───────────────────────────┘ patience.
▼
models/rakshak.pt ──► rakshak export ──► rakshak.onnx
│
Python · browser · edge ◄───┘
Why freeze first. With only a couple of hundred training images, a randomly initialised head produces large, meaningless gradients on its first passes. Letting those flow into pretrained ImageNet features damages the one genuinely good thing the model starts with. Training the head alone until it is sensible, and only then unfreezing at a much lower learning rate, is what makes a dataset this small workable at all.
Why normalisation lives inside the ONNX graph. The usual way a deployed
model quietly underperforms its reported accuracy is a client that
preprocesses slightly differently. Folding ImageNet normalisation and softmax
into the exported graph means JavaScript only has to supply RGB values in
[0, 1], and the export step verifies the graph against PyTorch to 1e-4
before it ships.
rakshak train train a detector on a labelled image folder
rakshak evaluate score a checkpoint on a labelled split
rakshak predict classify one or more images
rakshak export export a checkpoint to ONNX
rakshak scrape collect more images for a class
Run rakshak <command> --help for the full set of flags.
# A bigger backbone, longer schedule
rakshak train --backbone resnet18 --epochs 25 --finetune-epochs 15
# Your own dataset, larger input
rakshak train --data-dir ~/datasets/crashes --image-size 288 --batch-size 16
# Head only, no fine-tuning (fastest)
rakshak train --finetune-epochs 0
# Score and save a JSON report
rakshak evaluate --split Test --output report.json
# Export for the website
rakshak export --output docs/assets/model/rakshak.onnxAvailable backbones: mobilenet_v3_small (default), mobilenet_v3_large,
resnet18, resnet50, efficientnet_b0.
from rakshak import AccidentDetector
detector = AccidentDetector.from_checkpoint("models/rakshak.pt")
result = detector.predict("scene.jpg")
print(result.label) # 'accident'
print(result.display_label) # 'Accident'
print(result.confidence) # 0.94
print(result.accident_probability) # 0.94
print(result.is_accident) # TrueBatch a whole folder — the model is loaded once and reused:
for result in detector.predict_dir("frames/"):
if result.is_accident:
alert(result.path, result.confidence)Tune sensitivity without retraining:
sensitive = AccidentDetector.from_checkpoint("models/rakshak.pt", threshold=0.3)Train from Python:
from rakshak import TrainConfig
from rakshak.train import train
summary = train(TrainConfig(data_dir="Project", epochs=15, backbone="resnet18"))
print(summary["test"]["recall"])Two worked examples are in examples/:
batch_folder.py— classify a folder, write a CSVvideo_stream.py— video/webcam with temporal smoothing
rakshak export --checkpoint models/rakshak.pt --output rakshak.onnxThis writes rakshak.onnx plus a rakshak.json describing the input, and
verifies the exported graph against PyTorch before finishing.
The graph takes pixel_values, shape (N, 3, 224, 224), RGB in [0, 1]
(NCHW), and returns probabilities, shape (N, 2), where index 0 is
accident. Normalisation and softmax are already inside it.
import numpy as np, onnxruntime as ort
session = ort.InferenceSession("rakshak.onnx")
probabilities = session.run(None, {"pixel_values": batch.astype(np.float32)})[0]
accident = probabilities[:, 0]In the browser — this is exactly what the demo site does:
const session = await ort.InferenceSession.create("rakshak.onnx");
const tensor = new ort.Tensor("float32", pixels, [1, 3, 224, 224]);
const { probabilities } = await session.run({ pixel_values: tensor });
console.log("P(accident) =", probabilities.data[0]);Preprocessing must match. Resize the shorter side to
round(224 × 1.14) = 255, centre-crop to 224×224, then scale to[0, 1]. Seedocs/assets/js/demo.jsfor a reference implementation.
Point --data-dir at any two-class folder tree:
my_dataset/
├── Train/
│ ├── Accident/
│ └── Non Accident/
└── Test/ # optional
├── Accident/
└── Non Accident/
rakshak train --data-dir my_datasetFolder names are matched loosely: Accident, accident and crash all map to
the accident class; Non Accident, non-accident, no_accident, normal and
safe all map to the other. Imbalanced classes are handled automatically by
weighting the loss, so you do not need to resample.
To collect more images, rakshak scrape pulls from
Openverse and records a licence for every file:
rakshak scrape --label accident --output-dir Project/Train/Accident --limit 100See DATASET.md for the full picture.
rakshak/ the package
├── config.py TrainConfig and shared constants
├── data.py folder discovery, transforms, dataloaders
├── model.py backbone assembly, freezing, checkpoints
├── engine.py train/evaluate loops
├── train.py two-phase training pipeline
├── evaluate.py scoring a checkpoint
├── predict.py AccidentDetector — the public API
├── export.py ONNX export
├── scrape.py Openverse / URL-list collection
└── cli.py `rakshak <command>`
Project/ the dataset (352 images)
docs/ the website, deployed to GitHub Pages
tests/ 66 tests
examples/ batch and video integrations
notebooks/ the original scraping notebook
legacy/ the original Keras CNN, kept for reference
Rakshak is a research preview, not a safety system. Being specific about why is more useful than a disclaimer:
- The dataset is small and its copyright is unclear. 352 images scraped from web search. Some carry stock-agency watermarks. The MIT licence covers the code, not the images.
- Some labels are wrong. A crash-test photo of a visibly wrecked car sits
in
Test/Non Accident. The model is right about that image; the label is wrong. - The classes differ in photographic style. Accident photos are press photography — motion blur, emergency services, bad weather. Non-accident photos skew towards marketing imagery. Some of the reported score is the model learning photo style rather than whether a crash happened. This is the single biggest reason to treat the numbers as an upper bound.
- Still images only. No temporal reasoning, so one odd frame can produce a
false alert.
examples/video_stream.pyshows the cheap mitigation. - Scores are not calibrated. A softmax output of 0.9 does not mean a 90% chance of an accident.
Do not use Rakshak as the sole trigger for emergency response. Every one of these is tracked in DATASET.md and the roadmap — and all of them are open to contribution.
- Clean the dataset: fix wrong labels, drop non-road images, remove watermarked files
- Rebuild the dataset from licensed sources with recorded attribution
- Video input with temporal smoothing as a first-class feature
- Severity grading — minor vs major, instead of a binary flag
- Probability calibration via temperature scaling
- Grad-CAM explanations in the CLI and the web demo
- Publish to PyPI
- Ship a trained checkpoint so
rakshak predictworks without training first
Want one of these? See CONTRIBUTING.md — several need no GPU.
Contributions are very welcome, especially dataset fixes, which need nothing but a pair of eyes.
pip install -e ".[dev,onnx]"
ruff check .
pytestRead CONTRIBUTING.md first, and note the two invariants documented there before changing the class order or the preprocessing. Everyone participating is expected to follow the Code of Conduct.
If Rakshak is useful to you:
- Star the repo — it is how people find it
- Sponsor — sponsorship goes to compute and to the licensed dataset the project needs to grow up
- Open an issue — bug reports and dataset corrections are equally valuable
@software{walia_rakshak_2026,
author = {Walia, Aryan},
title = {Rakshak: Road Accident Detection from Camera Images},
year = {2026},
url = {https://github.com/4ryanwalia/Rakshak---Car},
version = {1.0.0}
}Built on PyTorch and torchvision pretrained backbones, exported with ONNX, and running in the browser through ONNX Runtime Web.
MIT for the code. The bundled dataset images are not covered — see DATASET.md.