Skip to content

README.md

Latest commit

 

History

History
187 lines (148 loc) · 7.85 KB

README.md

File metadata and controls

187 lines (148 loc) · 7.85 KB
Raw

rPPG & PPG-to-ABP Deep Learning Toolbox

A clean, professional, production-quality implementation of deep-learning-based Remote Photoplethysmography (rPPG) and PPG-to-ABP (Arterial Blood Pressure) estimation models using PyTorch.

Important

Disclaimer: This project is created for R&D purposes. It is not intended for commercial use or production systems. It is maintained strictly for educational and portfolio purposes only.

Overview

Purpose

This repository provides a comprehensive pipeline for extracting physiological signals (like heart rate and pulse wave) from facial videos using Remote Photoplethysmography (rPPG), and estimating continuous Arterial Blood Pressure (ABP) waveforms from raw PPG signals.

Features

  • Facial Image-Based rPPG Models:
    • DeepPhys: Video-Based Physiological Measurement Using Convolutional Attention Networks.
    • PhysNet: Remote Photoplethysmograph Signal Measurement from Facial Videos.
    • 3D-PhysNet: Spatio-Temporal Networks for remote heart rate estimation.
    • PhysNet + LSTM / 2D-PhysNet + LSTM integrations.
  • PPG-to-ABP Estimation:
    • PP-Net: Deep Learning Framework for PPG-based Blood Pressure (SBP/DBP) and Heart Rate estimation.
    • vid2bp: Dedicated subsystem for continuous waveform-level blood pressure prediction.
  • pyVHR Integration: An assessment tool suite for comparing different Region-of-Interest (ROI) selections.
  • Docker Support: Containerized environment for instant reproduction and execution.
  • WandB Logging: Built-in support for experimental tracking and performance logging.

Motivation

Non-contact health monitoring (rPPG) and cuffless continuous blood pressure estimation (PPG-to-ABP) are key frontiers in digital health. This repository standardizes these models to make them reproducible, easy to deploy, and clean for academic or industrial review.

Architecture & Execution Flow

The codebase is split into two primary components:

  1. rPPG Modeling: Processes facial video datasets (like UBFC, LGI_PPGI) to compute heart rate, BVP (Blood Volume Pulse), and respiratory signals.
  2. vid2bp: Processes raw PPG signals to output full Arterial Blood Pressure (ABP) waveforms.
graph TD
    A[Facial Video Input] --> B[pyVHR / Face Detection]
    B --> C[rPPG Deep Learning Models]
    C --> D[BVP Signal / Heart Rate]
    E[Raw PPG Signal] --> F[vid2bp Pipeline]
    F --> G[Continuous ABP Waveform SBP/DBP]
Loading

Physiological Context

Below is a graph showing how respiration modulates the PPG signal in three ways (baseline, amplitude, and frequency):

Respiration Modulates PPG

Execution Flow

  1. Configuration: Load configuration settings from params.py or environment variable overrides.
  2. Preprocessing: Parse raw video/signal data and write optimized files (.h5 formats) using scripts in utils/.
  3. Training/Validation: Run deep learning models via PyTorch train loops in main.py or vid2bp/main.py.
  4. Evaluation: Generate statistics, plots, and log metrics to Weights & Biases (WandB).

Folder Structure

.
├── CAM/                       # Class Activation Map utils
├── dataset/                   # Dataset loader definitions
├── docs/                      # Original specifications and system architecture diagrams
├── nets/                      # Core neural network architectures (models, blocks, layers)
├── pyVHR/                     # Custom Video Heart Rate framework integration
├── pytorch_grad/              # Gradient computation helpers
├── pytorch_grad_cam/          # Grad-CAM visualization toolkit
├── utils/                     # Preprocessing, training, and helper functions
├── vid2bp/                    # Subsystem for PPG to Arterial Blood Pressure estimation
├── .env.example               # Template environment configuration file
├── Dockerfile                 # Docker container environment definition
├── LICENSE                    # Open-source MIT License
├── README.md                  # This documentation file
├── _1_rppg_assesment.py       # Main entry point for pyVHR ROI assessment
├── main.py                    # Main training/evaluation script
├── params.py                  # Global model/dataset parameters configuration
└── requirements.txt           # Python dependency manifest

Technologies

Installation

Local Setup

  1. Clone the repository: 
    git clone https://github.com/remotebiosensing/rppg.git
cd rppg
  2. Create and activate a virtual environment: 
    python -m venv .venv
# Windows:
.venv\Scripts\activate
# Linux/macOS:
source .venv/bin/activate
  3. Install Dependencies: 
    pip install --upgrade pip
pip install -r requirements.txt

Docker Setup

To run the models in a fully containerized environment with GPU acceleration support:

  1. Build the Docker Image: 
    docker build -t rppg-toolbox:latest .
  2. Run the Container (with CUDA GPU support): 
    docker run --gpus all -it --env-file .env rppg-toolbox:latest

Configuration

Duplicate .env.example to .env and fill in your local system directories:

cp .env.example .env
Variable Name Description Default
SAVE_ROOT_PATH Path where preprocessed datasets are saved /media/hdd1/dy/dataset/
DATA_ROOT_PATH Base directory containing raw video folders /media/hdd1/
MODEL_ROOT_PATH Base directory where trained checkpoints are stored /media/hdd1/dy/model/
WANDB_PROJECT_NAME Weights & Biases project name torch_2023ICCV
WANDB_ENTITY Weights & Biases account name daeyeolkim
CUDA_VISIBLE_DEVICES GPU index to utilize for training 0

Usage

1. Training rPPG Models

To preprocess data, select a model, and execute training:

  1. Adjust parameters inside params.py or via environment variables.
  2. Run the main training loop: 
    python main.py

2. ROI Assessment using pyVHR

Evaluate different region-of-interest (ROI) masking methods on LGI_PPGI or UBFC datasets:

python _1_rppg_assesment.py

3. PPG-to-ABP Waveform Estimation (vid2bp)

To train/evaluate the blood pressure estimation models:

cd vid2bp
python main.py

Troubleshooting

  • OpenCV / MediaPipe Graphics Link Issues (Docker): If you get libGL.so.1: cannot open shared object file in containerized environments, ensure the system dependencies in the Dockerfile built successfully (libgl1-mesa-glx is present).
  • CUDA Out of Memory: Reduce batch_size in params.py (e.g. from 32 to 16 or 8).
  • Missing pyVHR dependencies: Please make sure requirements.txt has been fully installed in your virtual environment.

License

This project is licensed under the MIT License - see the LICENSE file for details.