# ksyegorov/mcd_rppg architecture

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

- Interactive diagram: https://gitdiagram.com/ksyegorov/mcd_rppg
- Repository: https://github.com/ksyegorov/mcd_rppg

## Overview

MCD-rPPG is a research codebase for reproducing remote photoplethysmography experiments: prepare face-video inputs, train or run rPPG models, then evaluate pulse signals and heart rate across datasets. The README also describes a multi-task model for health biomarkers; it is represented as a documented capability, but its end-to-end implementation is not established by the sampled source. The graph uses the documented training notebooks as entry points. Source excerpts support the training, preprocessing, and evaluation links shown; unsampled notebook and model wiring is not inferred.

Main entry points: [`rppglib/train.py`](https://github.com/ksyegorov/mcd_rppg/blob/main/rppglib/train.py) (Fold training and testing), [`rppglib/models`](https://github.com/ksyegorov/mcd_rppg/tree/main/rppglib/models) (Neural model zoo), [`preprocessing`](https://github.com/ksyegorov/mcd_rppg/tree/main/preprocessing) (Dataset preprocessing), [`rppglib/models/__init__.py`](https://github.com/ksyegorov/mcd_rppg/blob/main/rppglib/models/__init__.py) (Model registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prep["Video preparation"]
  node_prep_scripts["Dataset preprocessing"]
  node_face["Face and landmarks<br/>[face_utils.py]"]
end

subgraph group_runtime["Data and signals"]
  node_video_io["Video loading<br/>[data_utils.py]"]
  node_train_data["Training dataset<br/>[train.py]"]
  node_dataset_api["Windowed dataset API<br/>[dataset.py]"]
  node_processing["Signal processing<br/>[processing.py]"]
end

subgraph group_models["rPPG models"]
  node_models_api["Model registry<br/>[__init__.py]"]
  node_model_zoo["Neural model zoo"]
  node_classic["Unsupervised methods<br/>[unsupervised.py]"]
end

subgraph group_experiments["Training and evaluation"]
  node_train_nb["Model training notebooks"]
  node_other_train_nb["Other training experiments<br/>[train_POS.ipynb]"]
  node_training["Fold training and testing<br/>[train.py]"]
  node_inference_nb["Inference timing"]
end

node_researcher(("Researcher"))
node_dataset[("Video and PPG datasets")]
node_pulse_result["PPG and heart rate"]
node_biomarker_result["Health biomarkers"]

node_researcher -->|"runs experiment"| node_train_nb
node_researcher -->|"runs experiment"| node_other_train_nb
node_researcher -->|"runs inference"| node_inference_nb
node_dataset -->|"provides videos"| node_prep_scripts
node_prep_scripts -->|"loads video"| node_video_io
node_prep_scripts -->|"extracts faces"| node_face
node_train_nb -->|"starts training"| node_training
node_other_train_nb -->|"starts training"| node_training
node_dataset -->|"provides metadata"| node_training
node_training -->|"selects model"| node_models_api
node_models_api -->|"resolves model"| node_model_zoo
node_training -->|"builds loaders"| node_train_data
node_train_data -->|"filters PPG"| node_processing
node_training -->|"calculates metrics"| node_processing
node_training -->|"reports PPG and HR"| node_pulse_result
node_inference_nb -->|"benchmarks models"| node_model_zoo
node_model_zoo -->|"predicts pulse"| node_pulse_result
node_model_zoo -.->|"estimates biomarkers"| node_biomarker_result
node_classic -->|"extracts pulse"| node_pulse_result

click node_prep_scripts "https://github.com/ksyegorov/mcd_rppg/tree/main/preprocessing"
click node_video_io "https://github.com/ksyegorov/mcd_rppg/blob/main/rppglib/data_utils.py"
click node_face "https://github.com/ksyegorov/mcd_rppg/blob/main/rppglib/face_utils.py"
click node_train_data "https://github.com/ksyegorov/mcd_rppg/blob/main/rppglib/train.py"
click node_dataset_api "https://github.com/ksyegorov/mcd_rppg/blob/main/rppglib/dataset.py"
click node_processing "https://github.com/ksyegorov/mcd_rppg/blob/main/rppglib/processing.py"
click node_models_api "https://github.com/ksyegorov/mcd_rppg/blob/main/rppglib/models/__init__.py"
click node_model_zoo "https://github.com/ksyegorov/mcd_rppg/tree/main/rppglib/models"
click node_classic "https://github.com/ksyegorov/mcd_rppg/blob/main/rppglib/unsupervised.py"
click node_train_nb "https://github.com/ksyegorov/mcd_rppg/blob/main/train_SCNN_8roi_mcd_rppg.ipynb"
click node_other_train_nb "https://github.com/ksyegorov/mcd_rppg/blob/main/train_POS.ipynb"
click node_training "https://github.com/ksyegorov/mcd_rppg/blob/main/rppglib/train.py"
click node_inference_nb "https://github.com/ksyegorov/mcd_rppg/blob/main/Inference_time.ipynb"

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_prep_scripts,node_face toneBlue
class node_video_io,node_train_data,node_dataset_api,node_processing,node_dataset toneAmber
class node_models_api,node_model_zoo,node_classic toneMint
class node_train_nb,node_other_train_nb,node_training,node_inference_nb toneRose
class node_researcher,node_pulse_result,node_biomarker_result toneIndigo
```

## Components

### Video preparation

- [Dataset preprocessing](https://github.com/ksyegorov/mcd_rppg/tree/main/preprocessing): `preprocessing`
- [Face and landmarks](https://github.com/ksyegorov/mcd_rppg/blob/main/rppglib/face_utils.py): `rppglib/face_utils.py`

### Data and signals

- [Video loading](https://github.com/ksyegorov/mcd_rppg/blob/main/rppglib/data_utils.py): `rppglib/data_utils.py`
- [Training dataset](https://github.com/ksyegorov/mcd_rppg/blob/main/rppglib/train.py): `rppglib/train.py`
- [Windowed dataset API](https://github.com/ksyegorov/mcd_rppg/blob/main/rppglib/dataset.py): `rppglib/dataset.py`
- [Signal processing](https://github.com/ksyegorov/mcd_rppg/blob/main/rppglib/processing.py): `rppglib/processing.py`

### rPPG models

- [Model registry](https://github.com/ksyegorov/mcd_rppg/blob/main/rppglib/models/__init__.py): `rppglib/models/__init__.py`
- [Neural model zoo](https://github.com/ksyegorov/mcd_rppg/tree/main/rppglib/models): `rppglib/models`
- [Unsupervised methods](https://github.com/ksyegorov/mcd_rppg/blob/main/rppglib/unsupervised.py): `rppglib/unsupervised.py`

### Training and evaluation

- [Model training notebooks](https://github.com/ksyegorov/mcd_rppg/blob/main/train_SCNN_8roi_mcd_rppg.ipynb): `train_SCNN_8roi_mcd_rppg.ipynb`
- [Other training experiments](https://github.com/ksyegorov/mcd_rppg/blob/main/train_POS.ipynb): `train_POS.ipynb`
- [Fold training and testing](https://github.com/ksyegorov/mcd_rppg/blob/main/rppglib/train.py): `rppglib/train.py`
- [Inference timing](https://github.com/ksyegorov/mcd_rppg/blob/main/Inference_time.ipynb): `Inference_time.ipynb`

### Other components

- **Researcher**
- **Video and PPG datasets**
- **PPG and heart rate**
- **Health biomarkers**

## Connections

- Researcher → Model training notebooks: runs experiment
- Researcher → Other training experiments: runs experiment
- Researcher → Inference timing: runs inference
- Video and PPG datasets → Dataset preprocessing: provides videos
- Dataset preprocessing → Video loading: loads video
- Dataset preprocessing → Face and landmarks: extracts faces
- Model training notebooks → Fold training and testing: starts training
- Other training experiments → Fold training and testing: starts training
- Video and PPG datasets → Fold training and testing: provides metadata
- Fold training and testing → Model registry: selects model
- Model registry → Neural model zoo: resolves model
- Fold training and testing → Training dataset: builds loaders
- Training dataset → Signal processing: filters PPG
- Fold training and testing → Signal processing: calculates metrics
- Fold training and testing → PPG and heart rate: reports PPG and HR
- Inference timing → Neural model zoo: benchmarks models
- Neural model zoo → PPG and heart rate: predicts pulse
- Neural model zoo → Health biomarkers: estimates biomarkers
- Unsupervised methods → PPG and heart rate: extracts pulse