Edge Traffic Vision

A reproducible CPU-first road-object detection pipeline built for measurable edge-AI engineering.

Deterministic BDD100K ingestion ? YOLO validation ? CPU training ? ONNX export ? robustness evaluation ? video inference ? Docker packaging

Why This Project

Edge Traffic Vision demonstrates an end-to-end computer-vision workflow for detecting traffic signs, pedestrians, vehicles, and other road objects from images, videos, and camera sources.

The repository is designed around four engineering priorities:

• Reproducibility: configuration-driven data, training, evaluation, export, and inference workflows
• Validation: automated dataset, model, package, Docker, and release contracts
• Measurement: precision, recall, mAP, robustness, latency, and throughput evidence
• Deployment: ONNX Runtime CPU inference and non-root Docker packaging

This is an engineering-preview project. It must not be described as production-ready.

Verified Results

Area	Verified result
Balanced pilot dataset	2,500 images
Total pilot annotations	45,443
Canonical road-object classes	10
Selected model mAP50	0.14127
Selected model mAP50-95	0.07561
Operating confidence	0.20
Precision / recall / F1	0.51974 / 0.32730 / 0.40166
ONNX Runtime raw-backend speedup	3.317x
Severe Gaussian-noise mAP50 drop	39.71%
Representative 360p throughput	70.09 FPS
Representative 720p throughput	43.24 FPS
Representative 1080p throughput	21.77 FPS

The resolution measurements use a controlled 60-scene validation source. They include source decoding, preprocessing, ONNX inference, NMS, annotation rendering, and MP4 writing.

Continuous road-video validation remains pending until a suitable naturally changing MP4 is supplied.

System Architecture

flowchart LR
    A[BDD100K images and annotations]
    B[Deterministic ingestion]
    C[YOLO dataset validation]
    D[Annotation-balanced pilot]
    E[CPU training and evaluation]
    F[Confidence selection]
    G[ONNX export and validation]
    H[ONNX Runtime inference]
    I[Robustness and benchmark reports]
    J[Video and camera pipeline]
    K[Non-root CPU Docker image]

    A --> B
    B --> C
    C --> D
    D --> E
    E --> F
    F --> G
    G --> H
    H --> I
    H --> J
    J --> K

Loading

The trained checkpoint, ONNX model, BDD100K data, external videos, and generated reports are deliberately excluded from the source repository.

Core Capabilities

Data engineering

• Deterministic BDD100K Detection 2020 annotation parsing
• Native BDD100K-to-YOLO class and bounding-box conversion
• Transactional image, label, and manifest generation
• Annotation-balanced rare-class pilot selection
• Image-label pairing, readability, resolution, coordinate, class, duplicate, and syntax validation
• Atomic JSON and CSV validation reports

Model engineering

• CPU training readiness and smoke-training workflows
• Controlled 40-epoch lightweight detector training
• Confidence-threshold operating-point selection
• Reproducible ONNX export with graph and runtime validation
• Controlled PyTorch-versus-ONNX Runtime benchmarking
• Severity-based low-light, blur, and Gaussian-noise evaluation

Deployment engineering

• Config-driven image, video, and camera inference
• Warm-up-aware component and end-to-end latency profiling
• Representative 360p, 720p, and 1080p validation
• CPU-only non-root Docker packaging
• GitHub Actions tests, lint, package preflight, and Docker smoke checks
• Tag-only package release validation

Quick Start

1. Clone and create the Python environment

git clone https://github.com/NafizNoyon/edge-traffic-vision.git
Set-Location edge-traffic-vision

python -m venv .venv
.\.venv\Scripts\Activate.ps1

python -m pip install --upgrade pip
python -m pip install -r requirements-dev.txt
python -m pip install --no-deps -e .

Python 3.12 is required.

2. Verify the repository

python -m pytest -q
python -m ruff check src tests scripts
python -m pip check

3. Inspect the available CLIs

edge-traffic-ingest --help
edge-traffic-dataset-check --help
edge-traffic-train --help
edge-traffic-export-onnx --help
edge-traffic-video --help

Data, trained weights, and ONNX artifacts are not downloaded automatically.

Typical Workflow

Dataset ingestion preflight

