Facial Physiological Engine

extracts physiological signal from video via Haar Cascade face detection, ROI sampling, and CHROM rPPG.

Constructor

engine = FacialPhysiologicalEngine(fps=30, # frames per second min_hr_duration=30, # seconds; HR will not be computed below this min_hrv_duration=60, # seconds; HRV will not be computed below this roi_type='forehead', # 'forehead' | 'cheeks' | 'full_face')

Primary method

signals: PhysiologicalSignals = engine.extract_features(video_frames: List[np.ndarray], timestamps: Optional[List[float]] = None,)

PhysiologicalSignals dataclass

Field	Unit	Notes
`heart_rate`	bpm	< 5 bpm MAE at SNR > 3.0
`heart_rate_confidence`	0–1
`systolic_bp`	mmHg	Estimate; clinical decisions should still use a cuff
`diastolic_bp`	mmHg
`bp_confidence`	0–1
`respiration_rate`	breaths / min
`respiration_confidence`	0–1
`hrv_sdnn`	ms	Standard deviation of NN intervals
`hrv_rmssd`	ms	Root mean square of successive differences
`hrv_lf_hf_ratio`	ratio	Sympathovagal balance
`hrv_sd1`	ms	Poincaré short-term variability
`hrv_sd2`	ms	Poincaré long-term variability
`stress_index`	0–100
`pns_index`	0–100	Parasympathetic activity
`sns_index`	0–100	Sympathetic activity
`overall_quality`	0–100
`snr`	dB	Threshold: > 3.0
`signal_duration`	seconds

Library dependencies

OpenCV (cv2) — face detection
rPPG library (heartpy) — HR / HRV
SciPy (scipy.signal, scipy.interpolate, scipy.fft) — filtering
NumPy (numpy) — arrays

Failure modes

The engine returns the metric with confidence: 0.0 rather than fabricated values when:

Face detection fails on > 30 % of frames
SNR ≤ 3.0
Recording shorter than the declared minimum duration

​Constructor

​Primary method

​PhysiologicalSignals dataclass

​Library dependencies

​Failure modes

Constructor

Primary method

PhysiologicalSignals dataclass

Library dependencies

Failure modes