📸 GuidelineCamBuilder #

A lightweight Flutter package that helps build guideline camera overlay to capture IDs, documents, or faces. Supports rectangles, rounded rectangles, circles, and ovals for manual image capture.

🎬 Demo Gallery #


Basic Usage	Custom Button	Overlay Builder

Built-in Instruction Builder	Multi & Nested Shape	Static API

🚀 Quick Start #

1. Install #

dependencies:
  guideline_cam: ^0.0.3

2. Add permissions #

Android → AndroidManifest.xml

<uses-permission android:name="android.permission.CAMERA" />

iOS → Info.plist

<key>NSCameraUsageDescription</key>
<string>We need access to the camera to capture your document/ID</string>
<key>NSMicrophoneUsageDescription</key>
<string>We need access to the micrphone to capture your document/ID</string>

3. Quick Capture (Simplified API) #

For simple use cases, use the static takePhoto() method - no controller management needed:

import 'package:guideline_cam/guideline_cam.dart';

// Simple one-liner capture
final XFile? photo = await GuidelineCam.takePhoto(
  context: context,
  guideline: GuidelineOverlayConfig(
    shape: GuidelineShape.roundedRect,
    aspectRatio: 1.586, // ID card ratio
  ),
);

// Use front camera for selfie capture
final XFile? photo = await GuidelineCam.takePhoto(
  context: context,
  cameraDirection: CameraLensDirection.front,
  guideline: GuidelineOverlayConfig(
    shape: GuidelineShape.circle,
  ),
);

if (photo != null) {
  // Handle captured photo
  print('Photo captured: ${photo.path}');
}

4. Advanced Usage (Full Control) #

import 'package:flutter/material.dart';
import 'package:guideline_cam/guideline_cam.dart';

class CapturePage extends StatefulWidget {
  @override
  _CapturePageState createState() => _CapturePageState();
}

class _CapturePageState extends State<CapturePage> {
  late GuidelineCamController _controller;

  @override
  void initState() {
    super.initState();
    _controller = GuidelineCamController();
    _controller.initialize();
  }

  @override
  void dispose() {
    _controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text("GuidelineCamBuilder Example")),
      body: GuidelineCamBuilder(
        controller: _controller,
        guideline: GuidelineOverlayConfig(
          shape: GuidelineShape.roundedRect,   // 👈 try GuidelineShape.circle
          aspectRatio: 3 / 2, // Width : height
          frameColor: Colors.green,
          maskColor: Colors.black54,
        ),
        flashButtonBuilder: (context, flashMode, onPressed) {
          return FloatingActionButton(
            onPressed: onPressed,
            backgroundColor: flashMode == FlashMode.off ? Colors.red : Colors.green,
            child: Icon(flashMode == FlashMode.off ? Icons.flash_off : Icons.flash_on),
          );
        },
        cameraSwitchButtonBuilder: (context, lensDirection, onPressed) {
          return FloatingActionButton(
            onPressed: onPressed,
            backgroundColor: Colors.blue,
            child: Icon(lensDirection == CameraLensDirection.back ? Icons.camera_front : Icons.camera_rear),
          );
        },
        onCapture: (result) {
          // Handle the captured image
          // result.file contains the captured image file
        },
      ),
    );
  }
}

🎨 Overlay Options #

GuidelineShape.rect → plain rectangle
GuidelineShape.roundedRect → rectangle with border radius (default)
GuidelineShape.circle → circle (ideal for face/biometric capture)
GuidelineShape.oval → oval (e.g. passport photo frame)

⚡ Example: switch to a circle for face capture

guideline: GuidelineOverlayConfig(
  shape: GuidelineShape.circle,
  frameColor: Colors.blueAccent,
  maskColor: Colors.black54,
),

🎛️ Custom Button Builders #

You can customize the flash toggle and camera switch buttons by providing your own builders:

