API Reference

This section provides detailed documentation for the core API of the Open-rppg toolbox.

Core Interface

The Model class is the primary entry point for all rPPG tasks. It encapsulates the complexity of different neural network architectures (like PhysMamba, TSCAN, etc.) into a unified interface.

class rppg.Model(model='FacePhys.rlap')

The main wrapper class for rPPG inference. It handles the full pipeline: face detection, ROI signal extraction, and physiological metric calculation.

Parameters:

model (str) –

The name of the neural network architecture to use. Defaults to 'FacePhys.rlap'.

Supported Models:

  • State-Space Models (SSM): 'FacePhys.rlap' (Default), 'ME-chunk', 'ME-flow', 'PhysMamba', 'RhythmMamba'.

  • Transformer / Attention: 'PhysFormer', 'TSCAN', 'EfficientPhys'.

  • Convolutional: 'PhysNet'.

Note: Append .rlap or .pure to the model name to specify weights (e.g., 'PhysNet.pure' ).

process_video(vid_path)

Processes a video file from start to finish to extract physiological signals.

Parameters:

vid_path (str) – Path to the input video file (e.g., .mp4, .avi, .mkv).

Returns:

A dictionary containing the estimated heart rate ('hr'), signal quality ('SQI'), and other metrics.

Return type:

dict

video_capture(vid_path=0)

A context manager for processing real-time video streams or video files frame-by-frame. It initializes a background thread for non-blocking inference.

Parameters:

vid_path – The device index (int) for webcams or the file path (str) for video files. Defaults to 0.

Returns:

The instance itself (context manager).

process_video_tensor(tensor, fps=30.0)

Processes a pre-loaded video tensor (uint8). Useful for integration with existing data pipelines where the video is already in memory.

Parameters:

  • tensor (numpy.ndarray) – A 4D tensor of shape (Frames, Height, Width, 3).

  • fps (float) – The frame rate of the video data.

Returns:

A dictionary containing the analysis results.

process_faces_tensor(tensor, fps=30.0)

Processes a pre-cropped face tensor, skipping the internal face detection step.

Parameters:

  • tensor (numpy.ndarray) – A 4D tensor of shape (Frames, Height, Width, 3).

  • fps (float) – The frame rate of the video data.

Returns:

A dictionary containing the analysis results.

bvp(start=0, end=None, raw=False)

Retrieves the Blood Volume Pulse (BVP) signal from the internal buffer.

Parameters:

  • start (float) – Start time in seconds.

  • end (float) – End time in seconds. If None, returns data up to the current timestamp.

  • raw (bool) – If True, returns the raw model output. If False, applies bandpass filtering and normalization.

Returns:

A tuple (signal, timestamps).

Return type:

tuple

hr(start=0, end=None, return_hrv=True)

Calculates heart rate and HRV metrics from the buffered signal.

Parameters:

  • start (float) – Start time in seconds.

  • end (float) – End time in seconds.

  • return_hrv (bool) – Whether to compute detailed HRV metrics (SDNN, RMSSD, etc.). Defaults to True.

Returns:

A dictionary with keys 'hr', 'SQI', 'hrv', and 'latency'.

preview

A generator property used in the video_capture loop.

Yields:

(frame, box) where frame is the current RGB image and box is the face bounding box coordinates.

stop()

Stops the running inference thread. Called automatically when exiting the context manager.

Signal Processing Utilities

These helper functions are available in rppg.main for post-processing physiological signals.

rppg.main.SQI(signal, sr=30, min_freq=0.5, max_freq=3.0, window_size=10)

Calculates the Signal Quality Index (SQI) to assess the reliability of the rPPG signal. It uses an autocorrelation-based method to determine if the signal has a periodic physiological structure.

Parameters:

  • signal (numpy.ndarray) – The input BVP signal array.

  • sr (int) – Sampling rate in Hz. Defaults to 30.

  • min_freq (float) – Minimum expected human pulse frequency (Hz).

  • max_freq (float) – Maximum expected human pulse frequency (Hz).

  • window_size (int) – Window size in seconds for sliding window calculation.

Returns:

A quality score between 0.0 (noise) and 1.0 (clean signal).

Return type:

float

rppg.main.get_hr(y, sr=30, min=30, max=180)

Estimates the Heart Rate (HR) from a BVP signal using the frequency domain approach. It calculates the Power Spectral Density (PSD) using Welch’s method and finds the peak frequency.

Parameters:

  • y (numpy.ndarray) – The input BVP signal.

  • sr (int) – Sampling rate in Hz.

  • min (int) – Minimum valid heart rate (BPM).

  • max (int) – Maximum valid heart rate (BPM).

Returns:

Estimated Heart Rate in BPM.

Return type:

float

rppg.main.get_prv(y, ts=None, sr=30)

Computes Pulse Rate Variability (PRV) metrics (time-domain and frequency-domain) using peak detection. This function wraps heartpy analysis to provide standard HRV metrics.

Parameters:

  • y (numpy.ndarray) – The input BVP signal.

  • ts (numpy.ndarray) – Corresponding timestamps (optional).

  • sr (int) – Sampling rate in Hz.

Returns:

A dictionary containing metrics such as 'sdnn', 'rmssd', 'pnn50', 'LF/HF', and 'breathingrate'.

Return type:

dict

rppg.main.detrend(signal, min_freq=0.5, sr=30)

Applies Smoothness Priors Detrending (SPD) to remove low-frequency non-stationary trends (such as motion artifacts) from the signal.

Parameters:

  • signal (numpy.ndarray) – The raw input signal.

  • min_freq (float) – The cut-off frequency for the trend. Trends slower than this will be removed.

  • sr (int) – Sampling rate in Hz.

Returns:

The detrended signal.

Return type:

numpy.ndarray

rppg.main.bandpass_filter(data, lowcut=0.5, highcut=3, fs=30, order=3)

Applies a standard Butterworth bandpass filter to the signal.

Parameters:

  • data (numpy.ndarray) – Input signal.

  • lowcut (float) – Low frequency cutoff (Hz). Defaults to 0.5 (30 BPM).

  • highcut (float) – High frequency cutoff (Hz). Defaults to 3.0 (180 BPM).

  • fs (int) – Sampling frequency (Hz).

  • order (int) – Order of the filter.

Returns:

Filtered signal.

Return type:

numpy.ndarray