# bughht/realtime-rppg-application architecture

> Architecture diagram of the GitHub repository bughht/realtime-rppg-application, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bughht/realtime-rppg-application
- Repository: https://github.com/bughht/realtime-rppg-application

## Overview

This is a desktop webcam-based remote photoplethysmography application that estimates and displays heart rate from facial skin-color changes. The main workflow is webcam capture, landmark-based forehead/cheek ROI extraction, RGB feature buffering, selectable pulse-signal extraction, filtering and spectral BPM estimation, then confidence-weighted display. The README also documents four extraction methods and signal, spectrum, histogram, and ROI-mask views. Wiring is based on the README and sampled source; omitted source leaves some internal call details uncertain.

Main entry points: [`main.py`](https://github.com/bughht/realtime-rppg-application/blob/main/main.py) (Application window), [`face2series.py`](https://github.com/bughht/realtime-rppg-application/blob/main/face2series.py) (Capture and ROIs), [`series2rPPG.py`](https://github.com/bughht/realtime-rppg-application/blob/main/series2rPPG.py) (Signal processor), [`mainwindow.py`](https://github.com/bughht/realtime-rppg-application/blob/main/mainwindow.py) (Window controls)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Desktop interface"]
  node_app["Application window<br/>[main.py]"]
  node_ui["Window controls<br/>[mainwindow.py]"]
  node_plots["Live plots and readout<br/>[main.py]"]
end

subgraph group_capture["Face acquisition"]
  node_capture_roi["Capture and ROIs<br/>[face2series.py]"]
  node_face_model["Landmark model"]
  node_roi_features["ROI RGB features<br/>[face2series.py]"]
end

subgraph group_signal["Pulse processing"]
  node_processor["Signal processor<br/>[series2rPPG.py]"]
  node_green["GREEN method<br/>[series2rPPG.py]"]
  node_green_red["GREEN-RED method<br/>[series2rPPG.py]"]
  node_chrom["CHROM method<br/>[series2rPPG.py]"]
  node_pbv["PBV method<br/>[series2rPPG.py]"]
  node_preprocess["Detrend and filter<br/>[series2rPPG.py]"]
end

subgraph group_output["Heart-rate output"]
  node_spectrum["Spectrum and BPM<br/>[main.py]"]
  node_confidence["ROI confidence<br/>[main.py]"]
end

node_user(("Operator"))
node_webcam(("Webcam"))

node_user -->|"operates"| node_app
node_ui -->|"provides controls"| node_app
node_app -->|"starts processing"| node_processor
node_processor -->|"initializes capture"| node_capture_roi
node_webcam -->|"supplies frames"| node_capture_roi
node_capture_roi -->|"detects landmarks"| node_face_model
node_capture_roi -->|"extracts ROI features"| node_roi_features
node_roi_features -->|"provides buffered data"| node_app
node_app -->|"dispatches selection"| node_green
node_app -->|"dispatches selection"| node_green_red
node_app -->|"dispatches selection"| node_chrom
node_app -->|"dispatches selection"| node_pbv
node_app -->|"requests detrending"| node_preprocess
node_app -->|"filters and transforms"| node_spectrum
node_spectrum -->|"provides ROI BPM"| node_confidence
node_confidence -->|"weights and reports"| node_plots
node_app -->|"updates plots"| node_plots
node_plots -->|"displays results"| node_user

click node_app "https://github.com/bughht/realtime-rppg-application/blob/main/main.py"
click node_ui "https://github.com/bughht/realtime-rppg-application/blob/main/mainwindow.py"
click node_capture_roi "https://github.com/bughht/realtime-rppg-application/blob/main/face2series.py"
click node_face_model "https://github.com/bughht/realtime-rppg-application/blob/main/data/shape_predictor_81_face_landmarks.dat"
click node_roi_features "https://github.com/bughht/realtime-rppg-application/blob/main/face2series.py"
click node_processor "https://github.com/bughht/realtime-rppg-application/blob/main/series2rPPG.py"
click node_green "https://github.com/bughht/realtime-rppg-application/blob/main/series2rPPG.py"
click node_green_red "https://github.com/bughht/realtime-rppg-application/blob/main/series2rPPG.py"
click node_chrom "https://github.com/bughht/realtime-rppg-application/blob/main/series2rPPG.py"
click node_pbv "https://github.com/bughht/realtime-rppg-application/blob/main/series2rPPG.py"
click node_preprocess "https://github.com/bughht/realtime-rppg-application/blob/main/series2rPPG.py"
click node_spectrum "https://github.com/bughht/realtime-rppg-application/blob/main/main.py"
click node_confidence "https://github.com/bughht/realtime-rppg-application/blob/main/main.py"
click node_plots "https://github.com/bughht/realtime-rppg-application/blob/main/main.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_ui,node_plots toneBlue
class node_capture_roi,node_face_model,node_roi_features toneAmber
class node_processor,node_green,node_green_red,node_chrom,node_pbv,node_preprocess toneMint
class node_spectrum,node_confidence toneRose
class node_user,node_webcam toneIndigo
```

## Components

### Desktop interface

- [Application window](https://github.com/bughht/realtime-rppg-application/blob/main/main.py): `main.py`
- [Window controls](https://github.com/bughht/realtime-rppg-application/blob/main/mainwindow.py): `mainwindow.py`
- [Live plots and readout](https://github.com/bughht/realtime-rppg-application/blob/main/main.py): `main.py`

### Face acquisition

- [Capture and ROIs](https://github.com/bughht/realtime-rppg-application/blob/main/face2series.py): `face2series.py`
- [Landmark model](https://github.com/bughht/realtime-rppg-application/blob/main/data/shape_predictor_81_face_landmarks.dat): `data/shape_predictor_81_face_landmarks.dat`
- [ROI RGB features](https://github.com/bughht/realtime-rppg-application/blob/main/face2series.py): `face2series.py`

### Pulse processing

- [Signal processor](https://github.com/bughht/realtime-rppg-application/blob/main/series2rPPG.py): `series2rPPG.py`
- [GREEN method](https://github.com/bughht/realtime-rppg-application/blob/main/series2rPPG.py): `series2rPPG.py`
- [GREEN-RED method](https://github.com/bughht/realtime-rppg-application/blob/main/series2rPPG.py): `series2rPPG.py`
- [CHROM method](https://github.com/bughht/realtime-rppg-application/blob/main/series2rPPG.py): `series2rPPG.py`
- [PBV method](https://github.com/bughht/realtime-rppg-application/blob/main/series2rPPG.py): `series2rPPG.py`
- [Detrend and filter](https://github.com/bughht/realtime-rppg-application/blob/main/series2rPPG.py): `series2rPPG.py`

### Heart-rate output

- [Spectrum and BPM](https://github.com/bughht/realtime-rppg-application/blob/main/main.py): `main.py`
- [ROI confidence](https://github.com/bughht/realtime-rppg-application/blob/main/main.py): `main.py`

### Other components

- **Operator**
- **Webcam**

## Connections

- Operator → Application window: operates
- Window controls → Application window: provides controls
- Application window → Signal processor: starts processing
- Signal processor → Capture and ROIs: initializes capture
- Webcam → Capture and ROIs: supplies frames
- Capture and ROIs → Landmark model: detects landmarks
- Capture and ROIs → ROI RGB features: extracts ROI features
- ROI RGB features → Application window: provides buffered data
- Application window → GREEN method: dispatches selection
- Application window → GREEN-RED method: dispatches selection
- Application window → CHROM method: dispatches selection
- Application window → PBV method: dispatches selection
- Application window → Detrend and filter: requests detrending
- Application window → Spectrum and BPM: filters and transforms
- Spectrum and BPM → ROI confidence: provides ROI BPM
- ROI confidence → Live plots and readout: weights and reports
- Application window → Live plots and readout: updates plots
- Live plots and readout → Operator: displays results