Precision Mode

INFO

Note: Precision Mode is currently available for web SDKs (JavaScript, React, Vue) only.

Precision Mode allows you to control the trade-off between measurement accuracy and device performance requirements. The Vitals™ SDK provides two precision modes: Relaxed and Strict, each optimized for different use cases and device capabilities.

Overview

Precision Mode affects several aspects of the vital sign measurement process:

• Data Collection Duration: How long data is collected during scanning
• Face Detection Requirements: Frame rate and detection frequency requirements
• Region of Interest (ROI): Which facial and body areas are analyzed
• Data Resolution: Pixel data type and sampling rates
• Automatic Mode Switching: Dynamic adjustment based on device performance

INFO

Server Versions and Legacy Mode: If precision mode is not set, the SDK falls back to legacy mode, which connects to the V1 server (NyanCat backend). If precision mode is set to relaxed or strict, the V2 server (CrimsonLion backend) is used.

Precision Mode Types

Legacy Mode

Legacy mode is the fallback when precision mode is not explicitly set. It uses default settings for backward compatibility and connects to the V1 server.

Key Characteristics:

• Standard data collection and analysis durations
• Default frame rate requirements
• Basic facial regions analyzed
• Lower resolution pixel data
• Compatible with older SDK versions

Suitable For:

• Existing applications not yet updated to specify precision mode
• Basic compatibility needs
• When specific precision tuning is not required

Relaxed Mode

Relaxed mode prioritizes compatibility and performance on lower-end devices. It uses more lenient scanning conditions and is suitable for:

• Mobile phones with limited processing power
• Environments with variable lighting conditions
• Quick assessments where high precision is not critical
• Battery-constrained devices

Key Characteristics:

• Longer data collection duration (25 seconds)
• Shorter data analyzing duration (5 seconds)
• Lower minimum frame rate requirements (10-15 FPS)
• Fewer facial regions analyzed
• Lower resolution pixel data
• More tolerant of suboptimal conditions

Strict Mode

Strict mode maximizes measurement accuracy by requiring optimal scanning conditions. It provides the highest precision measurements but demands more from the device:

• High-performance devices (tablets, desktops)
• Well-controlled environments
• Medical or research applications
• When maximum accuracy is essential

Key Characteristics:

• Shorter data collection duration (18 seconds)
• Longer data analyzing duration (10 seconds)
• Higher minimum frame rate requirements (25 FPS)
• More facial regions analyzed (face, chest, cheeks, chin, glabella)
• Higher resolution pixel data
• Requires stable, optimal conditions

Usage

Setting Precision Mode

Set the precision mode when creating the Vital Sign Camera. If precision mode is not specified, the SDK will fall back to legacy mode using the V1 server.

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

const camera = createVitalSignCamera({
  isActive: true,
  sdkCredentials: {
    apiKey: "your-api-key",
    userId: "your-user-id"
  },
  userInfo: {
    age: 30,
    gender: Gender.Male
  },
  precisionMode: PrecisionMode.relaxed  // or PrecisionMode.strict, or omit for legacy mode
});

Dynamic Mode Switching

You can change the precision mode at runtime:

// Switch to strict mode for higher accuracy
camera.precisionMode = PrecisionMode.strict;

// Switch to relaxed mode for better performance
camera.precisionMode = PrecisionMode.relaxed;

Automatic Mode Adjustment

The SDK automatically switches from strict to relaxed mode if device performance is insufficient:

camera.onPrecisionModeWillUpdate = (event) => {
  console.log(`Precision mode will change from ${event.currentMode} to ${event.newMode}`);
  console.log(`Reason: ${event.reason}`);

  // Allow or delay the automatic switch
  if (event.reason === 'lowFrameRate') {
    // Ask user for confirmation or delay the switch
    event.response('wait');  // Wait for better conditions
    // or event.response('proceed');  // Proceed with switch
  }
};

