Scanning Sequence

The scanning sequence is a stage-aware orchestrator that drives the built-in visualizations through a predefined animation while the scan is running. Instead of enabling each overlay separately, you enable the sequence once and the SDK animates the scan for you.

How It Works

The orchestrator watches the engine stage:

While collecting data (CollectingData), it plays a sweep animation over the face:
1. Horizontal sweep (default 2 s)
2. Vertical sweep (default 2 s)
3. Ripple (default 0.5 s)
4. Static mesh with the thermal mask (open-ended — persists until the stage changes)
Otherwise (waiting, analyzing, or idle), it shows the configuration you provide in idleStage — for example a calm face mesh so the user always has visual feedback before and after the scan.

While the orchestrator is enabled, it owns the faceMesh, thermalMask, and boundingBox visualizations: top-level options for these are skipped to avoid double-creation, and they should be configured through the sequence options (and idleStage) instead. modelLoadingProgress is not managed by the sequence and keeps its normal lifecycle.

Configuration

JavaScriptReactVue

typescript

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

const camera = createVitalSignCamera({
  // ... other config
  visualizationOptions: {
    scanningSequence: {
      enabled: true,
      // Standby visualization (shown when not collecting data)
      idleStage: {
        faceMesh: {
          color: 'rgba(200, 200, 200, 0.6)',
          animationDirection: 'both',
          animationSpeed: 6,
          lineWidth: '0.3%'
        }
      },
      // Sweep styling
      sweepColor: 'white',
      sweepLineWidth: 0.3,
      // Final thermal step styling
      staticColor: 'rgba(255, 255, 255, 0.4)',
      staticLineWidth: 0.07,
      // Timing
      stepDurations: [2, 2, 0.5], // [horizontal, vertical, ripple] in seconds
      animationDelay: -1.5
    }
  }
});

tsx

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

const App = () => (
  <VitalSignCamera
    visualizationOptions={{
      scanningSequence: {
        enabled: true,
        idleStage: {
          faceMesh: { animationDirection: 'both', animationSpeed: 6 }
        }
      }
    }}
  />
);

vue

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

<script setup>
const visualizationOptions = {
  scanningSequence: {
    enabled: true,
    idleStage: {
      faceMesh: { animationDirection: 'both', animationSpeed: 6 }
    },
    stepDurations: [2, 2, 0.5]
  }
};
</script>

Options

Option	Type	Default	Description
`enabled`	`boolean`	`true` when present	Master toggle for the orchestrator
`idleStage`	`VisualizationOptions`	—	Visualization configuration applied while the engine stage is not `CollectingData`. Accepts the same shape as `visualizationOptions` (e.g. `faceMesh`, `thermalMask`, `boundingBox`). Declaring a `faceMesh` here is recommended so the user sees tracking feedback before and after the scan
`sweepColor`	`string`	`'white'`	Mesh color during the three animated sweep steps
`sweepLineWidth`	`number \| \`${number}%``	`0.3`	Line width during the sweep steps. Strings are percentages of the face width; bare numbers are pixels
`staticColor`	`string`	`'rgba(255, 255, 255, 0.4)'`	Mesh color for the static (non-animated) mesh in the final thermal step
`staticLineWidth`	`number \| \`${number}%``	`0.07`	Line width for the static mesh in the final thermal step
`stepDurations`	`[number, number, number]`	`[2, 2, 0.5]`	Duration in seconds of the three sweep steps, in order `[horizontal, vertical, ripple]`. The final thermal step is open-ended and persists until the engine stage changes
`animationDelay`	`number`	`-1.5`	Animation delay in seconds applied to the sweep steps. Use `0` to start at phase 0, or a negative value to start mid-cycle