VitalSense is a high-performance implementation of remote PhotoPlethysmoGraphy (rPPG). It enables camera-based measurement of the human blood volume pulse by detecting subtle changes in skin color that originate from blood pulsation.
Caution
This is a Computer Systems Engineering student project intended for demonstration purposes only. The provided code is not suitable for clinical use or medical decision-making.
Unlike traditional monolithic rPPG scripts, VitalSense uses a modular architecture that decouples signal extraction from the user interface. The system leverages the MediaPipe Tasks API (0.10.x) for asynchronous face tracking, ensuring a stable 30 FPS monitor even during heavy processing.
-
Signal Extraction: Tracks anatomically stable forehead regions (ROI) to capture the raw green-channel signal (
$G_{mean}$ ). -
DSP Pipeline: Applies a 2nd-order SOS Butterworth bandpass filter (
$0.7–4.0$ Hz) and Fast Fourier Transform (FFT) to isolate the heart rate. - AI Layer: Integrates a Groq-powered Llama 3.3 model to provide asynchronous, real-time health feedback and stress classification.
To run the VitalSense application, clone the repository and set up a virtual environment to ensure isolation.
# Clone the repository
git clone https://github.com/Arhamurrahemeen/VitalSense.git
cd VitalSense/src
# Create and activate a virtual environment
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txtMediaPipe's face tracking model (face_landmarker.task) is too large for git and must be downloaded manually into src/:
curl -L -o face_landmarker.task "https://storage.googleapis.com/mediapipe-models/face_landmarker/face_landmarker/float16/1/face_landmarker.task"Launch the main orchestrator to start the webcam feed and HUD:
python main.pypython main.py # green channel (default)
python main.py --method pos # POS (Wang et al. 2016)
python main.py --method chrom # CHROM (de Haan & Jeanne 2013)POS and CHROM project out achromatic components — specular reflection and most
illumination change — that a green-only estimator cannot separate from the pulse.
No published accuracy comparison exists for this implementation yet; see bench/
for the harness that will produce one.
- OpenCV HUD: The primary interface providing real-time overlays for BPM, Confidence, and AI-generated feedback.
- Scientific Dashboard: A secondary Matplotlib window displaying live time-domain PPG waveforms and frequency-domain power spectra.
For a detailed breakdown of the engineering stages, mathematical computations, and research findings, see the full project documentation: 👉 VitalSenseV1.md
VitalSense is built upon established research in the field of digital signal processing and rPPG:
- W. Verkruysse et al. (2008): Remote plethysmographic imaging using ambient light.
- Poh et al. (2010): Foundations of webcam-based heart rate estimation.
- Zhao et al. (2023): HRV feature extraction from rPPG signals.
Developed by: Muhammad Arham
Email: business.arhamurrahemeen@gmail.com
LinkedIn: linkedin.com/in/muhammad-arham-rajput