# armanlaliwala/real-time-hand-gesture-recognition-using-mediapipe-opencv architecture

> Architecture diagram of the GitHub repository armanlaliwala/real-time-hand-gesture-recognition-using-mediapipe-opencv, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/armanlaliwala/real-time-hand-gesture-recognition-using-mediapipe-opencv
- Repository: https://github.com/armanlaliwala/real-time-hand-gesture-recognition-using-mediapipe-opencv

## Overview

##### Project Type & Purpose
- This is a standalone real-time gesture recognition tool written in Python.
- It ingests a live video feed (webcam or external camera), detects hand landmarks via MediaPipe, classifies predefined gestures (👍, 👎, ✊), annotates frames with OpenCV, and records the output (H.264).

##### Main Components
a. Input Devices
- Webcam or external camera (DroidCam, Iriun).
b. Video Capture Module
- OpenCV’s VideoCapture API reads frames in real time.
c. Preprocessing
d. Hand Landmark Detection
- MediaPipe Hands pipeline extracts 21 landmark points per hand.
e. Gesture Classification Logic
- NumPy‐based rules compute relative positions to decide “Thumbs Up,” “Thumbs Down,” or “Fist.”
f. Annotation & Display
g. Video Encoding & Recording
- OpenCV VideoWriter encodes annotated frames using H.264 and writes to gesture_output.mp4.
h. Storage/Output
- Persisted file (gesture_output.mp4), demo notebook (code.ipynb), and example video (gesture_recognition_output.mp4).

##### Component Relationships & Data Flow
1 → 2 : “Camera Frame”
2 → 3 : “Raw Frame”
3 → 4 : “Preprocessed Frame”
4 → 5 : “Landmarks”
5 → 6 : “Gesture Label”
6 ↔ 2 : “Annotated Frame” (display loop)
6 → 7 : “Encoded Frame” → 8

##### Architectural Patterns & Design Principles
- Pipeline pattern: each module performs a discrete step on frame data.
- Single‐process, synchronous processing loop (capture → detect → classify → display/record).
- Extensibility point: classification logic can be extended with new rules or ML models.
- Separation of concerns: detection (MediaPipe) vs. classification (NumPy logic) vs. recording (OpenCV).

##### Relevant Technologies & Frameworks
- Python 3.8+
- MediaPipe 0.9+ (hand tracking)
- OpenCV 4.5+ (capture, drawing, encoding)
- NumPy (gesture rule logic)
- H.264 codec (VideoWriter)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Capture & Preprocessing
    subgraph "Capture & Preprocessing"
        direction TB
        Camera["Camera (Webcam / External)"]:::hardware
        VideoCapture["VideoCapture (OpenCV)"]:::process
        Preprocessing["Preprocessing (Resize, Color Convert)"]:::process
    end

    %% Detection & Classification
    subgraph "Detection & Classification"
        direction TB
        Detection["MediaPipe Hands (Python SDK)"]:::process
        Classification["Gesture Classification (NumPy Rules)"]:::process
        ExtModel["Custom Gesture Rules or ML Model"]:::ext
    end

    %% Annotation & Recording
    subgraph "Display & Recording"
        direction TB
        Annotation["Annotation & Display (OpenCV)"]:::process
        Recording["Video Encoding & Recording (H.264)"]:::process
    end

    %% Storage & Outputs
    subgraph "Storage & Outputs"
        direction TB
        OutputFile["gesture_output.mp4"]:::storage
        ExampleVideo["Example Output Video\n(gesture_recognition_output.mp4)"]:::storage
    end

    %% Documentation
    subgraph "Documentation & Configuration"
        direction TB
        DemoNotebook["Demo Notebook\n(code.ipynb)"]:::docs
        Readme["Project Overview\n(README.md)"]:::docs
        Requirements["Dependencies\n(requirements.txt)"]:::docs
    end

    %% Data Flow
    Camera -->|"Camera Frame"| VideoCapture
    VideoCapture -->|"Raw Frame"| Preprocessing
    Preprocessing -->|"Preprocessed Frame"| Detection
    Detection -->|"Landmarks"| Classification
    Classification -->|"Gesture Label"| Annotation
    Annotation -->|"Annotated Frame"| VideoCapture
    Annotation -->|"Annotated Frame"| Recording
    Recording -->|"H.264 Video"| OutputFile

    %% Extensibility
    Classification ---|"extends"| ExtModel

    %% Documentation Links
    DemoNotebook -.-> VideoCapture
    DemoNotebook -.-> Recording

    %% Example Video Link
    ExampleVideo -.-> Annotation

    %% Click Events
    click DemoNotebook "https://github.com/armanlaliwala/real-time-hand-gesture-recognition-using-mediapipe-opencv/blob/main/code.ipynb"
    click Readme "https://github.com/armanlaliwala/real-time-hand-gesture-recognition-using-mediapipe-opencv/blob/main/README.md"
    click Requirements "https://github.com/armanlaliwala/real-time-hand-gesture-recognition-using-mediapipe-opencv/blob/main/requirements.txt"
    click ExampleVideo "https://github.com/armanlaliwala/real-time-hand-gesture-recognition-using-mediapipe-opencv/blob/main/gesture_recognition_output.mp4"

    %% Styles
    classDef hardware fill:#CCE5FF,stroke:#0275d8,color:#000
    classDef process fill:#D5F5E3,stroke:#28a745,color:#000
    classDef storage fill:#FDEBD0,stroke:#e67e22,color:#000
    classDef ext fill:#F9E79F,stroke:#f1c40f,color:#000,stroke-dasharray: 5 5
    classDef docs fill:#E8DAEF,stroke:#8e44ad,color:#000,stroke-dasharray: 2 2
```
