Road traffic monitoring utility written in pure Rust. OpenCV is not required - the project supports ONNX Runtime and TensorRT backends that work without any OpenCV dependency (even for drawing/grabbing/postprocess frames stuff). OpenCV DNN backend is also available as an optional (and currently default) feature for those who prefer it.
- Video showcase
- About
- Inference Backends
- Traffic flow parameters
- Installation and usage
- Virtual lines
- ANPR and vehicle events
- Dataset collection
- Report mode
- ROADMAP
- Support
Basic vehicle detection and tracking:
showcase_3.mp4
ANPR (for more information see ANPR.md):
showcase_4.mp4
Vehicle detection/tracking and speed estimation via next instruments:
- Rust programming language - https://www.rust-lang.org/
- Object detection - od_opencv crate with three inference backends:
- OpenCV DNN (optional) - https://github.com/twistedfall/opencv-rust
- ONNX Runtime - https://onnxruntime.ai/
- TensorRT - https://developer.nvidia.com/tensorrt
- Linear algebra - https://github.com/dimforge/nalgebra
- YOLO models: YOLOv3/v4/v7 (Darknet), YOLOv8/v9/v11 (Ultralytics) - https://github.com/ultralytics/ultralytics
- actix-web for web part - https://actix.rs/
Notice:
UI is developed in seprate repository: https://github.com/LdDl/rust-road-traffic-ui. Prepared static directory after npm run build is here'
This project supports three inference backends via compile-time feature flags:
| Backend | Feature Flag | Models Supported | GPU Support | Requires OpenCV |
|---|---|---|---|---|
| OpenCV DNN | opencv-backend (default) |
YOLOv3/v4/v7 (Darknet), YOLOv8/v9/v11 (ONNX) | CUDA, OpenCL | Yes |
| ONNX Runtime | ort-backend |
YOLOv8/v9/v11 (ONNX only) | CUDA 12.x | No |
| TensorRT | tensorrt-backend |
YOLOv8/v9/v11 (.engine only) |
CUDA (native TensorRT) | No |
ort-backend and tensorrt-backend do NOT require OpenCV on the system. Video capture uses ffmpeg/GStreamer subprocesses, drawing uses own primitives, image encoding uses turbojpeg/png crates.
ort-backend uses ort 2.x crate which requires CUDA 12.x or higher for GPU acceleration. It will not work on systems with CUDA 10.x/11.x and so on.
tensorrt-backend is designed for NVIDIA embedded platforms (e.g. Jetson Nano) and discrete NVIDIA GPUs with TensorRT installed.
Network input size: For Darknet models (.cfg + .weights), net_width/net_height in TOML config are ignored - the input size is read directly from the [net] section of the .cfg file. For TensorRT (.engine), input size is also auto-detected from the engine bindings. For ONNX models, net_width/net_height must be specified in the TOML config.
Note: In case of non-OpenCV backend, traditional models (YOLOv3/v4/v7) in Darknet format (.cfg + .weights) should be converted to ONNX first via darknet2onnx with --format yolov8 flag. The --format yolov5 output is not supported (different post-processing). For TensorRT, convert ONNX to .engine via trtexec.
By default MJPEG streaming links to system libturbojpeg via pkg-config. Add --features turbojpeg-vendor to any build command below to build libjpeg-turbo from source instead (requires cmake).
# OpenCV backend (default) - requires OpenCV installed, supports traditional and Ultralytics models
cargo build --release
# ORT backend - no OpenCV needed at all
cargo build --release --no-default-features --features ort-backend
# TensorRT backend - no OpenCV needed at all (Jetson / NVIDIA GPU)
cargo build --release --no-default-features --features tensorrt-backend
# Any backend + vendored libjpeg-turbo (no system lib needed, requires cmake)
cargo build --release --features turbojpeg-vendor
cargo build --release --no-default-features --features tensorrt-backend,turbojpeg-vendor
cargo build --release --no-default-features --features ort-backend,turbojpeg-vendor# OpenCV backend
cargo run --release -- path-to-toml-file
# ORT backend
cargo run --release --no-default-features --features ort-backend -- path-to-toml-file
# TensorRT backend
cargo run --release --no-default-features --features tensorrt-backend -- path-to-toml-fileUse trtexec (included with TensorRT / JetPack) to convert an ONNX model:
trtexec --onnx=yolov8n.onnx --saveEngine=yolov8n.engine --fp16On Jetson devices, trtexec is typically located at /usr/src/tensorrt/bin/trtexec.
Be aware that Traditional models v3, v4 and v7 should be converted to ONNX first via darknet2onnx with --format yolov8 flag, and then via trtexec to TensorRT engine format.
Both REST API and Redis publisher export following parameters for each user-defined vehicle class:
-
Flow (a.k.a intensity)
Number of vehicles that pass given zone (or cross virtual line) in a specified period of time -
vehicles per period.You can cast any given flow to
vehicles/hourby multiplying the value by specific multiplier. E.g. software outputs 100vehicles per 15 minutes, then you may have 100*15=1500vehicles/hour.Look up at Virtual lines section on how vehicles are counted for additional information.
-
Defined flow
Same as just flow, but it is a number of vehicles that both pass given zone (or cross virtual line) in specified period of time and HAVE defined speed. Sometimes software just can't calculate speed, therefore defined flow has been introduced. This parameter could be renamed in further (in both documentation and code/api).
-
Average speed of the flow
Basically it is just average value among all speeds of vehicles that pass given zone (or cross virtual line) in a specified period of time. If speed could not be determined due some circumstances it is considered to be
-1(and not to be used in average aggregation).
For the all user-defined vehicles' classes there are:
-
Same as for single vehicle class: Flow, Defined Flow, Average speed of the flow.
-
Average headway
Average value amoung all calculated headway values. Headhway is the time that elapsed between the arrival of the leading vehicle and following vehicle to the zone (or virtual line).
Let's break down an example: you have 3 vehicles crossed a certain virtual line at specific times:
[10:00:01, 10:00:07, 10:00:09]. Then you have differences:[10:00:07 - 10:00:01, 10:00:09 - 10:00:07]which gives[6 seconds, 2 seconds]headways which gives(6+2)/2 = 4 secondsas average headway.You may ask: why average headway is not calculated for single class? -- It does not make that much sense to estimate it because headway is not that representative for some specific classes (e.g. bus) due the nature of distribution of that classes among the popular ones (e.g. personal cars). It could be reconsidered in further for some edge cases (PR's are welcome).
- OD (origin-destination) matrix - connections between different zones. Each connection is represented as number of vehicles moved from origin zone to destination one.
Locally you can access Swagger UI documentation via http://localhost:42001/api/docs:
-
You need installed Rust compiler obviously. Follow instruction of official site: https://www.rust-lang.org/tools/install
-
OpenCV is only required for
opencv-backend(the default). If you useort-backendortensorrt-backend, skip this step. In case of needopencv-backendI'd highly recommend to use OpenCV >= 4.7.0 with CUDA. Here is Makefile adopted from this one if you want build it from sources (it's targeted for Linux user obviously).sudo make install_cuda
Be aware: OpenCV < 4.7.0 probably wont work with YOLOv8 (even with ONNX opset12) if you need those.
-
You need
ffmpegandffprobeinstalled for video capture (files, RTSP streams, USB cameras). For GStreamer pipelines (e.g. CSI cameras on Jetson) you needgst-launch-1.0as well.# Debian/Ubuntu sudo apt install ffmpeg # GStreamer (optional, for CSI/MIPI cameras) sudo apt install gstreamer1.0-tools gstreamer1.0-plugins-base gstreamer1.0-plugins-good # Arch Linux sudo pacman -S ffmpeg # GStreamer (optional, for CSI/MIPI cameras) sudo pacman -S gstreamer gst-plugins-base gst-plugins-good
Source type is auto-detected from
video_srcin the configuration file:Source Example video_srcBackend Video file "./data/video.mp4"ffmpeg RTSP stream "rtsp://user:pass@192.168.1.10:554/stream"ffmpeg (TCP) USB camera (V4L2) "0"or"/dev/video0"ffmpeg GStreamer pipeline starts with known source element (e.g. nvarguscamerasrc,v4l2src), contains!gst-launch-1.0 GStreamer pipeline examples (use
appsinkas sink - it will be replaced withfdsink fd=1automatically; pipeline must output BGR format; width/height/framerate are parsed from caps in the pipeline string):# CSI camera via nvarguscamerasrc (Jetson Nano 4gb in my case) video_src = "nvarguscamerasrc sensor-id=0 ! video/x-raw(memory:NVMM), width=(int)1280, height=(int)720, format=(string)NV12, framerate=(fraction)30/1 ! nvvidconv flip-method=0 ! video/x-raw, width=(int)1280, height=(int)720, format=(string)BGRx ! videoconvert ! video/x-raw, format=(string)BGR ! appsink" # USB camera via GStreamer (alternative to V4L2) video_src = "v4l2src device=/dev/video0 ! video/x-raw, width=(int)640, height=(int)480, framerate=(fraction)30/1, format=(string)BGR ! appsink"
-
Dependencies are managed via Cargo.toml. OpenCV bindings are pulled automatically when using
opencv-backend. -
Clone the repo
git clone https://github.com/LdDl/rust-road-traffic.git
Well, actually I provide yolov4-tiny configuration and weights file from official repository (authors of YOLOv4), but you are free to use yours. I provide video file as sample also.
-
Сhange parameters for this utility by using template of configuration file. There is detailed explanation of each parameter.
-
Download weights and configuration files (optional)
-
YOLO v4 tiny - yolov4-tiny-vehicles-rect_best.weights + yolov4-tiny-vehicles-rect.cfg. It has been trained on filtered COCO dataset; classes are: "car", "motorbike", "bus", "train", "truck"
-
YOLO v3 tiny - tinyv3-vehicles_best.weights + tinyv3-vehicles.cfg. It has been trained on AIC HCMC 2020 challenge data; classes are: "car", "motorbike", "bus", "truck". More information here: https://github.com/LdDl/yolo_vehicles . I like it more personally.
-
-
Run
cargo run path-to-toml-file
If you want to use some Rust's optimizations then call build and run
cargo build --release && ./target/release/rust-road-traffic path-to-toml-fileIf you want both optimized in term of perfomance and stripped executable binary (thanks to rust-lang/cargo#3483)
export RUSTFLAGS='-C link-arg=-s' && cargo build --release && ./target/release/rust-road-traffic path-to-toml-file
-
UI configuration
If you enabled both REST API and MJPEG streaming and you want to adjust parameters for detection zones you could open http://localhost:42001/ in your browser and adjust polygons as you need (this UI still needs to be debugged and polished):
Configuration file lines:
[rest_api] enable = true host = "0.0.0.0" back_end_port = 42001 api_scope = "/api" [rest_api.mjpeg_streaming] enable = true # 0-100 quality = 80
-
Tracker configuration It is possible to pick either iou_naive or bytetrack tracker for tracking objects.
[tracking] # Either "bytetrack" or "iou_naive". Default is "iou_naive" type = "iou_naive" # Adjust number of points for each object in its track max_points_in_track = 100 # Kalman filter type: "centroid" or "bbox" # Default is "centroid" kalman_filter = "centroid" # How long (seconds) to keep a track alive without new detections. Default is 2.0. # Counted in real time, so it means the same on a file, a live stream, with frame skipping # and with a throttled detector. Increase (e.g. 3-4) for better OD matrix results when # objects need to traverse between distant zones. max_lost_seconds = 2.0 # Legacy frame-count limit, only used when `max_lost_seconds` is not set. # max_no_match = 60 # IoU threshold for matching detections to existing tracks. Default is 0.3. # Lower values (0.2-0.25) make matching stricter, higher values (0.4-0.5) make it more permissive. iou_threshold = 0.3
Configurable parameters:
-
max_lost_seconds(default: 2.0): How long a track survives without detections, in seconds of real time. Increase for better OD matrix tracking across distant zones. -
max_no_match: The same limit as a frame count; only used whenmax_lost_secondsis not set. A frame count changes meaning with the effective frame rate (frame skipping, a slow detector, a stalled stream), so prefer seconds. -
iou_threshold(default: 0.3): IoU threshold for matching detections to tracks. Lower = stricter matching.
Fixed parameters for ByteTrack:
- high_thresh = 0.7
- low_thresh = 0.3
- algorithm = Hungarian (matching algorithm)
Kalman Filter Types
The
kalman_filteroption selects the internal Kalman filter used for state prediction:Feature centroidbboxState vector $(x, y, v_x, v_y)$ $(x, y, w, h, v_x, v_y, v_w, v_h)$ State dimensions 4D 8D Tracks position v v Tracks velocity v v Tracks size (width/height) no v Best for Objects with stable size Objects changing size/aspect ratio Computational cost Lower Higher When to use
bbox:- Objects moving towards/away from camera (size changes)
- Varying aspect ratios during movement
- Better bounding box stability during occlusions
When to use
centroid(default):- Side-view cameras where object size is relatively stable
- Lower computational requirements
- Simpler tracking scenarios
-
-
REST API
If you want to do some REST calls you can do following (based on rest_api field in TOML configuration files)
# Get polygons (GeoJSON) in which road traffic monitoring is requested curl -XGET 'http://localhost:42001/api/polygons/geojson' # Get statistics info for each polygon and each vehicle type in that polygon curl -XGET 'http://localhost:42001/api/stats/all'
-
Export data
If you've enabled Redis output you can connect to Redis server (e.g. via CLI) and monitor incoming messages:
Configuration file lines:
[redis_publisher] enable = true host = "localhost" port = 6379 password = "" db_index = 0 channel_name = "DETECTORS_STATISTICS"
Both REST API and Redis publisher reset statistics in specific amount of time which could be adjusted via
reset_data_millisecondsoption:[worker] reset_data_milliseconds = 30000
-
Status
GET /api/statusanswers the questions that would otherwise need an SSH session: which source is being read and whether frames are getting through, what the inference runs on, how objects are tracked, where statistics are published, where the log goes, and what went wrong last.curl http://localhost:42001/api/status
{ "equipment_id": "1e23985f-1fa3-45d0-a365-2d8525a23ddd", "version": "0.3.1", "uptime_seconds": 42, "input": {"video_src": "rtsp://...", "kind": "live", "width": 1280, "height": 720, "fps": 30.0, "process_every_nth_frame": 2, "frames_processed": 542, "frames_dropped": 0, "processing_fps": 14.9, "last_frame_at": 36.1}, "detection": {"backend": "ort", "cuda_available": true, "model": "./data/model.onnx", "net_width": 416, "net_height": 256, "inference_ms": 7.4, "postprocess_ms": 0.01, "tracking_ms": 0.01}, "tracking": {"description": "BBox tracker (8D Kalman: ...) with ByteTracker engine, tracks expire after 2 s unmatched"}, "redis": {"enabled": false, "host": "localhost", "port": 6379, "channel": "DETECTORS_STATISTICS"}, "logging": {"level": "info", "file": "./logs/rust-road-traffic.log"}, "last_problem": null }processing_fpsis measured over the last second, so it shows what the detector keeps up with rather than what the source promises;frames_droppedcounts the frames a busy detector never got to, and is always 0 for a video file.last_problemis the most recent warning or error as it went into the log, with itsscope, ornullif there was none.save_required/unsaved_changesandrestart_required/pending_changessay what is still to be saved and what waits for a restart: the same block every changing request answers with (see Configuration over the API). Unlike the answer to a request, it survives a page reload. -
Restarting
Some settings are only read at startup: the video source, the tracker, Redis publisher and the statistics refresher period. API
POST /api/mutations/restartrestarts the application to pick them up, without knowing what supervises it:curl -X POST http://localhost:42001/api/mutations/restart # {"message":"restarting"}The process replaces its own image, keeping the same PID, so systemd sees no exit, a container whose entrypoint is this binary keeps running, and a plain terminal run comes back as well. Nothing is saved first, and a restart reads the file, so while anything is unsaved - settings, zones, even the ones that took effect at once - the request is refused with
409and the sameunsaved_changesblock every changing request answers with;?force=truerestarts anyway and drops what is unsaved. A config edited over SSH is picked up exactly as written. The reply is sent before the restart happens, so wait for/api/pingto answer again.The capture subprocess is shut down properly on the way out, and on
Ctrl-Cas well: it is sentSIGINT, whichgst-launch-1.0answers by taking the pipeline down to NULL, and only killed if it does not go within two seconds. That matters on a Jetson CSI camera, where only the orderly teardown closes the Argus session - a session left open keeps the sensor busy for the next start.Under systemd, add
KillMode=mixedto the unit so that stopping the service signals this process alone and lets it shut its pipeline down; with the defaultcontrol-groupsystemd signalsgst-launch-1.0directly, which kills it with the pipeline still up. -
Logging
Logs are NDJSON (one JSON object per line) on stdout and, by default, in
./logs/rust-road-traffic.lognext to the config file. Every line carrieslevel(INFO,WARN,ERROR),scope(startup,capture,processing,analytics,redis,rest_api,report,dataset) and the message with its fields:{"timestamp":"2026-09-07T16:56:01.362275Z","level":"INFO","fields":{"message":"Frame timing","scope":"capture","source":"file","process_every_nth_frame":2,"nominal_dt":0.0667,"dt_min":0.0167,"dt_max":2.0}}The
[verbose]section (optional, every key optional) only sets how much and where:[verbose] # "info" (default): regular, warning and error lines. "debug" adds per-frame detail. level = "info" # Relative to the config file's folder. Empty string = stdout only. logs_folder = "./logs" # Rotate daily or at this size (MB); keep this many old files (defaults: 10 MB, 2 files). max_file_size_mb = 10 max_files = 2
The
RUST_LOGenvironment variable overrideslevel. A folder that can't be written to never stops the app: it logs to stdout only and says why.The same lines are readable over the API, which is what the file is for: it is rotated, kept on disk and survives a restart, which is exactly when one wants to see what came before.
curl "http://localhost:42001/api/logs?limit=50&level=warn&scope=capture"limitis 200 by default and 5000 at most,levelis the lowest severity to include,scopematches one of the scopes above. Entries come oldest first, and rotated files are read as well when the current one is not enough. -
Configuration over the API
GET /api/configreturns the settings held in memory, the onesPATCHchanges, for the sections an operator may touch:input,tracking,equipment_info,worker,redis_publisherandverbose. Zones have their own endpoints; detection and the REST server itself are not part of it.GET /api/tracking/typeslists the valuestracking.typeandtracking.kalman_filteraccept.PATCH /api/configchanges the settings in memory only. Only the keys present in the request are touched, and a body this endpoint does not take is refused with 400 - what was wrong with it goes to the log rather than to the caller:curl -X PATCH -H 'Content-Type: application/json' \ -d '{"input": {"video_src": "rtsp://cam/stream"}, "verbose": {"level": "debug"}}' \ http://localhost:42001/api/config # {"message":"ok","changed":["input.video_src","verbose.level"], # "save_required":true,"unsaved_changes":["input.video_src","verbose.level"], # "restart_required":true,"pending_changes":["input.video_src"]}
Nothing reaches the file until
GET /api/mutations/save_toml, the only thing that writes it: the settings from memory together with the zones the running process uses. A restart reads the file, so the order is always save, then restart. Every request that changes something, settings or zones, answers with the same four fields describing everything left to do rather than only its own part, andGET /api/statuscarries them too:-
save_required/unsaved_changes- memory differs from the file (road_lanesstands for the zones); -
restart_required/pending_changes- some change takes effect only afterPOST /api/mutations/restart.
The log level, the equipment id and the zones apply at once and need saving only to survive a restart. Everything else is read when the piece that uses it is built, and waits for a restart. Values are validated the same way as when the file is loaded, and a request that would not make sense is rejected with 400. A key sent as
nullclears a setting that may be unset -tracking.max_lost_seconds,max_no_match,iou_threshold,redis_publisher.usernameand everything inverbose- and it is removed from the file on the next save; a key left out is not touched.Redis can be tried before it is saved:
curl -X POST -H 'Content-Type: application/json' -d '{"host": "10.0.0.2", "port": 6379}' \ http://localhost:42001/api/redis/check # {"ok":false,"took_ms":1,"target":"10.0.0.2:6379/0","error":"Connection refused (os error 111)"}
Anything left out of the request is taken from the current configuration, so an empty body checks what the app is set up to use.
-
See ANPR.md for configuration, image export and the SSE JSON format.
This utility supports vehicle counting via two approaches:
| Vehicle appeared in the zone | Vehicle crossed the line |
|---|---|
![]() |
![]() |
But what is the point to have optional virtual line for zone? Why just not use either line or zone at all?
-- Well, zone is essential for estimating speed, so it is needed for sure. Why need line then: sometimes it is needed to register vehicles in specific direction only or at specific moment of time (in center of zone, in bottom of zone, after zone and etc.).
You can configure virtual lines via configuration file or via UI (look at showcase):
[[road_lanes]]
lane_number = 0
lane_direction = 0
geometry = [[204, 542], [398, 558], [506, 325], [402, 318]]
geometry_wgs84 = [[-3.7058048784300297,40.39308821416677],[-3.7058296599552705,40.39306089952626],[-3.7059466895758533,40.393116604041296],[-3.705927467488266,40.39314855180666]]
color_rgb = [255, 0, 0]
# Remove lines below if you don't want to include virtual line
# Note: There is only one possible virtual line for given zone
[road_lanes.virtual_line]
geometry = [[254, 456], [456, 475]]
color_rgb = [255, 0, 0]
# inbound - inbound traffic (towards target side)
# outbound - outbound traffic (away from target side)
direction = "inbound"This utility can also automatically collect training datasets from video streams using a strong detection model. Useful for preparing YOLO training data on your specific use case.
- Run software with a reliable detection model (e.g., traditional YOLOv7 or Ultralytics YOLOv8)
- Use static video file (I mean you can prepare dataset from RTSP stream, but it is recommended to use video file for reproducibility and also could be use to retrain model and check results on same video again)
- Software tracks detected vehicles over time
- When a track is "mature" (visible for N frames, not touching frame edges), it saves:
- Raw image (no overlays/drawings) to
output_dir/images/ - YOLO format annotations to
output_dir/labels/
- Raw image (no overlays/drawings) to
# Dataset collector - auto-labeling feature for collecting training data
# This section is optional - if not present, the feature is disabled
[dataset_collector]
# Enable/disable dataset collection
enabled = true
# Output directory for images/ and labels/ folders
output_dir = "./collected_dataset"
# Label format: "yolo" for standard YOLO format (class_id center_x center_y width height)
# Currently only "yolo" is supported
label_format = "yolo"
# Minimum number of frames a track must exist before capturing (avoids partially visible objects)
min_track_age = 15
# Skip objects whose bounding box touches or is near frame edges
skip_edge_objects = true
# Margin in pixels to consider as "edge"
edge_margin_pixels = 5
# Maximum number of captures per unique track ID (1 = capture once per vehicle)
max_captures_per_track = 1
# Frames between captures for the same track (only used when max_captures_per_track > 1)
capture_interval = 30collected_dataset/
├── images/
│ └── 20251212_143052_123456_42.jpg
└── labels/
└── 20251212_143052_123456_42.txt
Label format (YOLO): class_id center_x center_y width height (all values normalized 0-1)
Example label file:
2 0.453125 0.621528 0.089844 0.156944
7 0.712500 0.534722 0.125000 0.180556
- Use a strong/accurate model for better pseudo-labels quality
- Set higher
min_track_age(e.g., 20-30) for cleaner samples - Review collected data before training - auto-labels may contain errors
- Class IDs in labels correspond to
net_classesorder in[detection]section - You can use https://github.com/LdDl/yolo-ann tool to visualize and manage collected dataset
This utility can generate a ZIP report after processing a video file. Report mode processes the entire video, accumulates all traffic statistics (no periodic resets) and produces a ZIP archive.
Note: Report mode is only available for video files, not for RTSP streams or cameras.
When report mode is enabled it automatically disables REST API, MJPEG streaming and periodic statistics reset.
[report]
enabled = true
output_path = "./reports"ZIP archive {video_name}_report.zip in configured output_path directory containing:
| File | Description |
|---|---|
traffic_counts.csv |
Vehicle counts per type per zone |
zones.csv |
Zone polygon coordinates (4 vertices) |
od_matrix.csv |
Origin-Destination matrix (zone movements) |
{video_name}_zones.png |
First frame with zones drawn, IDs and coordinates labeled |
CSV files use semicolon (;) as delimiter.
traffic_counts.csv example:
vehicle_type;zone_id;count
car;dir_0_lane_0;42
truck;dir_0_lane_0;15
zones.csv example:
zone_id;x1;y1;x2;y2;x3;y3;x4;y4
dir_0_lane_0;204;542;398;558;506;325;402;318
od_matrix.csv example:
zone_from;zone_to;count
dir_0_lane_0;dir_0_lane_1;15
dir_0_lane_1;dir_1_lane_0;8
Please see this file
If you have troubles or questions please open an issue.







