guideline_cam: A Flutter Camera Package for Seamless Scanning

Most Flutter apps that need document or ID scanning end up rebuilding the same painful flow: open a full-screen camera, draw a white rectangle so users know where to put their card, capture a photo, send it to OpenCV or Firebase ML Kit, wait for edge detection, process the image on a server, then finally upload it.

guideline_cam is a Flutter camera package that kills all that boilerplate. It runs a single offline pipeline  capture → auto-crop → enhancement → final JPEG . Written entirely in pure Dart on top of the camera and image packages. No platform channels, no native code, and it works on both Android and iOS for document, ID, and face capture out of the box.

The package was built by LOGIQUE Digital Indonesia to solve real production challenges our teams face across multiple KYC, onboarding, and document-intensive mobile apps. The package works on Android & iOS and is designed specifically for document, ID, and face capture.

Why guideline_cam is Better

Quick Start

Install the package:

dependencies:
  guideline_cam: ^any

Add permissions:

• Android – AndroidManifest.xml:

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

• iOS – Info.plist:

The microphone description is required by the underlying camera plugin even if you only capture still images.

One-liner capture (no controller, no widget tree)

import 'package:guideline_cam/guideline_cam.dart';

final XFile? idCard = await GuidelineCam.takePhoto(
  context: context,
  enableCrop: true,  // Auto-crops to guideline boundaries
  enableProcessing: true, // Runs the configured processing preset
  guideline: GuidelineOverlayConfig(
    shape: GuidelineShape.roundedRect,
    aspectRatio: 1.586,  // Standard card ratio
    processing: ImageProcessingConfig.idCard, // Color + enhance + sharpen
  ),
);

In a typical 1080p scenario, this gives you a cropped, enhanced JPEG with size generally in the 200–400 KB range depending on the JPEG quality configuration, small enough for network upload, good enough for OCR / review.

Going Pro: Full-Control Builder

Need custom buttons, nested shapes, or your own layout? Use GuidelineCamBuilder with a controller.

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

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

  @override
  void dispose() {
    _controller.dispose(); // Cleans up resources & cancels ongoing ops
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return GuidelineCamBuilder(
      controller: _controller,
      guideline: GuidelineOverlayConfig(
        shape: GuidelineShape.roundedRect,
        aspectRatio: 1.414, // A4 ratio
        cropConfig: CropConfig(
          padding: 10, // Safety border to avoid cut-off
          mode: CropMode.guideline,
          strategy: CropStrategy.outermost,
        ),
        processing: ImageProcessingConfig.documentScan, // grayscale + sharpen
      ),
      onCapture: (result) {
        // result.file          → final best version (processed > cropped > original)
        // result.originalFile  → raw uncropped image
        // result.croppedFiles  → list of crops (for multi-shape)
        // result.processedFile → processed image (if enabled)
        upload(result.file);
      },
    );
  }
}

Multi-Region Auto-Crop Support

Define multiple regions on the overlay and let the camera automatically produce separate cropped outputs for each one.

GuidelineCamBuilder(
  controller: _controller,
  guideline: GuidelineOverlayConfig(
    shapes: [
      ShapeConfig(
        shape: GuidelineShape.rect,
        bounds: Rect.fromLTWH(40, 80, 320, 200),  // Front
      ),
      ShapeConfig(
        shape: GuidelineShape.rect,
        bounds: Rect.fromLTWH(40, 320, 320, 200), // Back
      ),
    ],
    cropConfig: CropConfig(
      mode: CropMode.guideline,
      strategy: CropStrategy.eachShape, // Multiple crops
    ),
    processing: ImageProcessingConfig.idCard,
  ),
  onCapture: (result) {
    if (result.croppedFiles.length >= 2) {
      final front = result.croppedFiles[0];
      final back  = result.croppedFiles[1];
      uploadFront(front);
      uploadBack(back);
    } else {
      // Fallback: use result.file or result.originalFile
    }
  },
);

This matches the multi-shape, where CropStrategy.eachShape returns one image per defined shape.

Image Processing Cheat-Sheet

The package ships with presets and a fully-customizable config.

Internally, image processing runs in background isolates so our UI can stay at 60 fps even on mid-range devices.

Ready-to-Use Overlay Examples

Below are several common overlay configurations you can drop directly into your Flutter app to support different document and face-capture scenarios.

1. Passport Face Oval

GuidelineOverlayConfig(
  shape: GuidelineShape.oval,
  aspectRatio: 0.75, // 3:4 portrait
  maskColor: Colors.black38,
  cropConfig: CropConfig(
    mode: CropMode.guideline,
    padding: 5.0,
  ),
)

2. Business Card with Corner Guides

GuidelineOverlayConfig(
  shape: GuidelineShape.roundedRect,
  aspectRatio: 1.75,
  cornerLength: 24, // L-shaped corner indicators
  strokeWidth: 3,
  frameColor: Colors.cyanAccent,
  cropConfig: CropConfig(
    mode: CropMode.guideline,
    padding: 5.0,
  ),
)

3. Disable Everything (Raw Photo)

GuidelineOverlayConfig(
  cropConfig: CropConfig(enabled: false), // No auto-crop
  processing: null,                       // No processing
)

Troubleshooting Quick Hits

When to Use Alternatives Instead

guideline_cam is powerful for document and ID capture, but there are cases where other tools fit better:

• You need aggressive perspective correction / dewarping of crumpled pages : use MLKit / OpenCV.
• You need real-time barcode / QR scanning : use mobile_scanner or a dedicated barcode plugin.
• You target web : this package is currently mobile-only (Android/iOS).

Conclusion

Professional Flutter document capture is less about fancy camera tricks and more about:

• Guiding users to frame documents correctly,
• Preventing bad captures before they happen,
• Producing consistent, upload-ready images every time.

With guideline_cam you get:

• Visual overlays that just work for documents, IDs, and faces,
• A one-line static API for simple flows,
• A full-control builder for bespoke UX,
• Auto-crop & enhancement implemented in pure Dart,
• Thread-safe, cancellable, memory-aware internals tuned for mobile.

Drop it into your KYC / onboarding / document flow, track your rejection rate, and then iterate with multi-shape overlays and custom processing as your requirements grow.