opentraffic-perception-engine

<div align="center"> <img src="https://huggingface.co/buckets/OpenTraffic/opentraffic-perception-engine/resolve/opentraffic-perception-engine-main/figure/LOGO2x.png" width="70%" />

<br/>

</div>

TIR — Open-source traffic perception engine for urban intersections

Supports multi-stream RTSP input, YOLO11 + DeepSort detection and tracking, homography-based coordinate transformation, world velocity estimation, lane-level structured output, and radar-reference validation. Designed for Perception-Driven TSC scenarios.

<div align="center"> <img src="https://huggingface.co/buckets/OpenTraffic/opentraffic-perception-engine/resolve/opentraffic-perception-engine-main/figure/Framework.png" width="90%"> </div> <br/>

Paper: https://arxiv.org/abs/XXXX.XXXXX

Project Page: https://opentraffic-team.github.io/tir

HuggingFace: https://huggingface.co/OpenTraffic-Team

GitHub: https://github.com/OpenTraffic-Team/Tir

<br/>

🌟 Table of Contents

• 🎬 Demo Video
• 📢 News
• 📋 TODO List
• 🚀 Quick Start
  • Environment Requirements
  • Installation
  • Start Redis
  • Prepare Video Streams
  • Start the System
• ✏️ Configuration
  • Camera Fields
  • Global Fields
  • Example
• ✨ Features
• 📦 .so Delivery Version
• 🗄️ Redis Data Format
• 📊 Performance
• 📖 Paper
• 🤗 Hugging Face
• 🌐 Social Media
• 🔖 Citation
• 📄 License

<br/>

🎬 Demo Video

▶️ Click to watch the demo video

<br/>

📢 News

• [2026/05/27] Restructured README to align with unified English homepage style.
• [2026/05/15] Initial release of TIR, supporting real-time multi-direction intersection perception.

<br/>

📋 TODO List

• YOLO11 + DeepSort detection and tracking pipeline
• Four-direction (E/S/W/N) data fusion
• Homography matrix pixel → radar world coordinate transformation
• Real-time Redis Stream writing
• Hungarian algorithm cross-modal ID matching (vision ↔ radar)
• In-frame OCR timestamp extraction
• Lane-level structured output
• Radar-reference validation pipeline
• Release pretrained model weights to HuggingFace
• Support more intersection configurations
• Publish technical report / ArXiv paper
• Web visualization dashboard
• Support more camera protocols

<br/>

🚀 Quick Start

Environment Requirements

Installation

# Clone the repository
git clone https://github.com/OpenTraffic-Team/opentraffic-perception-engine.git
cd opentraffic-perception-engine-main/opentraffic-TIR

# Install dependencies
pip install -r requirements.txt

Start Redis

redis-server redis.conf

Prepare Video Streams

Use mediamtx to serve local video as RTSP:

./mediamtx mediamtx.yml

Or use VLC to stream:

vlc video.mp4 --sout '#rtp{sdp=rtsp://:8554/test}'

Or use a local video path directly: Set the rtsp_url field in drivers/config.json to a local file path (e.g. input/45_0429.mp4).

Test video: https://pan.baidu.com/s/1qULF2WcxUP_l5Cvs9uV-JA Password: 1234

Start the System

./run_local.sh

Stop:

./stop_local.sh

<br/>

✏️ Configuration

Edit opentraffic-TIR/drivers/config.json.

Camera Fields

Global Fields

Example

