Skip to content

README.md

Latest commit

 

History

History
161 lines (118 loc) · 6.38 KB

README.md

File metadata and controls

161 lines (118 loc) · 6.38 KB
Raw

Vehicle Tracking, Counting, and Speed Estimation System

Python PyTorch License: MIT

Warning

Educational & Portfolio Purpose Only This project was created for college students when I was working as a freelancer. This is not purposed for commercial use or production. It is maintained strictly for educational and portfolio presentation purposes.

A high-performance real-time computer vision system that tracks, classifies, and estimates the speed of vehicles passing through a defined region. The application leverages YOLOv5 for high-accuracy object detection and DeepSORT for robust multi-object tracking.

🌟 Features

  • Multi-Class Vehicle Tracking: Tracks and classifies cars, motorcycles, trucks, and buses.
  • Directional Counters: Distinct counters for vehicles traveling in opposite directions (UP and DOWN).
  • Speed Estimation: Estimates velocity in real-time in KM/H based on frame timing and configurable reference distances.
  • Dual Operation Modes:
    • Interactive Tkinter GUI: Easy-to-use graphical interface to load files and initiate tracking.
    • Headless CLI Command: Production-ready, fully configurable console script suitable for containerized and automated workloads.
  • High-Performance Rendering: Draws object bounding boxes, tracking paths, speed labels, and a premium telemetry dashboard HUD on the output video.

📊 Telemetry and Statistics

Below is an analytical graph of class-wise vehicle counts processed during traffic tracking validation:

Vehicle Tracking Statistics Chart

🏗️ Architecture

graph TD
    A[Video/Camera Input] --> B[Frame Processing Dataloader]
    B --> C[YOLOv5 Detector]
    C --> D[Non-Maximum Suppression]
    D --> E[DeepSORT Tracker]
    E --> F[Feature Extraction & ID Assignment]
    F --> G[Speed & Direction Processor]
    G --> H[Telemetry Dashboard & HUD Rendering]
    H --> I[Output Window / Saved Video]
Loading

Folder Structure

  • detect.py: Core CLI detection and business logic.
  • main.py: Tkinter GUI entrypoint.
  • yolov5/: Sub-folder housing the YOLOv5 architecture and utility scripts.
  • deep_sort_pytorch/: Sub-folder housing DeepSORT tracker algorithms and deep feature models.
  • deep_sort_pytorch/configs/deep_sort.yaml: Primary configuration variables (line coordinates, distances, thresholds).

🛠️ Technologies

  • Core: Python 3.8+
  • Deep Learning: PyTorch, torchvision, YOLOv5
  • Computer Vision: OpenCV (Open Source Computer Vision Library)
  • Tracking: DeepSORT (Simple Online and Realtime Tracking with a Deep Association Metric)
  • GUI Framework: Tkinter

🚀 Installation & Setup

Local Setup

  1. Clone & Open the Directory:

    cd "e:/ALL Projects/vehicle tracking and counting"

  2. Install Dependencies: It is recommended to use a virtual environment:

    python -m venv venv
venv\Scripts\activate  # On Windows
pip install -r requirements.txt

  3. Download Model Weights: The YOLOv5 and DeepSORT weights are downloaded automatically on first run. If you prefer to download them manually, place:

    • YOLOv5 weights (yolov5s.pt) under yolov5/
    • DeepSORT checkpoint (ckpt.t7) under deep_sort_pytorch/deep_sort/deep/checkpoint/

Docker Setup

For headless environments (servers, CLI-based batch runs):

  1. Build the Container:

    docker build -t vehicle-detector .

  2. Run Inference on a Video: Map your output directories to persist processed outputs:

    docker run -v ${PWD}/inference:/app/inference vehicle-detector --source yolov5/Traffic - 27260.mp4 --device cpu --save-vid

Or via Docker Compose:

docker-compose up

⚙️ Configuration

Telemetry and tracking limits are configured in deep_sort_pytorch/configs/deep_sort.yaml:

Variable Description Default
UPPER Upper reference distance marker (meters) for speed calculation. 50
LOWER Lower reference distance marker (meters) for speed calculation. 45
LINE Horizontal detection line crossing threshold (y-coordinate). 450
UPLIMIT Y-coordinate limit above which tracks are ignored. 350
DOWNLIMIT Y-coordinate limit below which tracks are ignored. 650
SAVE_VID Enable saving of annotated output videos. True

💻 Usage

Launch Interactive GUI

To start the application GUI where you can select videos interactively:

python main.py

Launch CLI Mode

To run tracking on a specific video source:

python detect.py --source yolov5/Traffic - 27260.mp4 --device cpu --show-vid --save-vid

CLI Command Options:

  • --yolo_weights: Path to YOLOv5 model weights.
  • --source: Input source (e.g. video file, webcam index 0, or RTSP feed).
  • --device: Hardware device (cpu or CUDA index e.g., 0).
  • --show-vid: Displays real-time window output frame by frame.
  • --save-vid: Saves output video to inference/output.
  • --track: Renders visual history paths.

🔍 Troubleshooting

  • Missing C++ Build Tools on Windows: If thop or other package building fails, install Microsoft Visual C++ Build Tools.
  • Tkinter DPI Scale Error: DPI resolution setting fails on non-Windows/Linux CLI platforms. The app automatically catches this and falls back to a standard resolution grid (1280x720).
  • OpenCV GUI Errors: When running in headless docker, GUI window displays (cv2.imshow) are disabled. Ensure --show-vid is not passed when running in Docker or without a display.

📄 License

Distributed under the MIT License. See LICENSE for details.