# shukkkur/volleyvision architecture

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

- Interactive diagram: https://gitdiagram.com/shukkkur/volleyvision
- Repository: https://github.com/shukkkur/volleyvision

## Overview

VolleyVision is a volleyball-video computer-vision project organized as three stages: ball detection/tracking, player and action recognition, and court detection. The documented goal includes tracking and game statistics, but the README says statistics and deployment were not completed. Stage I’s sampled code shows video inference and ball-box postprocessing; Stage II and III connections are limited to documented capabilities because their source was not excerpted. The model and utility layer is represented without implying that the stages form an implemented end-to-end pipeline.

Main entry points: [`Stage I - Volleyball/models/yolo.py`](https://github.com/shukkkur/volleyvision/blob/main/Stage%20I%20-%20Volleyball/models/yolo.py) (YOLO Model), [`Stage I - Volleyball/utils/general.py`](https://github.com/shukkkur/volleyvision/blob/main/Stage%20I%20-%20Volleyball/utils/general.py) (Detection Utilities), [`Stage I - Volleyball/detect.py`](https://github.com/shukkkur/volleyvision/blob/main/Stage%20I%20-%20Volleyball/detect.py) (Ball Inference), [`Stage I - Volleyball/models/experimental.py`](https://github.com/shukkkur/volleyvision/blob/main/Stage%20I%20-%20Volleyball/models/experimental.py) (Model Variants)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ball["Ball Detection & Tracking"]
  node_ball_app["Ball Inference<br/>[detect.py]"]
  node_ball_helpers["Ball Helpers<br/>[my_utils.py]"]
  node_tracker["Ball Tracking<br/>[volley_track.py]"]
end

subgraph group_runtime["YOLO Runtime"]
  node_yolo_model["YOLO Model<br/>[yolo.py]"]
  node_model_layers["Model Layers<br/>[common.py]"]
  node_model_variants["Model Variants<br/>[experimental.py]"]
  node_video_data["Video &amp; Datasets<br/>[datasets.py]"]
  node_general_utils["Detection Utilities<br/>[general.py]"]
  node_training_loss["Training Losses<br/>[loss.py]"]
  node_training_metrics["Validation Metrics<br/>[metrics.py]"]
  node_training_plots["Training Plots<br/>[plots.py]"]
  node_device_utils["Device Utilities<br/>[torch_utils.py]"]
  node_anchor_utils["Anchor Utilities<br/>[autoanchor.py]"]
  node_google_utils["Download Utilities<br/>[google_utils.py]"]
  node_wandb_logging["W&amp;B Logging<br/>[wandb_utils.py]"]
end

subgraph group_players["Players &amp; Actions"]
  node_players_app["Player &amp; Action Detection<br/>[main.py]"]
  node_action_filter["Temporal Filtering<br/>[sliding_wndow.py]"]
  node_action_filter_verbose["Verbose Filtering"]
end

subgraph group_court["Court Detection"]
  node_court_app["Court Detection<br/>[court_detect.py]"]
end

node_video(("Volleyball Video"))
node_roboflow["Roboflow Model"]

node_video -->|"supplies frames"| node_ball_app
node_ball_app -->|"uses helpers"| node_ball_helpers
node_ball_app -.->|"queries optionally"| node_roboflow
node_ball_helpers -->|"constructs model"| node_yolo_model
node_tracker -->|"uses helpers"| node_ball_helpers
node_yolo_model -->|"uses layers"| node_model_layers
node_yolo_model -->|"uses variants"| node_model_variants
node_yolo_model -->|"uses losses"| node_training_loss
node_yolo_model -->|"uses utilities"| node_device_utils
node_yolo_model -->|"uses utilities"| node_general_utils
node_yolo_model -->|"checks anchors"| node_anchor_utils
node_model_variants -->|"imports layers"| node_model_layers
node_model_variants -->|"downloads weights"| node_google_utils
node_video_data -->|"uses utilities"| node_general_utils
node_general_utils -->|"uses utilities"| node_device_utils
node_general_utils -->|"uses metrics"| node_training_metrics
node_training_plots -->|"uses utilities"| node_general_utils
node_training_plots -->|"uses metrics"| node_training_metrics
node_wandb_logging -->|"loads datasets"| node_video_data
node_wandb_logging -->|"uses utilities"| node_general_utils
node_video -.->|"input documented"| node_players_app
node_players_app -.->|"temporal filtering"| node_action_filter
node_players_app -.->|"filtering variant"| node_action_filter_verbose
node_video -.->|"input documented"| node_court_app

click node_ball_app "https://github.com/shukkkur/volleyvision/blob/main/Stage%20I%20-%20Volleyball/detect.py"
click node_ball_helpers "https://github.com/shukkkur/volleyvision/blob/main/Stage%20I%20-%20Volleyball/my_utils.py"
click node_tracker "https://github.com/shukkkur/volleyvision/blob/main/Stage%20I%20-%20Volleyball/volley_track.py"
click node_yolo_model "https://github.com/shukkkur/volleyvision/blob/main/Stage%20I%20-%20Volleyball/models/yolo.py"
click node_model_layers "https://github.com/shukkkur/volleyvision/blob/main/Stage%20I%20-%20Volleyball/models/common.py"
click node_model_variants "https://github.com/shukkkur/volleyvision/blob/main/Stage%20I%20-%20Volleyball/models/experimental.py"
click node_video_data "https://github.com/shukkkur/volleyvision/blob/main/Stage%20I%20-%20Volleyball/utils/datasets.py"
click node_general_utils "https://github.com/shukkkur/volleyvision/blob/main/Stage%20I%20-%20Volleyball/utils/general.py"
click node_training_loss "https://github.com/shukkkur/volleyvision/blob/main/Stage%20I%20-%20Volleyball/utils/loss.py"
click node_training_metrics "https://github.com/shukkkur/volleyvision/blob/main/Stage%20I%20-%20Volleyball/utils/metrics.py"
click node_training_plots "https://github.com/shukkkur/volleyvision/blob/main/Stage%20I%20-%20Volleyball/utils/plots.py"
click node_device_utils "https://github.com/shukkkur/volleyvision/blob/main/Stage%20I%20-%20Volleyball/utils/torch_utils.py"
click node_anchor_utils "https://github.com/shukkkur/volleyvision/blob/main/Stage%20I%20-%20Volleyball/utils/autoanchor.py"
click node_google_utils "https://github.com/shukkkur/volleyvision/blob/main/Stage%20I%20-%20Volleyball/utils/google_utils.py"
click node_wandb_logging "https://github.com/shukkkur/volleyvision/blob/main/Stage%20I%20-%20Volleyball/utils/wandb_logging/wandb_utils.py"
click node_players_app "https://github.com/shukkkur/volleyvision/blob/main/Stage%20II%20-%20Players%20%26%20Actions/main.py"
click node_action_filter "https://github.com/shukkkur/volleyvision/blob/main/Stage%20II%20-%20Players%20%26%20Actions/sliding_wndow.py"
click node_action_filter_verbose "https://github.com/shukkkur/volleyvision/blob/main/Stage%20II%20-%20Players%20%26%20Actions/sliding_window_verbose.py"
click node_court_app "https://github.com/shukkkur/volleyvision/blob/main/Stage%20III%20-%20Court%20Detection/court_detect.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ball_app,node_ball_helpers,node_tracker toneBlue
class node_yolo_model,node_model_layers,node_model_variants,node_video_data,node_general_utils,node_training_loss,node_training_metrics,node_training_plots,node_device_utils,node_anchor_utils,node_google_utils,node_wandb_logging toneAmber
class node_players_app,node_action_filter,node_action_filter_verbose toneMint
class node_court_app toneRose
class node_video,node_roboflow toneIndigo
```

## Components

### Ball Detection & Tracking

- [Ball Inference](https://github.com/shukkkur/volleyvision/blob/main/Stage%20I%20-%20Volleyball/detect.py): `Stage I - Volleyball/detect.py`
- [Ball Helpers](https://github.com/shukkkur/volleyvision/blob/main/Stage%20I%20-%20Volleyball/my_utils.py): `Stage I - Volleyball/my_utils.py`
- [Ball Tracking](https://github.com/shukkkur/volleyvision/blob/main/Stage%20I%20-%20Volleyball/volley_track.py): `Stage I - Volleyball/volley_track.py`

### YOLO Runtime

- [YOLO Model](https://github.com/shukkkur/volleyvision/blob/main/Stage%20I%20-%20Volleyball/models/yolo.py): `Stage I - Volleyball/models/yolo.py`
- [Model Layers](https://github.com/shukkkur/volleyvision/blob/main/Stage%20I%20-%20Volleyball/models/common.py): `Stage I - Volleyball/models/common.py`
- [Model Variants](https://github.com/shukkkur/volleyvision/blob/main/Stage%20I%20-%20Volleyball/models/experimental.py): `Stage I - Volleyball/models/experimental.py`
- [Video & Datasets](https://github.com/shukkkur/volleyvision/blob/main/Stage%20I%20-%20Volleyball/utils/datasets.py): `Stage I - Volleyball/utils/datasets.py`
- [Detection Utilities](https://github.com/shukkkur/volleyvision/blob/main/Stage%20I%20-%20Volleyball/utils/general.py): `Stage I - Volleyball/utils/general.py`
- [Training Losses](https://github.com/shukkkur/volleyvision/blob/main/Stage%20I%20-%20Volleyball/utils/loss.py): `Stage I - Volleyball/utils/loss.py`
- [Validation Metrics](https://github.com/shukkkur/volleyvision/blob/main/Stage%20I%20-%20Volleyball/utils/metrics.py): `Stage I - Volleyball/utils/metrics.py`
- [Training Plots](https://github.com/shukkkur/volleyvision/blob/main/Stage%20I%20-%20Volleyball/utils/plots.py): `Stage I - Volleyball/utils/plots.py`
- [Device Utilities](https://github.com/shukkkur/volleyvision/blob/main/Stage%20I%20-%20Volleyball/utils/torch_utils.py): `Stage I - Volleyball/utils/torch_utils.py`
- [Anchor Utilities](https://github.com/shukkkur/volleyvision/blob/main/Stage%20I%20-%20Volleyball/utils/autoanchor.py): `Stage I - Volleyball/utils/autoanchor.py`
- [Download Utilities](https://github.com/shukkkur/volleyvision/blob/main/Stage%20I%20-%20Volleyball/utils/google_utils.py): `Stage I - Volleyball/utils/google_utils.py`
- [W&B Logging](https://github.com/shukkkur/volleyvision/blob/main/Stage%20I%20-%20Volleyball/utils/wandb_logging/wandb_utils.py): `Stage I - Volleyball/utils/wandb_logging/wandb_utils.py`

### Players & Actions

- [Player & Action Detection](https://github.com/shukkkur/volleyvision/blob/main/Stage%20II%20-%20Players%20%26%20Actions/main.py): `Stage II - Players & Actions/main.py`
- [Temporal Filtering](https://github.com/shukkkur/volleyvision/blob/main/Stage%20II%20-%20Players%20%26%20Actions/sliding_wndow.py): `Stage II - Players & Actions/sliding_wndow.py`
- [Verbose Filtering](https://github.com/shukkkur/volleyvision/blob/main/Stage%20II%20-%20Players%20%26%20Actions/sliding_window_verbose.py): `Stage II - Players & Actions/sliding_window_verbose.py`

### Court Detection

- [Court Detection](https://github.com/shukkkur/volleyvision/blob/main/Stage%20III%20-%20Court%20Detection/court_detect.py): `Stage III - Court Detection/court_detect.py`

### Other components

- **Volleyball Video**
- **Roboflow Model**

## Connections

- Volleyball Video → Ball Inference: supplies frames (evidence: `Stage I - Volleyball/detect.py`)
- Ball Inference → Ball Helpers: uses helpers (evidence: `Stage I - Volleyball/detect.py`)
- Ball Inference → Roboflow Model: queries optionally (evidence: `Stage I - Volleyball/detect.py`)
- Ball Helpers → YOLO Model: constructs model (evidence: `Stage I - Volleyball/my_utils.py`)
- Ball Tracking → Ball Helpers: uses helpers (evidence: `Stage I - Volleyball/volley_track.py`)
- YOLO Model → Model Layers: uses layers (evidence: `Stage I - Volleyball/models/yolo.py`)
- YOLO Model → Model Variants: uses variants (evidence: `Stage I - Volleyball/models/yolo.py`)
- YOLO Model → Training Losses: uses losses (evidence: `Stage I - Volleyball/models/yolo.py`)
- YOLO Model → Device Utilities: uses utilities (evidence: `Stage I - Volleyball/models/yolo.py`)
- YOLO Model → Detection Utilities: uses utilities (evidence: `Stage I - Volleyball/models/yolo.py`)
- YOLO Model → Anchor Utilities: checks anchors (evidence: `Stage I - Volleyball/models/yolo.py`)
- Model Variants → Model Layers: imports layers (evidence: `Stage I - Volleyball/models/experimental.py`)
- Model Variants → Download Utilities: downloads weights (evidence: `Stage I - Volleyball/models/experimental.py`)
- Video & Datasets → Detection Utilities: uses utilities (evidence: `Stage I - Volleyball/utils/datasets.py`)
- Detection Utilities → Device Utilities: uses utilities (evidence: `Stage I - Volleyball/utils/general.py`)
- Detection Utilities → Validation Metrics: uses metrics (evidence: `Stage I - Volleyball/utils/general.py`)
- Training Plots → Detection Utilities: uses utilities (evidence: `Stage I - Volleyball/utils/plots.py`)
- Training Plots → Validation Metrics: uses metrics (evidence: `Stage I - Volleyball/utils/plots.py`)
- W&B Logging → Video & Datasets: loads datasets (evidence: `Stage I - Volleyball/utils/wandb_logging/wandb_utils.py`)
- W&B Logging → Detection Utilities: uses utilities (evidence: `Stage I - Volleyball/utils/wandb_logging/wandb_utils.py`)
- Volleyball Video → Player & Action Detection: input documented (evidence: `README.md`)
- Player & Action Detection → Temporal Filtering: temporal filtering (evidence: `README.md`)
- Player & Action Detection → Verbose Filtering: filtering variant
- Volleyball Video → Court Detection: input documented (evidence: `README.md`)