GuidelineCamBuilder(
  controller: controller,
  guideline: const GuidelineOverlayConfig(),
  flashButtonBuilder: (context, flashMode, onPressed) {
    return Container(
      decoration: BoxDecoration(
        color: flashMode == FlashMode.off ? Colors.red : Colors.green,
        borderRadius: BorderRadius.circular(20),
      ),
      child: Material(
        color: Colors.transparent,
        child: InkWell(
          borderRadius: BorderRadius.circular(20),
          onTap: onPressed,
          child: Padding(
            padding: const EdgeInsets.all(12),
            child: Row(
              mainAxisSize: MainAxisSize.min,
              children: [
                Icon(
                  flashMode == FlashMode.off ? Icons.flash_off : Icons.flash_on,
                  color: Colors.white,
                ),
                const SizedBox(width: 4),
                Text(
                  flashMode == FlashMode.off ? 'OFF' : 'ON',
                  style: const TextStyle(color: Colors.white),
                ),
              ],
            ),
          ),
        ),
      ),
    );
  },
  cameraSwitchButtonBuilder: (context, lensDirection, onPressed) {
    return FloatingActionButton(
      onPressed: onPressed,
      backgroundColor: Colors.blue,
      child: Icon(
        lensDirection == CameraLensDirection.back
            ? Icons.camera_front
            : Icons.camera_rear,
      ),
    );
  },
)

The builders receive:

context: BuildContext for the widget
flashMode/lensDirection: Current state for styling
onPressed: Callback to trigger the action

If no custom builders are provided, default FloatingActionButton.small widgets are used.

Complete Overlay Control #

For maximum flexibility, you can provide a custom overlayBuilder to completely control the overlay layout:

GuidelineCamBuilder(
  controller: controller,
  guideline: const GuidelineOverlayConfig(),
  overlayBuilder: (context, controller) {
    return Stack(
      children: [
        // Custom positioned flash button
        Positioned(
          bottom: 100,
          right: 20,
          child: FloatingActionButton(
            onPressed: () async {
              final currentMode = controller.flashMode;
              final newMode = currentMode == FlashMode.off
                  ? FlashMode.always
                  : FlashMode.off;
              await controller.setFlashMode(newMode);
            },
            backgroundColor: controller.flashMode == FlashMode.off
                ? Colors.red
                : Colors.green,
            child: Icon(controller.flashMode == FlashMode.off
                ? Icons.flash_off
                : Icons.flash_on),
          ),
        ),
        // Custom positioned camera switch button
        Positioned(
          bottom: 100,
          left: 20,
          child: FloatingActionButton(
            onPressed: () async {
              await controller.switchCamera();
            },
            backgroundColor: Colors.blue,
            child: Icon(controller.lensDirection == CameraLensDirection.back
                ? Icons.camera_front
                : Icons.camera_rear),
          ),
        ),
        // Custom capture button
        Positioned(
          bottom: 20,
          left: 0,
          right: 0,
          child: Center(
            child: FloatingActionButton.large(
              onPressed: () async {
                final result = await controller.capture();
                // Handle result
              },
              child: const Icon(Icons.camera_alt),
            ),
          ),
        ),
        // Custom status indicator
        Positioned(
          top: 50,
          left: 0,
          right: 0,
          child: Center(
            child: Container(
              padding: const EdgeInsets.all(8),
              decoration: BoxDecoration(
                color: Colors.black54,
                borderRadius: BorderRadius.circular(16),
              ),
              child: Text(
                'State: ${controller.state.name}',
                style: const TextStyle(color: Colors.white),
              ),
            ),
          ),
        ),
      ],
    );
  },
)

The overlayBuilder receives:

context: BuildContext for the widget
controller: GuidelineCamController with all camera controls

When overlayBuilder is provided, it completely replaces the default overlay system, giving you full control over positioning, styling, and layout.

Multi-Shape Overlays #

For complex capture scenarios like ID cards with face photos, you can use multiple shapes in a single overlay:

GuidelineCamBuilder(
  controller: controller,
  guideline: GuidelineOverlayConfig(
    shapes: [
      // Face oval - top portion
      ShapeConfig(
        shape: GuidelineShape.oval,
        bounds: Rect.fromLTWH(50, 100, 200, 250),
        frameColor: Colors.blue,
        strokeWidth: 3.0,
        showGrid: true,
      ),
      // ID card rectangle - bottom portion
      ShapeConfig(
        shape: GuidelineShape.roundedRect,
        bounds: Rect.fromLTWH(20, 400, 300, 200),
        frameColor: Colors.green,
        strokeWidth: 3.0,
        borderRadius: 16.0,
        cornerLength: 30.0,
        showGrid: true,
      ),
    ],
    maskColor: Colors.black54,
  ),
)

The ShapeConfig class provides:

shape: The type of shape (rect, roundedRect, circle, oval)
bounds: Exact positioning and size using Rect
frameColor: Color of the shape outline
strokeWidth: Thickness of the outline
borderRadius: Corner radius for rounded rectangles
cornerLength: Length of corner indicators
showGrid: Whether to show a 3x3 grid inside the shape

