# lancercrack25/fingers-hand-detector architecture

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

- Interactive diagram: https://gitdiagram.com/lancercrack25/fingers-hand-detector
- Repository: https://github.com/lancercrack25/fingers-hand-detector

## Overview

##### Project type and purpose
- This is a standalone real-time computer vision application written in Python.
- Its goal is to capture live video, detect hands and fingers (using MediaPipe Hands), count and identify which fingers are raised, recognize basic hand gestures, and overlay results on the video.

##### File structure
- Top level:
- README.md – project overview, libraries, usage
- program.py – core application script
- Results/… – sample output videos
- There are no distinct frontend/backend modules or microservices—everything runs inside one Python process.

##### README for additional insights
- Libraries: OpenCV (cv2) for capture and image processing, MediaPipe for the hand-landmarks model, NumPy/math for calculations.
- Workflow described: capture → landmark detection → finger state calculation → gesture classification → display.

##### Main components
a. Video Input
- Hardware camera or video feed
- Captured via cv2.VideoCapture
b. Preprocessing Module
c. MediaPipe Hands Model
- Pretrained ML model loaded via mediapipe.solutions.hands
- Outputs 21 hand landmarks per detected hand
d. Landmark Processor
- Receives raw landmarks
- Applies geometric rules (using NumPy/math) to determine which fingers are up
e. Gesture Recognizer
- Maps combinations of raised fingers to named gestures (paz, puño, dedo grosero, mano abierta)
f. Output Renderer
- Draws landmarks, counts, labels on frames via OpenCV drawing functions
- Displays or records video stream (Results/ folder)

##### Relationships and data flow
- Preprocessing → MediaPipe Hands Model
- Model → Landmark Processor
- Landmark Processor → Gesture Recognizer
- Gesture Recognizer → Output Renderer
- Output Renderer → Display/Save

##### Architectural pattern & principles
- Pipeline (stream processing) pattern: linear stages that process each video frame in sequence.
- Single-process, modular stages for clarity and easy debugging.
- Separation of concerns: capture, ML inference, post-processing, and rendering are distinct.

##### Detail level
- Six pipeline stages above.
- Do not break down individual OpenCV or NumPy calls further—group them into logical modules.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Python Application"
        direction TB
        VideoInput["Video Capture\n(cv2.VideoCapture)"]:::io
        Preprocess["Preprocessing\n(Resize, BGR→RGB)"]:::processing
        Model["MediaPipe Hands Model\n(mediapipe.solutions.hands)"]:::inference
        Landmark["Landmark Processor\n(NumPy, math)"]:::processing
        Gesture["Gesture Recognizer\n(gesture mapping)"]:::processing
        Renderer["Output Renderer\n(cv2 drawing & display)"]:::io
    end

    MediaPipeLib["MediaPipe Library"]:::external
    Storage[(Saved MP4s\nResults/)]:::storage
    ProjectOverview["README.md\n(Project overview & deps)"]:::doc

    VideoInput --> Preprocess
    Preprocess --> Model
    Model --> Landmark
    Landmark --> Gesture
    Gesture --> Renderer
    Renderer --> Storage
    Model --> MediaPipeLib

    click VideoInput "https://github.com/lancercrack25/fingers-hand-detector/blob/master/program.py"
    click Preprocess "https://github.com/lancercrack25/fingers-hand-detector/blob/master/program.py"
    click Model "https://github.com/lancercrack25/fingers-hand-detector/blob/master/program.py"
    click Landmark "https://github.com/lancercrack25/fingers-hand-detector/blob/master/program.py"
    click Gesture "https://github.com/lancercrack25/fingers-hand-detector/blob/master/program.py"
    click Renderer "https://github.com/lancercrack25/fingers-hand-detector/blob/master/program.py"
    click Storage "https://github.com/lancercrack25/fingers-hand-detector/tree/master/Results/"
    click ProjectOverview "https://github.com/lancercrack25/fingers-hand-detector/blob/master/README.md"

    classDef io fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef processing fill:#FFA500,stroke:#333,stroke-width:1px
    classDef inference fill:#90EE90,stroke:#333,stroke-width:1px
    classDef storage fill:#FFE4B5,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef doc fill:#E0E0E0,stroke:#333,stroke-width:1px
```
