Add Fixed Frame Mode with Auto-Capture and Positioning Guidance

[saade]

TLDR

This PR adds a new IndicatorShape.fixedFrame mode that displays a centered, fixed-size frame with color-coded feedback (white/red/green) and real-time positioning guidance. Includes configurable countdown timer, intelligent
face detection constraints, and debug mode for visualization. Ideal for KYC, document verification, and applications requiring consistent face capture quality.

---

Overview

This PR introduces a fixed frame capture mode that significantly improves the user experience for face capture applications by providing visual feedback and real-time guidance to help users position their
faces correctly.

Key Features

1. Fixed Frame Mode (IndicatorShape.fixedFrame)

Instead of drawing an indicator that follows the detected face, this mode displays a centered, fixed-size frame (70% of screen) that changes color based on face positioning:

• White/Gray: No face detected
• Red: Face detected but positioning requirements not met
• Green: All requirements met, ready for capture

2. Real-Time Positioning Guidance

Provides intelligent, context-aware guidance messages through messageBuilder:

• Distance: "Move closer" / "Move back"
• Horizontal: "Move left" / "Move right"
• Vertical: "Move up" / "Move down"
• Fine-tuning: "Center your face"

Messages can be fully customized for branding, localization, or specific use cases.

3. Countdown Timer

New captureDelay parameter (default: 3 seconds) adds a countdown before auto-capture:

• Displays large centered countdown number (3, 2, 1)
• Only starts when all positioning requirements are met
• Automatically cancels if face moves out of position
• Shows "Hold still..." message during countdown
• Set to 0 for immediate capture without countdown

4. Intelligent Detection Constraints

Face must meet ALL of the following criteria for green frame/countdown:

Face Distance

• Measured by eye separation (normalized distance)
• Too close: eye distance > 0.08 → "Move back"
• Too far: eye distance < 0.02 → "Move closer"
• Optimal range: 0.02 - 0.08

Landmark Positioning

• All 6 required landmarks must be inside frame (15%-85% bounds)
• Required landmarks: both eyes, nose base, 3 mouth points (left, right, bottom)
• Ears are NOT required (often not visible in close-up selfies)

Face Centering

• Nose must be near center of frame (40%-60% range)
• Ensures face is not just inside frame, but properly centered

Head Orientation

• Head rotation Y (left/right turn): ≤ 12 degrees
• Head rotation Z (sideways tilt): ≤ 12 degrees
• User must face forward with head straight

5. Debug Mode

New showDebugLandmarks parameter enables visual debugging:

• Colored landmark markers:
  • Blue: Eyes
  • Green: Nose
  • Red: Mouth
  • Yellow: Cheeks
  • Purple: Ears
  • Cyan: Face bounding box

Helps developers understand detection behavior and fine-tune positioning requirements.

---

API Changes

New Controller Parameters

captureDelay: int (default: 3)

• Countdown delay in seconds before auto-capture
• Set to 0 for immediate capture

showDebugLandmarks: bool (default: false)

• Enable colored markers for facial landmarks
• Useful for development and debugging

New Controller Method

String? getFacePositionGuidance()

• Returns current positioning guidance message
• Returns null when face is perfectly positioned
• Used in messageBuilder for custom messages

New State Field

isCapturing: bool

• Indicates if capture is currently in progress
• Prevents countdown restart during processing

Indicator Shape

IndicatorShape.fixedFrame

• New enum value for fixed centered frame mode

Technical Implementation

Coordinate System Handling

• Properly handles portrait orientation with swapped width/height
• Clamps ML Kit bounding boxes that extend beyond image bounds
• Uses normalized coordinates (0-1) for consistent calculations across devices

Face Detection Optimization

• Removed ear landmark requirement (unreliable in close-up shots)
• Relaxed eye open threshold to 40% (allows natural blinking)
• Head rotation tolerance set to 12 degrees for realistic usage

Backward Compatibility

✅ Fully backward compatible - All changes are additive:

• New IndicatorShape.fixedFrame is opt-in
• New controller parameters have sensible defaults
• Existing IndicatorShape options work unchanged
• No modifications to existing public APIs

---

Future Enhancements (Not in this PR)

Potential additions for future PRs:

• Adjustable frame size percentage
• Customizable detection thresholds
• Voice guidance option
• Haptic feedback on status change
• Photo quality scoring

[Copilot]

Pull request overview

Adds a new fixed-frame capture mode with countdown-based auto-capture, face-position guidance, and optional landmark debugging overlays to improve consistency for selfie/KYC capture flows.

Changes:

• Introduces IndicatorShape.fixedFrame and renders a centered fixed frame with red/green/neutral feedback.
• Adds countdown state + timer-driven auto-capture gating (captureDelay, countdown, isCapturing, isFaceWellPositioned).
• Adds positioning guidance API (getFacePositionGuidance) and optional debug landmark rendering (showDebugLandmarks).

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 12 comments.

Show a summary per file

File	Description
lib/src/smart_face_camera.dart	Passes new painter flags and overlays countdown UI during auto-capture.
lib/src/res/enums.dart	Adds the fixedFrame indicator shape enum value.
lib/src/paints/face_painter.dart	Implements fixed frame drawing and debug landmark/bounding-box rendering.
lib/src/handlers/face_identifier.dart	Adjusts positioning thresholds and relaxes landmark requirements (ears).
lib/src/controllers/face_camera_state.dart	Adds countdown/capturing/well-positioned fields and copyWith support.
lib/src/controllers/face_camera_controller.dart	Implements countdown timer, centered-face checks, and guidance messaging API.
example/lib/main.dart	Demonstrates fixed frame mode, countdown messaging, and custom guidance text.
README.md	Documents fixed frame mode, constraints, debug landmarks, and countdown configuration.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 4 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[saade]

Everything should be fixed by now, ready for review