Skip to main content

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.

FacialPhysiologicalEngine 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

FieldUnitNotes
heart_ratebpm< 5 bpm MAE at SNR > 3.0
heart_rate_confidence0–1
systolic_bpmmHgEstimate; clinical decisions should still use a cuff
diastolic_bpmmHg
bp_confidence0–1
respiration_ratebreaths / min
respiration_confidence0–1
hrv_sdnnmsStandard deviation of NN intervals
hrv_rmssdmsRoot mean square of successive differences
hrv_lf_hf_ratioratioSympathovagal balance
hrv_sd1msPoincaré short-term variability
hrv_sd2msPoincaré long-term variability
stress_index0–100
pns_index0–100Parasympathetic activity
sns_index0–100Sympathetic activity
overall_quality0–100
snrdBThreshold: > 3.0
signal_durationseconds

​
Library dependencies

  • OpenCV (cv2) — face detection
  • HeartPy (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