# chuphal-11/volleytrack architecture

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

- Interactive diagram: https://gitdiagram.com/chuphal-11/volleytrack
- Repository: https://github.com/chuphal-11/volleytrack

## Overview

##### Project type and purpose
- This is a computer-vision pipeline tool (“VolleyTrack”) for tracking volleyballs and players in video clips, with optional action-recognition overlays.
- It is delivered as a standalone Python application, invoked via scripts (`main.py` or `volleball.py`), processing input videos end-to-end.

##### File structure
- Top-level scripts:
- `main.py` – entry point
- `volleball.py` – main pipeline script
- Modules:
- `Tracker/` – tracking logic (`tracker.py`)
- `actions/` – action-recognition logic (`actions_reco.py`)
- `utils/` – helper utilities (`video_utils.py`, `bbox_utils.py`)
- Artifacts and assets:
- `mod/` – pre-trained model weights for action detection (`action_detection_3.pt`)
- `Tracking_history/` – serialized track histories (`*.pkl`)
- `assets/` – demo GIF/video
- `output/` – result videos

##### README for additional insights
- Confirms pipeline stages: video input → tracking → optional action detection → annotated output
- Mentions supported actions: serve, pass, spike, etc.
- Dependencies implied: OpenCV for video I/O, PyTorch for model inference, pickle for history storage.

##### Main components and their relationships
a. Components
1. Video Input (raw .mp4/.avi files)
2. Video Utilities (preprocessing, frame extraction, writing)
3. Tracker Module (object detection + data association)
4. Tracking History Store (serialize/deserialize tracks to `tracks.pkl`)
5. Action Recognition Module (loads `action_detection_3.pt` for serve/pass/spike)
7. Model Storage (weights in `mod/`)
b. Interactions
- Video Input → utils.video_utils → frames → Tracker
- Tracker → outputs per-frame detections → saved in Tracking History
- Tracker outputs + frames → optionally passed to Action Recognition
- Action Recognition → labels per detection → back to Output Generator
- Output Generator → annotated frames → video written to `output/`

##### Architectural patterns and principles
- Pipeline/flow pattern: linear, stage-by-stage processing
- Separation of concerns:
- `utils/` for generic helpers
- `Tracker/` solely for tracking logic
- `actions/` solely for classification logic
- Scripts orchestrate modules without embedding business logic
- Persistence layer: simple file store for track history (pickle)
- Model inference decoupled from tracking

##### Relevant technologies and frameworks
- Python 3.x
- OpenCV (cv2) for video I/O and drawing
- PyTorch for loading/running action-detection model
- pickle for serializing tracking histories

- All seven components clearly boxed and labeled
- A star or flag marking entry points (`main.py` / `volleball.py`)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Entry"
        MainPy["main.py"]:::entry
        VolPy["volleball.py"]:::entry
    end

    subgraph "Input/Preprocessing"
        VideoInput["Video Input (.mp4/.avi)"]:::io
        VideoUtils["Video Utilities"]:::pre
        BBoxUtils["BBox Utilities"]:::pre
    end

    subgraph "Core Processing"
        Tracker["Tracker Module"]:::core
        ActionReco["Action Recognition Module"]:::core
    end

    subgraph "Storage"
        TrackingHistory["Tracking History Store"]:::storage
        ModelStorage["Model Storage (action_detection_3.pt)"]:::storage
        OutputDir["output/"]:::storage
    end

    subgraph "Output"
        OutputGen["Output Generator"]:::output
    end

    MainPy --> VideoInput
    VolPy --> VideoInput
    VideoInput --> VideoUtils
    VideoUtils --> Tracker
    Tracker --> TrackingHistory
    Tracker -- optional --> ActionReco
    ModelStorage -->|"load weights"| ActionReco
    TrackingHistory --> OutputGen
    ActionReco --> OutputGen
    VideoUtils --> OutputGen
    OutputGen --> OutputDir

    click MainPy "https://github.com/chuphal-11/volleytrack/blob/main/main.py"
    click VolPy "https://github.com/chuphal-11/volleytrack/blob/main/volleball.py"
    click VideoUtils "https://github.com/chuphal-11/volleytrack/blob/main/utils/video_utils.py"
    click BBoxUtils "https://github.com/chuphal-11/volleytrack/blob/main/utils/bbox_utils.py"
    click Tracker "https://github.com/chuphal-11/volleytrack/blob/main/Tracker/tracker.py"
    click TrackingHistory "https://github.com/chuphal-11/volleytrack/blob/main/Tracking_history/tracks.pkl"
    click ActionReco "https://github.com/chuphal-11/volleytrack/blob/main/actions/actions_reco.py"
    click ModelStorage "https://github.com/chuphal-11/volleytrack/blob/main/mod/action_detection_3.pt"
    click OutputDir "https://github.com/chuphal-11/volleytrack/tree/main/output/"

    classDef io fill:#cff,stroke:#333,stroke-width:1px;
    classDef pre fill:#bbf,stroke:#333,stroke-width:1px;
    classDef core fill:#bfb,stroke:#333,stroke-width:1px;
    classDef storage fill:#ddd,stroke:#333,stroke-width:1px;
    classDef output fill:#fbe,stroke:#333,stroke-width:1px;
    classDef entry fill:#fbb,stroke:#333,stroke-width:1px;
```
