# debopriya-ai/gesturesense- architecture

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

- Interactive diagram: https://gitdiagram.com/debopriya-ai/gesturesense-
- Repository: https://github.com/debopriya-ai/gesturesense-

## Overview

##### Project type and purpose
- GestureSense is a real‐time computer vision application (not a web or mobile stack).
- It uses classical image‐processing techniques (no deep learning) to detect and count fingers from a live webcam feed.

##### File structure
- Top‐level files:
- `main.py` – the entry point that initializes the webcam feed, runs the processing loop, and displays results.
- `utils.py` – contains geometric and contour‐analysis helper functions (adaptive thresholding, convex hull, cosine‐rule classifier).
- `assets/` – demo screenshots or GIFs (not involved at runtime).
- `Final_Project_MV*.ipynb` – Jupyter notebook for exploratory analysis or demonstration.
- Configuration files (none beyond LICENSE, README).

##### Key insights from README
- Tech stack: Python, OpenCV, NumPy.
- Pipeline stages: ROI segmentation → adaptive thresholding → contour detection → convex hull/defect analysis → cosine‐rule classification → GUI overlay.
- Goal: low‐latency, high‐accuracy real‐time performance (~30 FPS).

##### Main components and interactions
a. Input Component
- “Webcam / Video Capture”
- External dependency: OpenCV’s `cv2.VideoCapture`
b. Preprocessing Component
- ROI Selector (crop to hand region)
- Adaptive Thresholding (grayscale → binary mask)
c. Contour Analysis Component
- Contour Detector (findContours)
- Contour Filter (select largest hand contour)
d. Feature Extraction Component
- Convex Hull Calculator
- Convexity Defect Analyzer
- Cosine‐Rule Finger Classifier
e. Output / Rendering Component
- Window (OpenCV GUI)
f. Utilities Module
- Shared functions from `utils.py`
g. External Libraries
- OpenCV, NumPy

##### Relationships & data flow
Webcam → Preprocessing → Contour Analysis → Feature Extraction → Output/Rendering → Display
- Utilities module should be depicted as a side component that each processing stage calls into.
- External libraries at the bottom or side, showing that each main block depends on OpenCV/NumPy.

##### Architectural patterns & design principles
- Pipeline pattern: sequential data transformations.
- Single‐process, in‐memory communication (no microservices).
- Separation of concerns: `main.py` handles control flow; `utils.py` encapsulates pure functions.

##### Essential elements
- Component names and brief descriptions.
- I/O (webcam/display)
- Processing stages
- Helpers/utilities
- External dependencies
- Annotations for performance targets (e.g., “30 FPS”) and any hardware considerations (e.g., CPU usage).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Control
    Main["main.py\n(Control Flow Loop)"]:::util

    %% Pipeline
    Main --> Webcam
    Webcam["Webcam / Video Capture\n(cv2.VideoCapture)"]:::io
    Webcam --> Preproc
    Preproc["Preprocessing\nROI Selector\nAdaptiveThreshold\n(cv2.adaptiveThreshold)"]:::process
    Preproc --> Contour
    Contour["Contour Analysis\nfindContours\nFilter Largest Contour"]:::process
    Contour --> Feature
    Feature["Feature Extraction\nConvexHull\nConvexity Defects\nCosine-Rule Classifier"]:::process
    Feature --> Render
    Render["Rendering\nOverlay Drawer\nDisplay Window"]:::io
    Render -->|Loop for 30 FPS| Main

    %% Utilities and External
    subgraph "Supporting Modules"
        Utils["utils.py\n(Geometric & Contour Helpers)"]:::util
        ExtLibs["External Libraries\nOpenCV, NumPy"]:::ext
    end

    Preproc -.-> Utils
    Contour -.-> Utils
    Feature -.-> Utils
    Render -.-> Utils

    Preproc -.-> ExtLibs
    Contour -.-> ExtLibs
    Feature -.-> ExtLibs
    Render -.-> ExtLibs
    Webcam -.-> ExtLibs

    %% Documentation
    subgraph "Project Documentation"
        Notebook["Exploratory Analysis & Demo\nFinal_Project_MV (1).ipynb"]:::docs
        Readme["Project Documentation\nREADME.md"]:::docs
        License["License Information\nLICENSE"]:::docs
    end

    %% Click Events
    click Notebook "https://github.com/debopriya-ai/gesturesense-/blob/main/Final_Project_MV (1).ipynb"
    click Readme "https://github.com/debopriya-ai/gesturesense-/blob/main/README.md"
    click License "https://github.com/debopriya-ai/gesturesense-/tree/main/LICENSE"

    %% Styles
    classDef io fill:#8FBC8F,stroke:#333,stroke-width:1px
    classDef process fill:#87CEFA,stroke:#333,stroke-width:1px
    classDef util fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef ext fill:#E6E6FA,stroke:#333,stroke-width:1px
    classDef docs fill:#FFD700,stroke:#333,stroke-width:1px
```