camera.onPrecisionModeUpdated = (event) => {
  console.log(`Precision mode changed from ${event.previousMode} to ${event.currentMode}`);
  console.log(`Reason: ${event.reason}`);

  // Update UI to reflect the new mode
  updateUIMode(event.currentMode);
};

Performance Considerations

Device Requirements

Device Type	Recommended Mode	Minimum Frame Rate	Supported Resolution
Mobile Phone	Relaxed	10 FPS	480x360
Tablet	Relaxed/Strict	15-25 FPS	1280x720
Desktop	Strict	25 FPS	1920x1080

Battery Impact

• Relaxed Mode: Lower power consumption, suitable for battery-powered devices
• Strict Mode: Higher power consumption due to increased processing and higher resolution

Network Usage

• Relaxed Mode: Smaller data payloads, faster transmission
• Strict Mode: Larger data payloads due to higher resolution pixel data

Best Practices

Choosing the Right Mode

1. Start with Relaxed Mode for broad compatibility

2. Use Strict Mode when:

   • Device performance allows it
   • Maximum accuracy is required
   • Environmental conditions are optimal
   • User is stationary and well-lit

3. Monitor Performance and allow automatic switching

4. Provide User Control to manually adjust mode based on preferences

5. Legacy Mode (when precision mode is not set) uses the V1 server for backward compatibility but may have limited features compared to V2

Handling Mode Changes

function handlePrecisionModeChange(newMode: PrecisionMode) {
  // Update UI indicators
  updateModeIndicator(newMode);

  // Adjust scanning instructions based on mode
  if (newMode === PrecisionMode.strict) {
    showStrictModeInstructions();
  } else {
    showRelaxedModeInstructions();
  }

  // Log for analytics
  analytics.track('precision_mode_changed', { mode: newMode });
}

Error Handling

camera.onError = (error) => {
  if (error.message.includes('frame rate')) {
    // Frame rate too low for current mode
    console.log('Consider switching to relaxed mode for better compatibility');

    // Optionally auto-switch to relaxed mode
    if (camera.precisionMode === PrecisionMode.strict) {
      camera.precisionMode = PrecisionMode.relaxed;
    }
  }
};

Troubleshooting

Common Issues

Frame rate too low for strict mode

• Solution: Switch to relaxed mode or improve lighting/camera setup
• Automatic switching should handle this, but manual intervention may be needed

Inconsistent measurements in relaxed mode

• Solution: Try strict mode if device capabilities allow
• Check environmental conditions (lighting, motion, distance)

App performance degraded in strict mode

• Solution: Switch to relaxed mode or optimize device settings
• Consider battery life impact on mobile devices

Performance Monitoring

Monitor key metrics to determine optimal mode:

camera.onVideoFrameProcessed = (event) => {
  const frameRate = event.frameInfo?.frameRate;
  const mode = camera.precisionMode;

  // Log performance metrics
  console.log(`Frame rate: ${frameRate} FPS, Mode: ${mode}`);

  // Alert if performance is marginal
  if (mode === PrecisionMode.strict && frameRate < 25) {
    console.warn('Frame rate below strict mode requirements');
  }
};

API Reference

PrecisionMode Enum

enum PrecisionMode {
  relaxed = 'relaxed',  // More tolerant, better performance
  strict = 'strict'     // Higher accuracy, stricter requirements
}

Events

• onPrecisionModeWillUpdate: Fired before automatic mode change (allows intervention)
• onPrecisionModeUpdated: Fired after mode change (for UI updates)

Properties

• precisionMode: Current precision mode (get/set)
• PrecisionMode: Enum for mode values

Conclusion

Precision Mode provides a powerful way to balance measurement accuracy with device performance and user experience. By understanding the trade-offs between relaxed and strict modes, you can optimize your application for different use cases and device capabilities. The automatic mode switching feature ensures reliable operation across a wide range of conditions while maintaining the best possible accuracy.