Heatmap

The heatmap visualization displays a PPG (photoplethysmography) amplitude overlay on the face region, showing which areas of the face provide the strongest blood volume pulse signal. This helps users position their face optimally for accurate measurements.

How It Works

The heatmap analyzes video frames in real-time, measuring PPG signal amplitude across different facial regions. Areas with stronger pulse signals appear highlighted, while weaker areas are dimmer or transparent. The visualization adapts dynamically as lighting and face position change.

Available Presets

The heatmap includes 10 built-in presets:

Preset	Description
field	Warm, soft semi-transparent field (default)
cool	Cool-toned field
neon	Bright, high-contrast neon glow
pulse	Strong pulsing intensity
bloom	Wide, soft glow with lower center intensity
sharp	Tight, high-contrast hotspots
cycles	Animated color cycling
drift	Hotspots drift across the face
vintage	Muted vintage tones
electric	Fast, high-energy flicker

The preset configurations are also exported (HEATMAP_PRESETS, HEATMAP_PRESET_NAMES) so a preset can be inspected or used as a starting point for a custom variant.

Configuration

JavaScript

import { createVitalSignCamera } from 'ts-vital-sign-camera';

const camera = createVitalSignCamera({
  // ... other config
  visualizationOptions: {
    heatmap: {
      enabled: true,
      mode: 'field',      // Preset name (default: 'field') or a custom variant config
      ppgHistorySize: 120,// PPG samples kept for normalization (default: 120)
      renderFps: 30       // Target render frame rate (default: 30)
    }
  }
});

React

import { VitalSignCamera } from 'react-vital-sign-camera';

const App = () => (
  <VitalSignCamera
    visualizationOptions={{
      heatmap: {
        enabled: true,
        mode: 'neon'
      }
    }}
  />
);

Vue

<template>
  <VitalSignCamera
    :visualizationOptions="visualizationOptions"
  />
</template>

<script setup>
const visualizationOptions = {
  heatmap: {
    enabled: true,
    mode: 'bloom',
    renderFps: 24
  }
};
</script>

Custom Variants

Instead of a preset name, mode accepts a HeatmapVariantConfig object for full control over the rendering:

import { heatmapColormapWarm, type HeatmapVariantConfig } from 'ts-vital-sign-camera';

const customVariant: HeatmapVariantConfig = {
  colormap: heatmapColormapWarm, // (value: number) => [r, g, b] for normalized 0–1 values
  radiusScale: 1,     // Multiplier on the base hotspot radius
  aCenter: 0.55,      // Alpha at the center of each hotspot
  aMid: 0.35,         // Alpha at the 30% falloff point
  aEdge: 0.12,        // Alpha at the 70% falloff point
  pulseAmp: 0.06,     // Sinusoidal intensity pulsing amplitude
  pulseSpeed: 1.6,    // Pulse animation frequency
  driftAmp: 0,        // Positional drift of hotspot centers (face-height units)
  flickerAmp: 0,      // High-frequency intensity flicker
  cycleSpeed: 0       // Color cycling speed (0 = static)
};

camera.visualizationOptions = {
  ...camera.visualizationOptions,
  heatmap: { enabled: true, mode: customVariant }
};

Built-in colormaps: heatmapColormapWarm, heatmapColormapCool, heatmapColormapNeon, heatmapColormapVintage, heatmapColormapElectric.

Runtime Updates

// Switch preset
camera.visualizationOptions = {
  ...camera.visualizationOptions,
  heatmap: { mode: 'neon' }
};

// Disable
camera.visualizationOptions = {
  ...camera.visualizationOptions,
  heatmap: { enabled: false }
};

HeatmapOptions Interface

interface HeatmapOptions {
  enabled?: boolean;                    // Enable/disable the overlay (default: true)
  mode?: HeatmapPresetName | HeatmapVariantConfig; // Preset name or custom variant (default: 'field')
  ppgHistorySize?: number;              // PPG samples kept for normalization (default: 120)
  renderFps?: number;                   // Target render frame rate (default: 30)
}