{
  "intersection": {
    "id": "HHL_QHDD",
    "name": "Honghua Road",
    "cameras": [
      {
        "id": "HHL_QHDD_S",
        "rtsp_url": "./input/45_0429.mp4",
        "window": [0, 0, 1920, 1080],
        "H": [[...], [...], [...]],
        "H_inv": [[...], [...], [...]],
        "radar_variant": "default",
        "radar_redis_key": "origin_info_state:HHL_QHDD"
      }
    ]
  },
  "debugMode": false,
  "jsonlOutputDir": "./control_group_fullspeed_jsonl",
  "radarReferenceJsonl": "./reference_radar/HHL_QHDD_S/HHL_QHDD_S_shard_00000.jsonl",
  "vehicleMatchMaxDist": 10.0,
  "localRedisConfig": {
    "host": "127.0.0.1",
    "port": 6379,
    "db": 0,
    "password": "your_password"
  },
  "data_processing": {
    "upload_interval_sec": 1
  }
}

<br/>

✨ Features

🚗 Vehicle Detection

• Vehicle detection and multi-object tracking (YOLO11 + DeepSort) for intersection video.
• Compatible with RTSP streams and local video files.
• Recognition engine compiled to .so for acceleration; outputs structured target IDs for downstream use.

🗺️ World Coordinate Output

• Projects image-space targets into world coordinates.
• Uses calibrated homography matrix (H / H_inv) for pixel-to-world mapping.
• Outputs radar-style coordinates for downstream integration.

💨 World Velocity Estimation

• Kalman-filter-based SimpleVelocityEstimator estimates target velocity in world coordinates.
• Outputs structured velocity fields (m/s) per tracked vehicle.
• Supports traffic state interpretation and speed comparison against radar reference.

🛣️ Lane-Level Output

• Associates detected targets with lane semantics.
• Generates lane-level structured results for consumption by control systems.

🕐 Timestamp Extraction

• OCR extracts timestamps from video frames for accurate temporal alignment.

🔗 Cross-Modal ID Matching

• Hungarian algorithm aligns visual targets with external radar data by ID.

<br/>

📦 .so Delivery Version

This section applies to the self-contained .so delivery package, which runs without the full source code.

Included Resources

Running

Start:

cd /tir-0513-git-so
./run_local.sh

Stop:

cd /tir-0513-git-so
./stop_local.sh

Output Format

Default output directory:

control_group_fullspeed_jsonl/HHL_QHDD_S/HHL_QHDD_S_shard_00000.jsonl

Output JSONL fields:

<br/>

🗄️ Redis Data Format

Results are written to two Redis keys:

• Snapshot: recognition_{camera_id}_snap
• Stream: recognition_{camera_id}

Merged four-direction snapshot format (origin_info_state:{intersection_id}):

{
  "code": "HHL_QHDD",
  "name": "Honghua Road",
  "recognitionSnap[HHL_QHDD_E]": {
    "timestamp": 1734400000.0,
    "vehicles": [
      {
        "id": "42",
        "orig_id": "7",
        "type": "",
        "lane": "",
        "center": [12.5, 8.3],
        "speed": [3.2, -1.1],
        "licenseNum": ""
      }
    ]
  }
}

<br/>

📊 Performance

Evaluation: historical full-set speed JSONL vs. raw radar JSONL.

Field Error Comparison

Field Consistency

<br/>

📖 Paper

• Title: OpenTraffic Perception System for Perception-Driven TSC
• Status: In preparation / pending release
• Placeholder: https://arxiv.org/abs/XXXX.XXXXX

<br/>

🤗 Hugging Face

• Model page: https://huggingface.co/OpenTraffic-Team
• Planned releases:
  • Packaged perception model
  • Sample output results
  • Benchmark examples

<br/>

🌐 Social Media

• GitHub: https://github.com/OpenTraffic-Team/Tir
• WeChat Group: Join Discussion
• X / Twitter: Coming soon

<br/>

🔖 Citation

If TIR is useful for your research, please cite:

@article{tir2026,
  title   = {TIR: Real-Time Traffic Situation Awareness for Urban Intersections},
  author  = {OpenTraffic Team},
  journal = {arXiv preprint},
  year    = {2026}
}

<br/>

📄 License

This project is released under the Apache 2.0 License.

---

<div align="center"> <b>OpenTraffic Team</b> | Making urban traffic smarter. </div>