Implement complete smart_face_capture Flutter package with ML Kit pose detection

[Copilot]

Implements a production-ready Flutter package for guided face photo capture using Google ML Kit for real-time head pose detection. Captures mandatory front/left/right face images automatically when correct pose is detected, with optional custom capture steps.

Core Implementation

• Face Detection Service: ML Kit integration with head pose analysis via headEulerAngleY
  • Front: yaw ∈ [-15°, 15°], Left: yaw > 20°, Right: yaw < -20°
  • Single-face validation (rejects no face, multiple faces, face too small)
• Camera Service: Camera initialization, image stream management, capture with compression
• Controller: State orchestration with 1.5s cooldown, auto-capture on pose match, manual capture for custom steps
• UI Components: Fullscreen preview, circular guide overlay, status indicators, progress dots, capture/skip buttons

Package Structure

lib/
├── smart_face_capture.dart          # Public API exports
└── src/
    ├── models.dart                  # CustomCaptureRequest, CaptureState, enums
    ├── camera_service.dart          # Camera lifecycle & capture
    ├── face_detector_service.dart   # ML Kit face detection & pose validation
    ├── smart_face_controller.dart   # State management & flow orchestration
    ├── smart_face_view.dart         # Main widget with StreamBuilder
    ├── overlays.dart                # UI overlays (guide, status, buttons)
    └── utils.dart                   # Utility functions

Usage

SmartFaceCaptureView(
  customCaptures: [
    CustomCaptureRequest(
      id: 'smile',
      label: 'Smile',
      instructionText: 'Please smile for the camera',
    ),
  ],
  onCompleted: (capturedFiles) {
    // capturedFiles[0-2]: Front, Left, Right (mandatory)
    // capturedFiles[3+]: Custom captures in order
  },
)

Platform Configuration

• Android: Camera permissions, ML Kit metadata, minSdk 21
• iOS: Camera usage description, iOS 12.0+
• Example app: Complete demo with custom captures and results screen
• Documentation: README, CHANGELOG, QUICK_START guide with setup instructions

Technical Details

• Stream-based reactive state management for UI updates
• Proper resource disposal (camera, ML Kit detector)
• Image compression to temporary storage as XFile
• Platform-specific image rotation handling for ML Kit
• No network dependencies—fully on-device processing

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• https://storage.googleapis.com/flutter_infra_release/flutter/78fc3012e45889657f72359b005af7beac47ba3d/dart-sdk-linux-x64.zip
  • Triggering command: /update-job-proxy /update-job-proxy conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT /usr/share/ca-certificates/mozilla/SSL.com_Root_Certification_Authority_ECC.crt est A_-_R3.pem test test sed -e CA1.pem /usr/share/ca-certificates/mozilla/UCA_Extended_Validation_Root.crt /bin/test cation_Authority/usr/sbin/iptables TLS_2021.crt /usr/bin/test test (http block)
  • Triggering command: /update-job-proxy /update-job-proxy ACCEPT /usr/local/sbin//etc/ssl/certs/Buypass_Class_2_Root_CA.pem sed -e pem -e test -e s/,/_/g est sed -e 18bfb83.0 -e /usr/local/sbin/test -e s/,/_/g /bin/test test (http block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

You are an autonomous senior Flutter engineer running as a GitHub Copilot Agent.

Your task is to implement a complete Flutter package from scratch.

Package name:
smart_face_capture

Goal:
Provide a reusable Flutter package that captures guided face photos:

• Mandatory guided captures: Front, Left, Right
• Optional custom extra captures with user-defined instructions

The package must be fully implemented end-to-end — not pseudo code.
All Dart files must be properly commented and documented.
A complete README.md must be written.
An example app must be included.

---

CORE TECH STACK

• Flutter stable
• camera plugin for preview & image capture
• google_mlkit_face_detection for face detection & head pose
• Return captured images as List

---

MANDATORY GUIDED CAPTURE FLOW

Sequence:

1. Front
2. Left
3. Right

Face rules:

• Exactly one face must be detected
• If zero faces: show status "No face detected"
• If multiple faces: show status "Multiple faces detected"
• Do not capture unless exactly one face is present

Head pose detection using headEulerAngleY:

• Front: yaw between -15° and +15°
• Left: yaw > +20°
• Right: yaw < -20°

When correct pose is detected:

• Auto-capture photo
• Apply 1.5 second cooldown between captures
• Save image to temporary storage
• Store result as XFile
• Move to next step

After completing Front, Left, Right → proceed to optional custom captures.

---

OPTIONAL CUSTOM CAPTURES

Allow host app to pass:

List customCaptures

CustomCaptureRequest fields:

• id (String unique key)
• label (String shown in UI)
• instructionText (String shown to user)

Custom capture behavior:

• Show instructionText
• Same single-face validation rules
• No pose restriction
• Provide manual capture button
• On button press:
  • Capture image
  • Save XFile
  • Store result mapped to id
  • Move to next custom capture

Provide Skip button to skip remaining custom captures.

---

PUBLIC API

Expose widget:

SmartFaceCaptureView

Parameters:

• List customCaptures (optional)
• CameraLensDirection initialCamera (default front)
• Function(List allCapturedFiles) onCompleted

Returned List order:

• index 0 → Front
• index 1 → Left
• index 2 → Right
• followed by custom capture files in the order provided

---

UI REQUIREMENTS

• Fullscreen camera preview
• Circular face guide overlay
• Instruction text:
  • "Look Straight"
  • "Turn Left"
  • "Turn Right"
  • Custom instructionText
• Status text:
  • "No face detected"
  • "Multiple faces detected"
  • "Move closer"
• No capture button during mandatory steps
• Manual capture button during custom steps
• Skip button during custom steps

---

PACKAGE STRUCTURE

lib/
├── smart_face_capture.dart // Public exports
└── src/
├── smart_face_view.dart
├── smart_face_controller.dart
├── camera_service.dart
├── face_detector_service.dart
├── overlays.dart
├── models.dart
└── utils.dart

example/
└── main.dart // Demonstrates mandatory + custom captures

README.md:

• What the package does
• Installation steps
• Android permissions
• iOS permissions
• Basic usage
• Custom capture usage
• Returned XFile list format
• Performance notes

---

PERMISSIONS

Android:

• Camera permission
• Runtime permission handling

iOS:

• NSCameraUsageDescription

---

NON-FUNCTIONAL

• Fully on-device
• No server calls
• Proper disposal of camera and MLKit
• Image compression to reasonable size (~300KB)
• Clean code and comments on all classes and methods

---

DELIVERABLE

Produce complete working source code:

• All Dart files
• Example app
• README.md

No placeholders. No TODOs. Full implementation.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.