热图

热图可视化在人脸区域显示 PPG（光电容积描记法）振幅覆盖层，显示脸部哪些区域提供最强的血容量脉搏信号。这帮助用户将脸部调整到最佳位置以获得准确测量。

工作原理

热图实时分析视频帧，测量不同脸部区域的 PPG 信号振幅。脉搏信号较强的区域会显示为高亮，较弱的区域则较暗或透明。可视化会随着光线和脸部位置的变化动态调整。

可用预设

热图包含 10 种内置预设：

预设	描述
field	暖色、柔和的半透明场（默认）
cool	冷色调场
neon	明亮、高对比度的霓虹光晕
pulse	强烈的脉冲强度
bloom	宽广柔和的辉光，中心强度较低
sharp	紧密、高对比度的热点
cycles	动态色彩循环
drift	热点在脸部上漂移
vintage	柔和的复古色调
electric	快速、高能量的闪烁

预设配置也会被导出（HEATMAP_PRESETS、HEATMAP_PRESET_NAMES），因此可以查看预设内容，或将其作为自定义变体的起点。

配置

JavaScript

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

const camera = createVitalSignCamera({
  // ... 其他配置
  visualizationOptions: {
    heatmap: {
      enabled: true,
      mode: 'field',      // 预设名称（默认：'field'）或自定义变体配置
      ppgHistorySize: 120,// 用于归一化的 PPG 样本数（默认：120）
      renderFps: 30       // 目标渲染帧率（默认：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>

自定义变体

mode 除了预设名称外，也接受 HeatmapVariantConfig 对象，以完全控制渲染效果：

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

const customVariant: HeatmapVariantConfig = {
  colormap: heatmapColormapWarm, // (value: number) => [r, g, b]，输入为归一化至 0–1 的值
  radiusScale: 1,     // 基础热点半径的倍数
  aCenter: 0.55,      // 每个热点中心的透明度
  aMid: 0.35,         // 30% 衰减点的透明度
  aEdge: 0.12,        // 70% 衰减点的透明度
  pulseAmp: 0.06,     // 正弦强度脉动振幅
  pulseSpeed: 1.6,    // 脉动动画频率
  driftAmp: 0,        // 热点中心的位移漂移（以脸部高度为单位）
  flickerAmp: 0,      // 高频强度闪烁
  cycleSpeed: 0       // 色彩循环速度（0 = 静态）
};

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

内置色图：heatmapColormapWarm、heatmapColormapCool、heatmapColormapNeon、heatmapColormapVintage、heatmapColormapElectric。

运行时更新

// 更换预设
camera.visualizationOptions = {
  ...camera.visualizationOptions,
  heatmap: { mode: 'neon' }
};

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

HeatmapOptions 接口

interface HeatmapOptions {
  enabled?: boolean;                    // 启用/停用覆盖层（默认：true）
  mode?: HeatmapPresetName | HeatmapVariantConfig; // 预设名称或自定义变体（默认：'field'）
  ppgHistorySize?: number;              // 用于归一化的 PPG 样本数（默认：120）
  renderFps?: number;                   // 目标渲染帧率（默认：30）
}