> ## Documentation Index
> Fetch the complete documentation index at: https://docs.medera.info/llms.txt
> Use this file to discover all available pages before exploring further.

# Facial Physiological Engine

> rPPG-derived HR, BP, HRV, respiration, stress, affect

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

## Constructor

```python theme={"system"}
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

```python theme={"system"}
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