# habom2310/heart-rate-measurement-using-camera architecture

> Architecture diagram of the GitHub repository habom2310/heart-rate-measurement-using-camera, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/habom2310/heart-rate-measurement-using-camera
- Repository: https://github.com/habom2310/heart-rate-measurement-using-camera

## Overview

##### Project type and purpose
- This is a standalone real-time computer-vision application (Python) for non-contact heart-rate measurement using a webcam.

##### File structure
- Top-level scripts:
- GUI.py – main application entry point with live camera feed and controls
- webcam.py / video.py – camera capture modules
- face_detection.py, face_utilities.py – dlib/OpenCV face detector & landmark alignment
- signal_processing.py – buffer management, band-pass filter, FFT, BPM extraction
- amplify_color.py – Eulerian Video Magnification module for visualization
- graph_plot.py – static/real-time plotting utility
- process.py / interface.py – glue code or CLI interface
- new_update/ – refactored code, unit tests for utilities (face & signal processing)
- requirements.txt lists core libraries: numpy, scipy, OpenCV, dlib, matplotlib, tkinter or PySimpleGUI

##### README for additional insights
- Workflow summary:

a. Main components:
– Camera Input Module (webcam.py / video.py)
– Face Detection & Alignment Service (face_detection.py + shape_predictor models)
– Signal Processing Pipeline (signal_processing.py)
– FFT Analyzer & BPM Estimator
– Visualization Layer
- Real-time GUI (GUI.py)
- Graph Plotter (graph_plot.py)
– Configuration & Models (shape_predictor_*.dat)
b. Relationships & interactions:
– Unidirectional data flow: Camera → Face Detector → ROI Averager → Signal Processor → FFT → BPM → GUI/Plot/Amplifier
– Shared resources: data buffer, model files, config parameters from requirements
c. Architectural patterns & design principles:
– Modular pipeline: each stage is a stateless function or class
– Separation of concerns: detection, processing, visualization decoupled
– Pluggable modules: amplify_color and graph_plot can be invoked independently
– Unit-testable components in new_update/
d. Key technologies/frameworks:
– OpenCV + dlib for computer vision
– NumPy/SciPy for numerical processing and FFT
– Matplotlib or PySimpleGUI/Tkinter for UI and plotting
– Python packaging via requirements.txt

##### Detail without over-complicating
- Python script or logical service as its own node.
- Two uses of .dat model files (5- and 68-point predictors).
- Buffer size (150 frames) as a queue between ROI and filter.
- Configuration (filter band, sampling rate) alongside the signal processor.
- A Testing module that references new_update/test_*.py to show unit-test coverage.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Processing Pipeline"
        style Processing Pipeline fill:#f9f9f9,stroke:#333,stroke-width:1px
        Camera["Camera Input Module"]:::cv
        FaceDet["Face Detection & Alignment"]:::cv
        ROI["ROI Extraction & Color Averager"]:::cv
        Queue["Frame Buffer<br/>(150 frames)"]:::misc
        Signal["Signal Processing"]:::sig
        FFT["FFT Analyzer & BPM Estimator"]:::sig
    end

    Camera --> FaceDet
    FaceDet --> ROI
    ROI --> Queue
    Queue --> Signal
    Signal --> FFT

    subgraph "Visualization Components"
        GUI["Real-time GUI"]:::viz
        Graph["Graph Plotter"]:::viz
        Amplify["Eulerian Video Magnification"]:::viz
    end

    FFT --> GUI
    FFT --> Graph
    FFT -.-> Amplify

    subgraph "Auxiliary Interfaces & Config"
        CLI["CLI / Glue Interface"]:::misc
        Config["requirements.txt"]:::misc
    end

    CLI --> GUI
    CLI --> Graph

    subgraph "Resources"
        Model5["shape_predictor_5_face_landmarks.dat"]:::misc
        Model68["shape_predictor_68_face_landmarks.dat"]:::misc
    end

    FaceDet --> Model5
    FaceDet --> Model68

    subgraph "Test Harness"
        NU_FaceMod["new_update/face_utilities.py"]:::test
        NU_SigMod["new_update/signal_processing.py"]:::test
        NU_FaceTest["new_update/test_face_utilities.py"]:::test
        NU_SigTest["new_update/test_signal_processing.py"]:::test
    end

    NU_FaceTest --> NU_FaceMod
    NU_SigTest --> NU_SigMod

    %% Click Events
    click Camera "https://github.com/habom2310/heart-rate-measurement-using-camera/blob/master/webcam.py"
    click Camera "https://github.com/habom2310/heart-rate-measurement-using-camera/blob/master/video.py"
    click FaceDet "https://github.com/habom2310/heart-rate-measurement-using-camera/blob/master/face_detection.py"
    click Model5 "https://github.com/habom2310/heart-rate-measurement-using-camera/blob/master/shape_predictor_5_face_landmarks.dat"
    click Model68 "https://github.com/habom2310/heart-rate-measurement-using-camera/blob/master/shape_predictor_68_face_landmarks.dat"
    click ROI "https://github.com/habom2310/heart-rate-measurement-using-camera/blob/master/face_utilities.py"
    click Signal "https://github.com/habom2310/heart-rate-measurement-using-camera/blob/master/signal_processing.py"
    click Amplify "https://github.com/habom2310/heart-rate-measurement-using-camera/blob/master/amplify_color.py"
    click GUI "https://github.com/habom2310/heart-rate-measurement-using-camera/blob/master/GUI.py"
    click Graph "https://github.com/habom2310/heart-rate-measurement-using-camera/blob/master/graph_plot.py"
    click CLI "https://github.com/habom2310/heart-rate-measurement-using-camera/blob/master/interface.py"
    click CLI "https://github.com/habom2310/heart-rate-measurement-using-camera/blob/master/process.py"
    click Config "https://github.com/habom2310/heart-rate-measurement-using-camera/blob/master/requirements.txt"
    click NU_FaceMod "https://github.com/habom2310/heart-rate-measurement-using-camera/blob/master/new_update/face_utilities.py"
    click NU_SigMod "https://github.com/habom2310/heart-rate-measurement-using-camera/blob/master/new_update/signal_processing.py"
    click NU_FaceTest "https://github.com/habom2310/heart-rate-measurement-using-camera/blob/master/new_update/test_face_utilities.py"
    click NU_SigTest "https://github.com/habom2310/heart-rate-measurement-using-camera/blob/master/new_update/test_signal_processing.py"

    %% Styles
    classDef cv fill:#cce5ff,stroke:#1f77b4,stroke-width:1px
    classDef sig fill:#ccffcc,stroke:#2ca02c,stroke-width:1px
    classDef viz fill:#ffe5cc,stroke:#ff7f0e,stroke-width:1px
    classDef misc fill:#f0f0f0,stroke:#888888,stroke-width:1px
    classDef test fill:#f9e6ff,stroke:#9467bd,stroke-width:1px
    classDef optional stroke-dasharray: 5 5,stroke:#ff7f0e,fill:#ffe5cc,stroke-width:1px

    class Amplify optional
```
