# abhijitshukla/spinvision architecture

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

- Interactive diagram: https://gitdiagram.com/abhijitshukla/spinvision
- Repository: https://github.com/abhijitshukla/spinvision

## Overview

##### Project Type and Purpose
- This is a data-processing pipeline (computer-vision) application written in Python. Its goal is to take an input cricket video, detect the ball’s frame-by-frame position, simulate a no-spin trajectory from the bounce point, and overlay actual vs. predicted paths to estimate spin deviation.

##### File Structure Analysis
Top-level scripts and folders reveal a clear, linear pipeline:
- coord.py      → Detection step using a YOLOv8 model
- predict.py    → Physics-based trajectory simulation (no spin)
- overlay.py    → Visualization & video output
- model/        → Contains the pre-trained YOLOv8 detector (.pt)
- videos/       → Raw input videos
- coordinates/  → Intermediate coordinate files (actual & predicted)
- output/       → Final overlay videos & snapshots
- results/      → Example outputs for reference

##### Key Components
a. Input Source
- “videos/” directory (e.g., kohli.mp4)
b. Detection Module
- coord.py
- YOLOv8 model (model/cricket_ball_detector.pt)
- Output: coordinates/coordinates.txt
c. Bounce & Physics Module
- predict.py
- Reads coordinates.txt, computes post-bounce trajectory without spin
- Output: coordinates/coordinates_no_spin.txt
d. Visualization Module
- overlay.py
- Reads both coordinate files + input video
- Renders green (actual) vs. red (predicted) trajectories
- Outputs overlay_output.mp4 & snapshot_with_spin_angle.png
e. Data Stores
- coordinates/
- output/
- results/ (for reference)
f. External Dependencies
- Python runtime, OpenCV, YOLOv8 framework, NumPy, etc.

##### Relationships and Data Flow
- Feedback loops for parameter tuning or reruns

##### Architectural Patterns & Principles
- Pipeline/Batch-processing pattern
- Separation of concerns: detection, simulation, visualization in distinct scripts
- Intermediate, filesystem-based data passing (coordinate text files)
- Reproducibility: clear inputs/outputs for each stage

## Diagram (Mermaid)

```mermaid
flowchart TD
    videos["videos/"]:::input
    subgraph "Detection Stage"
        coord["coord.py"]:::detection
        model["YOLOv8 .pt"]:::model
    end
    subgraph "Prediction Stage"
        predict["predict.py"]:::simulation
    end
    subgraph "Visualization Stage"
        overlay["overlay.py"]:::visualization
    end
    coords_txt["coordinates/coordinates.txt"]:::datastore
    coords_no_spin["coordinates/coordinates_no_spin.txt"]:::datastore
    output_vid["output/overlay_output.mp4"]:::datastore
    results["results/"]:::reference

    videos -->|"raw video (.mp4)"| coord
    model -->|"loads model"| coord
    coord -->|".txt"| coords_txt
    coords_txt -->|"coords.txt"| predict
    predict -->|"coords_no_spin.txt"| coords_no_spin
    videos -->|"input video"| overlay
    coords_txt -->|"actual coords"| overlay
    coords_no_spin -->|"predicted coords"| overlay
    overlay -->|"overlay video (.mp4)"| output_vid

    click videos "https://github.com/abhijitshukla/spinvision/tree/main/videos/"
    click coord "https://github.com/abhijitshukla/spinvision/blob/main/coord.py"
    click predict "https://github.com/abhijitshukla/spinvision/blob/main/predict.py"
    click overlay "https://github.com/abhijitshukla/spinvision/blob/main/overlay.py"
    click coords_txt "https://github.com/abhijitshukla/spinvision/tree/main/coordinates/"
    click coords_no_spin "https://github.com/abhijitshukla/spinvision/tree/main/coordinates/"
    click output_vid "https://github.com/abhijitshukla/spinvision/tree/main/output/"
    click results "https://github.com/abhijitshukla/spinvision/tree/main/results/"

    classDef input fill:#E0F7FA,stroke:#006064,color:#006064,stroke-width:2px;
    classDef detection fill:#BBDEFB,stroke:#0D47A1,color:#0D47A1,stroke-width:2px;
    classDef model fill:#F3E5F5,stroke:#4A148C,color:#4A148C,stroke-width:2px,stroke-dasharray: 5 5;
    classDef simulation fill:#FFE0B2,stroke:#E65100,color:#E65100,stroke-width:2px;
    classDef visualization fill:#C8E6C9,stroke:#1B5E20,color:#1B5E20,stroke-width:2px;
    classDef datastore fill:#CFD8DC,stroke:#37474F,color:#37474F,stroke-width:2px,stroke-dasharray: 2 2;
    classDef reference fill:#F5F5F5,stroke:#9E9E9E,color:#9E9E9E,stroke-width:2px,stroke-dasharray: 4 2;
```
