Ensemble Face Camera Module

The ensemble_face_camera module provides face detection capabilities to the Ensemble framework. It is a standalone module extracted from the original ensemble_camera package.

Features

• Real-time face detection on both Mobile and Web.
• Customizable detection parameters (threshold, yaw, tilt, etc.).
• Integration with Ensemble Action system via openFaceCamera.

Installation

Enable from Starter (recommended)

From the starter app, run the module enable script to add the dependency, register FaceCameraManagerImpl, set useFaceCamera in lib/generated/ensemble_modules.dart, and apply platform permissions:

cd starter
npm run hasFaceCamera
flutter pub get

For specific platforms (for example Android, iOS, and web):

dart scripts/modules/enable_face_camera.dart platform=android,ios,web

On web, the script also adds script tags for assets/packages/ensemble_face_camera/web/face_api.js and assets/packages/ensemble_face_camera/web/face_detection.js in web/index.html.

Manual setup

Add the following to your pubspec.yaml:

dependencies:
  ensemble_face_camera:
    git:
      url: https://github.com/EnsembleUI/ensemble.git
      ref: main
      path: modules/face_camera

Action Registration

To use the openFaceCamera action, you must register it in your Ensemble application (usually in lib/generated/ensemble_modules.dart or a dedicated setup file):

import 'package:ensemble_face_camera/ensemble_face_camera.dart';

// ... inside your initialization logic

GetIt.I.registerSingleton<FaceCameraManager>(FaceCameraManagerImpl());

Usage

YAML Action

The openFaceCamera action consolidates all configuration into the options map. While top-level properties (like message) are still supported for backward compatibility, it is recommended to place them inside options.

onTap:
  openFaceCamera:
    id: myFaceCamera
    options:
      initialCamera: front       # front (default) or back
      performanceMode: fast      # fast (default) or accurate
      imageResolution: high      # low, medium, high, veryHigh, ultraHigh, max
      defaultFlashMode: off      # off (default), auto, always
      orientation: portraitUp    # portraitUp (default), portraitDown, landscapeLeft, landscapeRight
      
      message: "Align your face" # Custom message to display
      messageStyle:              # Custom text style for the message
        color: 0xFFFFFFFF
        fontSize: 18
      
      indicatorShape: circle     # circle (default) or square
      showStatusMessage: true    # Show/hide the detection status message
      
      showControls: true         # Show/hide all camera controls
      showCaptureControl: true   # Show/hide the capture button
      showFlashControl: true     # Show/hide the flash toggle
      showCameraLensControl: true # Show/hide the camera switch button
      
      autoCapture: false         # Automatically capture when face is aligned
      autoDisableCaptureControl: false # Disable capture button until face is detected

      accuracyConfig:            # Fine-tune detection accuracy
        threshold: 0.6           # Detection threshold (0.0 to 1.0)
        yaw: 15                  # Maximum allowed face rotation (horizontal)
        tilt: 15                 # Maximum allowed face tilt (vertical)
        minFaceSize: 0.15        # Minimum face size relative to frame
        
    onCapture: |
      print('Face captured: ' + event.data.files[0].path);
    onError: |
      print('Error: ' + event.error);

Dart Widget

You can also use the FaceDetectionCamera widget directly in your Dart code:

import 'package:ensemble_face_camera/face_detection_camera.dart';

// ...
FaceDetectionCamera(
  onCapture: (file) => print('Captured: ${file?.path}'),
  onError: (error) => print('Error: $error'),
)

Migration from ensemble_camera

If you were previously using openCamera with faceDetection: enabled: true, follow these steps:

1. Add ensemble_face_camera to your pubspec.yaml.
2. Replace openCamera with openFaceCamera in your YAML.
3. Remove faceDetection: enabled: true from the options as it's now implicit.
4. Call GetIt.I.registerSingleton<FaceCameraManager>(FaceCameraManagerImpl()); in your app initialization.