OTVision

OTVision is a core module of the OpenTrafficCam framework designed to detect and track objects (road users) in videos recorded by OTCamera or other camera systems. The resulting trajectories can be used for traffic analysis using OTAnalytics.

Features

• Video Conversion: Convert video files (h264 to mp4) with options to set frame rate and rotation
• Object Detection: Detect road users in videos using state-of-the-art YOLO models
• Object Tracking: Track detected objects through video frames using IOU-based tracking algorithms

Requirements

System Requirements

• Python 3.12
• uv for dependency management
• CUDA-capable GPU (recommended for faster processing)
• ffmpeg (optional for video conversion)

Installation

Installation from GitHub Releases

Pre-built releases are available on GitHub for easy installation:

1. Go to the OTVision Releases page on GitHub
2. Download the appropriate release for your platform:
   • Windows: Choose between OTVision-win-{vX.Y.Z}.zip (standard) or OTVision-win-cuda-{vX.Y.Z}.zip (with CUDA support)
   • Linux: Choose between OTVision-linux-{vX.Y.Z}.zip (standard) or OTVision-linux-cuda-{vX.Y.Z}.zip (with CUDA support)
   • macOS: Choose OTVision-macos-{vX.Y.Z}.zip
3. Extract the downloaded ZIP file
4. Run the installation script:
   • On Windows: Double-click install.cmd
   • On Linux: Run ./install.sh
   • On macOS: Double-click install.command

Manual Installation

1. Clone the repository:

   git clone https://github.com/OpenTrafficCam/OTVision.git
   cd OTVision
   

2. Install the package:

   • On Windows:

     install.cmd
     

   • On Linux/macOS:

     ./install.sh
     

Manual Development Installation

For development purposes, if you want to contribute to the project:

1. Clone the repository:

   git clone https://github.com/OpenTrafficCam/OTVision.git
   cd OTVision
   

2. Install the development version:

   • On Windows:

     install_dev.cmd
     

   • On Linux/macOS:

     ./install_dev.sh
     

Usage

OTVision provides several command-line scripts for different functionalities:

Video Conversion

Convert video files (e.g., h264 to mp4):

uv run convert.py --paths /path/to/videos/*.h264 --input-fps 20.0 --rotation 0

Object Detection

Detect objects in videos:

uv run detect.py --paths /path/to/videos/*.mp4 --weights yolov8s

Object Tracking

Track detected objects:

uv run track.py --paths /path/to/detections/*.otdet

Coordinate Transformation

Transform pixel coordinates to UTM coordinates:

uv run transform.py --paths /path/to/tracks/*.ottrk --refpts-file /path/to/reference_points.json

Configuration

OTVision can be configured using a YAML configuration file. A default configuration is provided in user_config.otvision.yaml. You can specify a custom configuration file using the --config option:

uv run detect.py --config /path/to/custom_config.yaml

Documentation

For detailed documentation, visit:

• OTVision Documentation
• Getting Started Guide
• Requirements
• Installation Guide

Contributing

We appreciate your support in the form of both code and comments. Please have a look at the contribute section of the OpenTrafficCam documentation for guidelines on how to contribute to the project.

License

This software is licensed under the GPL-3.0 License.

Contact

• GitHub: https://github.com/OpenTrafficCam
• Email: team@opentrafficcam.org