Multi-shape overlays provide a unified mask covering the entire screen except the defined shapes, making it perfect for complex document capture scenarios.

Nested Shapes (Parent-Child Relationships) #

For even more complex scenarios, you can create nested shapes where child shapes are positioned relative to their parent. This is perfect for ID cards with photo areas, signature sections, or any document with multiple distinct regions.

GuidelineCamBuilder(
  controller: controller,
  guideline: GuidelineOverlayConfig(
    shapes: [
      // Parent shape - ID card frame
      ShapeConfig(
        shape: GuidelineShape.roundedRect,
        bounds: Rect.fromLTWH(50, 100, 300, 400),
        frameColor: Colors.green,
        strokeWidth: 3.0,
        borderRadius: 16.0,
        children: [
          // Child 1: Centered photo area
          ShapeConfig.centered(
            shape: GuidelineShape.rect,
            size: Size(80, 100), // Absolute size
            frameColor: Colors.white,
            strokeWidth: 2.0,
          ),
          // Child 2: Relative positioned signature area
          ShapeConfig.relativePosition(
            shape: GuidelineShape.rect,
            relativeOffset: Offset(0.7, 0.8), // 70% right, 80% down
            size: Size(0.4, 0.15), // 40% of parent width, 15% of parent height
            frameColor: Colors.blue,
            strokeWidth: 2.0,
          ),
          // Child 3: Inset positioned text area
          ShapeConfig.inset(
            shape: GuidelineShape.rect,
            insets: EdgeInsets.only(left: 20, top: 20, right: 20, bottom: 20),
            size: Size(0.6, 0.3), // 60% of parent width, 30% of parent height
            frameColor: Colors.orange,
            strokeWidth: 1.5,
          ),
        ],
      ),
    ],
  ),
)

Positioning Modes

ShapePositioning.absolute: Uses fixed coordinates (default behavior)
ShapePositioning.center: Automatically centers the child within the parent
ShapePositioning.relative: Positions using percentage offsets (0.0 to 1.0)
ShapePositioning.inset: Positions with pixel offsets from parent edges

Size Options

Absolute size: Size(100, 150) - fixed pixel dimensions
Relative size: Size(0.3, 0.4) - percentage of parent (30% width, 40% height)

Convenience Constructors

ShapeConfig.centered() - Creates a centered child shape
ShapeConfig.inset() - Creates a child with inset positioning
ShapeConfig.relativePosition() - Creates a child with relative positioning

Nested shapes support unlimited depth - children can have their own children, creating complex hierarchical layouts.

Static API vs Manual Controller #

Feature	Static API (`GuidelineCam.takePhoto()`)	Manual Controller (`GuidelineCamBuilder`)
Setup	One method call	StatefulWidget + controller lifecycle
Boilerplate	Minimal	Requires initState/dispose
Customization	Through parameters	Full control via builders
Use Case	Simple capture scenarios	Complex UI, custom workflows
Return Value	`XFile?`	`GuidelineCaptureResult` via callback

When to Use Each #

Use Static API when:

You need quick photo capture
Minimal configuration is enough
You don't need advanced UI control
You want automatic resource management

Use Manual Controller when:

You need custom UI layouts
You want to integrate into existing pages
You need advanced state management
You want to reuse the controller across multiple captures

Troubleshooting #

Flash not supported: The flash toggle will be hidden if the device does not support it.
Focus tips: Tap on the screen to focus on a specific area.

📚 API Reference #

GuidelineCam (Static API) #

static Future<XFile?> takePhoto({
  required BuildContext context,
  GuidelineOverlayConfig? guideline,
  CameraLensDirection cameraDirection = CameraLensDirection.back,
  bool showFlashToggle = true,
  bool showCameraSwitch = true,
  Color backgroundColor = Colors.black,
  Widget Function(BuildContext, GuidelineState)? instructionBuilder,
})

Simplified API for quick photo capture. Returns XFile? containing the captured image, or null if cancelled or error occurs.

Parameter	Type	Required	Default	Description
context	BuildContext	Yes	-	Build context for navigation
guideline	GuidelineOverlayConfig?	No	Default config	Overlay configuration
cameraDirection	CameraLensDirection	No	CameraLensDirection.back	Initial camera direction
showFlashToggle	bool	No	true	Show flash toggle button
showCameraSwitch	bool	No	true	Show camera switch button
backgroundColor	Color	No	Colors.black	Background color
instructionBuilder	Widget Function(...)?	No	-	Custom instruction widget