Face Mesh

The face mesh visualization renders a 468-point facial landmark wireframe overlay. It provides detailed visual feedback about face detection quality and tracking precision.

How It Works

The SDK's face mesh module detects 468 facial landmarks in real-time, mapping the contours of eyes, eyebrows, nose, mouth, and jawline. The visualization draws connecting lines between these points to form a wireframe mesh overlay on the detected face. An optional sweep animation provides a subtle scanning appearance to confirm active tracking.

Configuration

JavaScript

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

const camera = createVitalSignCamera({
  // ... other config
  visualizationOptions: {
    faceMesh: {
      enabled: true,
      color: 'lightgreen',       // Wireframe color (default: 'lightgreen')
      lineWidth: '1%',           // Pixels or % of face width (default: '1%')
      animate: true,             // Sweep animation (default: true)
      animationDirection: 'both',// 'horizontal' | 'vertical' | 'both' | 'ripple'
      animationSpeed: 1.0,       // Animation duration in seconds
      animationDelay: 0,         // CSS animation-delay in seconds
      simplifyFaceMesh: false    // Remove outer perimeter + zigzag mesh (default: false)
    }
  }
});

React

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

const App = () => (
  <VitalSignCamera
    visualizationOptions={{
      faceMesh: {
        enabled: true,
        color: '#00ff88',
        animate: true,
        animationDirection: 'ripple'
      }}
    }}
  />
);

Vue

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

<script setup>
const visualizationOptions = {
  faceMesh: {
    enabled: true,
    color: '#64ffda',
    lineWidth: '0.5%',
    animate: true,
    animationDirection: 'both',
    animationSpeed: 6,
    simplifyFaceMesh: true
  }
};
</script>

Animation Directions

Direction	Behavior
'vertical'	Up-down sweep across the mesh (default when not set)
'horizontal'	Left-right sweep across the mesh
'both'	Four-way sweep
'ripple'	Ripple expanding from the nose tip

The sweep is a CSS mask animation over the wireframe; animationSpeed controls the duration of one sweep in seconds and animationDelay offsets the start of the animation (use a negative value to start mid-cycle).

Simplified Mesh

Set simplifyFaceMesh: true to remove the outer perimeter and the surrounding structural zigzag connections, leaving a cleaner mesh that focuses on the facial contours. This is useful when the full mesh is too visually busy (for example on small screens).

Dynamic Updates

// Change animation direction
camera.visualizationOptions = {
  ...camera.visualizationOptions,
  faceMesh: { animationDirection: 'ripple' }
};

// Simplify the mesh
camera.visualizationOptions = {
  ...camera.visualizationOptions,
  faceMesh: { simplifyFaceMesh: true }
};

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

FaceMeshOptions Interface

type FaceMeshAnimationDirection = 'horizontal' | 'vertical' | 'both' | 'ripple';

interface FaceMeshOptions {
  enabled?: boolean;                  // Enable/disable the overlay
  color?: string;                     // CSS color (default: 'lightgreen')
  lineWidth?: number | `${number}%`;  // Pixels, or % of face width (default: '1%')
  animate?: boolean;                  // Enable sweep animation (default: true)
  animationSpeed?: number;            // Animation duration in seconds
  animationDelay?: number;            // CSS animation-delay in seconds
  animationDirection?: FaceMeshAnimationDirection;
  simplifyFaceMesh?: boolean;         // Remove outer perimeter + zigzag connections (default: false)
}

TIP

When the scanning sequence orchestrator is enabled, it owns the face mesh (and thermal mask / bounding box) lifecycle. Configure the mesh for the sequence through the sequence's own options and idleStage instead of a top-level faceMesh option.