# mchockalingam/computervision architecture

> Architecture diagram of the GitHub repository mchockalingam/computervision, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mchockalingam/computervision
- Repository: https://github.com/mchockalingam/computervision

## Overview

##### Project type and purpose
- This is a command-line Python application for video-based object detection, tracking and counting of vehicles.
- It uses Ultralytics YOLOv8 for detection, OpenCV for video I/O, Supervision (with ByteTrack under the hood) for tracking and annotation, and Numpy/TQDM for filtering and progress display.

##### File structure
- Top-level scripts
– app.py          → Main entry point: orchestrates video loading, detection, tracking, counting, annotation, and output
– model-names.py  → Utility to list class names from a YOLOv8 model
– run.sh, setup.sh → Shell scripts to bootstrap the environment and launch the application
- Supporting files
– requirements.txt → Python dependencies
– readme.md        → Project overview, usage, and configuration instructions
- No deep subdirectories; all core logic lives in app.py with imports from external libraries

##### Key insights from README
- Workflow: download or reference a video → read frames → detect vehicles → filter by class IDs → track across frames → count when crossing predefined line zones → annotate and write output video
- All configuration (model file path, class IDs, line coordinates) lives in app.py
- Dependencies: Ultralytics, OpenCV-Python, Supervision (and ByteTrack), Numpy, TQDM; optional yt-dl + ffmpeg for YouTube ingestion

##### Main components and interactions
a. Video Source
- Local video file OR YouTube via youtube-dl.py + ffmpeg
b. Frame Reader (OpenCV VideoCapture)
↓
c. Detection Module (YOLOv8 loaded via Ultralytics API)
- Inputs: frame
↓
d. Filter Module (NumPy)
- Keeps only selected vehicle classes (car, motorcycle, bus, truck)
↓
e. Tracking & Annotation (Supervision + ByteTrack)
- Assigns persistent IDs to objects
- Defines LineZone(s) for counting
- Counts when a tracked object crosses a line
↓
f. Video Writer (OpenCV or Supervision helper)
- Writes annotated frames to output file
g. Stats & Progress (TQDM)
- Displays processing progress and final counts

##### Architectural patterns and design principles
- Pipeline pattern: sequential processing of frames through modular stages
- Single responsibility: app.py coordinates modules; each library handles its domain (detection, tracking, I/O, annotation)
- Configurable constants: class IDs, line coordinates, model paths defined up-front for easy customization

##### Details not to miss
- Runtime environment setup (setup.sh → virtualenv & requirements.txt) feeding into app.py
- Configuration inputs: model file path, class ID array, line coordinates

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Setup Stage
    subgraph "Environment Setup"
        direction TB
        SetupScript["setup.sh"]:::util
        Requirements["requirements.txt"]:::util
        SetupScript -->|"installs dependencies from"| Requirements
    end

    %% Utility Files
    subgraph "Project Utilities"
        direction TB
        Readme["readme.md"]:::util
        License["LICENSE"]:::util
        Gitignore[".gitignore"]:::util
        ModelNames["model-names.py"]:::util
    end

    %% Launcher and Main Application
    RunScript["run.sh"]:::util
    RunScript -->|"launches"| App["app.py"]:::util

    %% Processing Pipeline
    subgraph "Processing Pipeline"
        direction TB
        VideoSource["Video Source\n(local file)"]:::io
        YouTube["YouTube Download\n(youtube-dl + ffmpeg)"]:::io
        VideoSource --> FrameReader["Frame Reader\n(OpenCV VideoCapture)"]:::io
        YouTube --> FrameReader

        FrameReader --> Detector["YOLOv8 Detector\n(Ultralytics)"]:::ml
        Detector --> Filter["Filter Module\n(NumPy)"]:::logic
        Filter --> Tracker["Tracking & Annotation\n(Supervision + ByteTrack)"]:::ml
        Tracker --> VideoWriter["Video Writer\n(OpenCV/Supervision)"]:::io

        %% Progress Sidecar
        TQDM["Stats & Progress\n(TQDM)"]:::util
        FrameReader --> TQDM
        Detector --> TQDM
        Filter --> TQDM
        Tracker --> TQDM
    end

    %% Configuration Inputs
    Config["Configuration Constants\n(model path, class IDs, line coords)"]:::util
    Config --> App
    App --> VideoSource

    %% File and Utility References
    App --> ModelNames
    App --> Readme

    %% Click Events
    click App "https://github.com/mchockalingam/computervision/blob/main/app.py"
    click ModelNames "https://github.com/mchockalingam/computervision/blob/main/model-names.py"
    click SetupScript "https://github.com/mchockalingam/computervision/blob/main/setup.sh"
    click Requirements "https://github.com/mchockalingam/computervision/blob/main/requirements.txt"
    click RunScript "https://github.com/mchockalingam/computervision/blob/main/run.sh"
    click Readme "https://github.com/mchockalingam/computervision/blob/main/readme.md"
    click License "https://github.com/mchockalingam/computervision/tree/main/LICENSE"
    click Gitignore "https://github.com/mchockalingam/computervision/blob/main/.gitignore"

    %% Styles
    classDef io fill:#D0E7FF,stroke:#005B9F,color:#000;
    classDef ml fill:#D5F5E3,stroke:#1D8348,color:#000;
    classDef logic fill:#FDEBD0,stroke:#D35400,color:#000;
    classDef util fill:#E5E7E9,stroke:#566573,color:#000;
```
