熱圖

熱圖可視化在臉部區域顯示 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）
}