---

name: rppg-toolbox description: "Guide remote photoplethysmography workflows with rPPG-Toolbox, including dataset preparation, supervised and unsupervised inference, evaluation, visualization, and safe extension." disable-model-invocation: true metadata: disco-role: operating license: NOASSERTION

rPPG-Toolbox

Use this repo skill when a Researcher needs to work with the rPPG-Toolbox for camera-based physiological sensing (remote photoplethysmography/rPPG): prepare supported video-plus-BVP datasets, train or test a neural model, extract BVP with traditional methods, evaluate heart rate/signal quality, inspect outputs, or extend a loader/model/method. This skill is an operating guide, not a replacement for the source package or a claim that data/checkpoints are available.

Start here

1. Confirm the user's checkout, Python environment, dataset/cache locations, checkpoint provenance, target mode, sampling rate, and whether the operation may write caches, checkpoints, plots, or logs.
2. Read installation and environment guidance for the Python/PyTorch stack. The repository is not a normal installable Python distribution; use an isolated environment and run from the checkout root or an explicit import path.
3. Choose a route below. Read only that route's SKILL.md first, then its linked references and scripts.
4. Validate paths, cache/file-list identity, tensor layout, label type, device, and expected output before launching an expensive command.
5. Keep raw data and checkpoints outside the skill tree. Treat preprocessing, training, OpenFace, and dataset-scale inference as explicit user-approved operations.

Route map

• Setup, YAML, and dispatch: Read setup-and-config when choosing train_and_test, only_test, or unsupervised_method, validating a config, diagnosing derived paths, or adding a dispatch branch.
• Datasets and preprocessing: Read data-preparation for raw layouts, face crop, transforms, chunking, pseudo labels, custom file lists, splits, cache audits, and loader extensions.
• Supervised neural models: Read supervised-models for exact model names, tensor geometry, checkpoints, training/only-test flow, BigSmall, or PhysMamba's required CUDA extension.
• Traditional BVP extraction: Read unsupervised-methods for POS, CHROM, ICA, GREEN, LGI, PBV, and OMIT selection and numerical failure diagnosis.
• Metrics and visual outputs: Read evaluation-and-visualization for HR/RR metrics, SNR/MACC, Bland--Altman, saved prediction pickles, preprocessed arrays, and optional OpenFace motion summaries.

Minimal invocation contract

From a user-owned rPPG-Toolbox checkout, the primary entry point is:

python main.py --config_file <path-to-user-config.yaml>

The source dispatches exact mode strings train_and_test, only_test, and unsupervised_method. YAML, not the CLI, controls datasets, models, devices, checkpoints, preprocessing, and output paths. Start from a nearby repository config, replace all research-specific paths, and use the setup validator before running the main program. Do not assume a release .pth file matches a new preprocessing identity.

Cross-route invariants

• The normal cache stores frame-first *_input*.npy arrays and paired *_label*.npy signals; the data layout returned to a model depends on DATA_FORMAT. Do not silently transpose to hide a model mismatch.
• DiffNormalized, Raw, and Standardized are different label contracts. Record the label type and sampling rate with every evaluation or visualization.
• Relative paths resolve from the process working directory. Derived cache, file-list, checkpoint, and output identities depend on preprocessing settings; use the printed frozen config and a read-only validator rather than guessing.
• A CPU import does not verify PhysMamba. Its mamba_ssm/causal_conv1d CUDA backend must be installed and exercised on a compatible device.
• Missing datasets, checkpoints, OpenFace, or external motion-augmentation inputs are explicit limits. Do not download, fabricate, or silently skip them and then report a completed experiment.

Before handoff

Record the route, config identity, dataset/split, cache and file-list paths, label type, frame rate, device/backend, checkpoint, output location, command, result, and any skipped or blocked verification. For current-code alignment, read repository provenance before using refresh-repo-skill. For cross-cutting failures, read troubleshooting.

This repo skill was generated as a reusable package/repository operating graph; it remains self-contained knowledge and does not require the source checkout to remain available for reading. The actual rPPG run still requires the user's own data, environment, and permissions.