edge-traffic-ingest `
    --config configs/dataset_ingestion_balanced.yaml `
    --dry-run

Materialize and validate the balanced pilot

edge-traffic-ingest `
    --config configs/dataset_ingestion_balanced.yaml

edge-traffic-dataset-check `
    --config configs/dataset_validation_balanced.yaml

Verify training readiness

edge-traffic-train `
    --config configs/training_smoke.yaml `
    --preflight-only

Export the selected checkpoint to ONNX

edge-traffic-export-onnx `
    --config configs/onnx_export.yaml

Run video-inference preflight

edge-traffic-video `
    --config configs/video_inference.yaml `
    --preflight-only

Evaluate robustness

edge-traffic-robustness `
    --config configs/robustness_evaluation.yaml `
    --preflight-only

Command Reference

Command	Purpose
edge-traffic-ingest	Plan and execute deterministic BDD100K ingestion
edge-traffic-dataset-check	Validate YOLO images, labels, and structure
edge-traffic-train	Run training readiness or controlled training
edge-traffic-baseline	Run configuration-driven baseline inference
edge-traffic-benchmark	Measure repeated inference performance
edge-traffic-export-onnx	Export and validate an ONNX model
edge-traffic-backend-benchmark	Compare PyTorch and ONNX Runtime
edge-traffic-robustness	Evaluate low-light, blur, and noise conditions
edge-traffic-video	Run ONNX video or camera inference

Repository Layout

edge-traffic-vision/
??? .github/workflows/       CI and release-package workflows
??? configs/                 Reproducible YAML configurations
??? data/                    Local dataset lifecycle directories
??? docker/                  Container helper files
??? docs/                    Engineering and reproduction documentation
??? models/                  Local model-artifact directories
??? scripts/                 Release and artifact validation tools
??? src/edge_traffic_vision/ Installable Python package
??? tests/                   Automated contract and regression tests
??? Dockerfile               CPU-only non-root runtime image
??? pyproject.toml           Package metadata and CLI entry points
??? README.md                Project landing page

Generated datasets, checkpoints, ONNX models, reports, videos, and temporary build outputs are excluded from version control.

Documentation

Topic	Guide
Dataset ingestion	BDD100K Dataset Ingestion
Dataset validation	Dataset Validation
Training	Training Readiness and CPU Training
CPU benchmarking	CPU Inference Benchmark
ONNX deployment	ONNX Export and Backend Benchmark
Robustness	Deterministic Robustness Evaluation
Video inference	ONNX Video Inference
Video optimization	Video Pipeline Optimization
Resolution validation	Multi-Scene Video Validation
Docker	Docker Packaging
Release process	Release Checklist
Proposed release notes	v0.1.0 Notes

Release Status

• Package metadata version: 0.1.0
• Release stage: engineering-preview preparation
• Public GitHub Release: not published
• Continuous road-video validation: pending
• Repository license: MIT
• Package, Docker, and tag-validation workflows: verified
• Model, dataset, video, and generated report artifacts: not bundled

Completed release milestones:

MIT licensing completed
    -> release-readiness hardening completed
    -> continuous road-video validation
    -> v0.1.0 release decision

The project should be published as a prerelease when continuous road-video validation remains incomplete.

Development Status

Twenty engineering milestones are complete, including:

• deterministic data ingestion and validation
• balanced pilot construction
• CPU training and threshold selection
• ONNX export and backend comparison
• robustness and video-pipeline validation
• CPU Docker packaging
• MIT licensing
• package and release-workflow hardening

The next evidence milestone is continuous road-video validation using a naturally changing source.

Limitations

• The current model was trained on a limited balanced pilot rather than the complete BDD100K training corpus.
• Current execution and measured deployment evidence are CPU-focused.
• Continuous natural road-video evidence remains unavailable.
• Webcam and camera forwarding depend on the host environment.
• Dataset, model, and external-video redistribution terms must be reviewed separately from the repository's source-code license.
• Reported metrics describe controlled engineering experiments and do not establish production safety or production readiness.

License

Source code is licensed under the MIT License.

BDD100K data, pretrained or trained model artifacts, external videos, and other third-party resources remain subject to their respective licenses, access rules, and redistribution terms.