CFMamba-Phys

CFMamba-Phys (unofficial reimplementation) — rPPG heart rate from facial video

Unofficial. Not affiliated with the original authors.

This is an independent, third-party reimplementation of CFMamba-Phys. It is not an official release, not endorsed, reviewed, or supported by the paper's authors, by Beijing Sport University, or by Elsevier. No weights, code, or data came from the authors.

The name "CFMamba-Phys" is used only to identify the architecture being reproduced.

Several architecture details are deliberate departures from the paper — the scan, the clip length, and the loss weighting. See Deviations.

Model summary

A PyTorch model that predicts a blood-volume-pulse (BVP) waveform from face video. Heart rate is not regressed; it is read off the predicted waveform afterwards by band-pass filtering and beat timing.

video -> ffmpeg decode 30 fps, face crop
      -> Fusion Stem      raw frames fused with four temporal differences
      -> PGA              Gaussian skin prior, channel-wise gating, space collapsed
      -> 4 x [Mamba + CAM, DF-FFN]
      -> 1D conv head     one BVP sample per frame
      -> Butterworth 0.75-2.5 Hz + beat intervals -> heart rate

Source research

The architecture comes from:

Wang, L., Su, X., Yang, Y., Ge, H., Shen, Y. CFMamba-Phys: A frequency-aware state space model with channel enhancement for remote photoplethysmography. Biomedical Signal Processing and Control 126 (2026) 110996. DOI: 10.1016/j.bspc.2026.110996

The paper leaves parts unspecified. Four further papers fill them, as recorded in ARCHITECTURE.md:

Deviations

These are known, intentional, and measured. They are why this is not a reproduction.

1. Mamba-3, not Mamba-1. All source papers call the Mamba-1 selective scan. This uses Mamba-3.
2. 300-frame clips, not 160. The papers use 160.
3. Loss weight alpha = 0.8, not 0.2. CFMamba Eq. 19 gives alpha and beta as symbols with no values. RhythmFormer §3.4 supplied 0.2/1.0, and this project ran that way until measurement showed the temporal term went flat from epoch 2 and contributed ~1.5% of the final loss. Raised to 0.8 on that evidence.
4. Heart rate is read as the median inter-beat interval, not the dominant spectral peak. This departs from the rPPG-Toolbox convention, so these numbers are not comparable with rPPG-Toolbox tables.
5. Parameter and MAC budget differ by +2.5% / -2.0% from the published 0.91 M / 80.82 M.

Loss

L = alpha * L_time + beta * L_freq        alpha = 0.8, beta = 1.0
L_time = 1 - Pearson(S_pred, S_gt)
L_freq = CE(PSD(S_pred), argmax(PSD(S_gt)))

L_freq is a cross-entropy over 105 candidate rates at 1 bpm spacing across 45-150 bpm, evaluated as a direct DFT at those frequencies. The label is the target waveform's own dominant rate, taken from the contact PPG rather than from a manifest heart-rate column, because five UBFC subjects have a broken HR readout and an intact waveform.

Training data

No dataset files are uploaded here. This repository holds code and weights only. The corpora carry human-subject facial video and health biomarkers under data use agreements and are not redistributed, mirrored, or bundled in any form. Obtain each from its own source, under its own terms, yourself.

Three corpora, pooled into one 90/3/7 split, grouped by subject and stratified by source.

MCD-rPPG:

Egorov, K., Botman, S., Blinov, P., Zubkova, G., Ivaschenko, A., Kolsanov, A., et al. Gaze into the Heart: A Multi-View Video Dataset for rPPG and Health Biomarkers Estimation. DOI: 10.1145/3746027.3758255 Dataset: huggingface.co/datasets/kyegorov/mcd_rppg

Unverified: UBFC-rPPG (Bobbia et al.) and MR-NIRP (Nowara et al.) are used under their own published terms.

Evaluation

Pooled test split, 4482 windows of 300 frames, checkpoint at 48 of 50 epochs, interval (median IBI) readout, band 45-150 bpm.

Readout comparison

Over 1569 strided test windows spanning all 265 test clips:

Published comparison

MCD-rPPG in-dataset results from Egorov et al. (2025), MAE only:

Intended use

Research and engineering on remote photoplethysmography: reproducing the architecture, comparing readouts, and studying dataset quality.

Usage

The code is on GitHub, not here: https://github.com/Tipuch/rppg_experiment

git clone https://github.com/Tipuch/rppg_experiment.git
cd rppg_experiment
uv sync

uv run python -m src.cli --help
uv run python -m src.cli predict --video path/to/face.mp4 --model path/to/last.pt
uv run python -m src.cli readout   # score every readout on a labelled split
uv run python -m src.cli train     # all three corpora, 50 epochs

--model defaults to the most recent build/runs/*/final.pt or last.pt, so point it at the downloaded checkpoint. predict needs no manifest entry: the face box and skin mask are built inline.

Window length is read from the checkpoint, not passed as an option. CUDA is required for any forward pass.

datasets/ and tools/rPPG-Toolbox are in neither repository. Obtain the corpora yourself; the toolbox (github.com/ubicomplab/rPPG-Toolbox) is needed only for baseline and train --baselines. RPPG_DATA_ROOT and RPPG_BUILD_ROOT repoint both roots.

README.md, ARCHITECTURE.md and DATASETS.md are in the repository.

Reproducing

seed 20260822, AdamW lr 1e-3, betas (0.9, 0.999), weight decay 0.05
grad clip 1.0, batch 4, 300 frames, 128x128, 50 epochs
5% linear warmup into cosine, min lr 1% of peak
alpha 0.8, beta 1.0

train --resume restores weights, AdamW moments, and the scheduler step counter. --epochs, --batch, --frames and steps per epoch must match the checkpoint; a mismatch raises rather than silently continuing a different schedule.

Tests: uv run python -m pytest tests/ -q — 487 tests, requires an idle GPU.

Licence and redistribution

• Code: MIT. See LICENSE. Repository: github.com/Tipuch/rppg_experiment.
• Weights: trained on corpora governed by data use agreements. Confirm that each agreement permits releasing derived weights before redistributing them. MIT on the code does not settle this.
• The paper is not licensed to this project. The architecture is reimplemented from the published description.

Citation

Cite the original work, not this repository:

@article{wang2026cfmambaphys,
  title   = {CFMamba-Phys: A frequency-aware state space model with channel
             enhancement for remote photoplethysmography},
  author  = {Wang, Lin and Su, Xinhua and Yang, Yaqing and Ge, Huanmin and
             Shen, Yanfei},
  journal = {Biomedical Signal Processing and Control},
  volume  = {126},
  pages   = {110996},
  year    = {2026},
  doi     = {10.1016/j.bspc.2026.110996}
}