guideline_cam: Package Kamera Flutter untuk Pemindaian yang Lebih Praktis

guideline_cam hadir sebagai solusi untuk menyederhanakan proses pemindaian di aplikasi Flutter. Sebelumnya, developer harus mengulang langkah kompleks seperti membuka kamera full-screen, menampilkan panduan kotak putih, mengambil gambar, lalu memprosesnya melalui OpenCV atau Firebase ML Kit sebelum akhirnya diunggah.

guideline_cam adalah package kamera Flutter yang menghilangkan semua boilerplate tersebut dengan menjalankan satu pipeline offline: pindai → auto-crop → enhancement → hasil final JPEG. Seluruhnya ditulis dengan Dart dengan package camera dan image Tanpa platform channel, tanpa native code, dan langsung jalan di Android maupun iOS untuk kebutuhan capture dokumen, ID, maupun wajah.

Package ini dikembangkan oleh LOGIQUE Digital Indonesia untuk menjawab tantangan di environment produksi yang tim kami hadapi di berbagai aplikasi KYC, onboarding, dan aplikasi mobile yang intensif dokumen. Package ini bekerja di Android & iOS dan sejak awal memang didesain khusus untuk pengambilan foto dokumen, ID, dan wajah.

Mengapa guideline_cam Lebih Baik

Quick Start

Tambahkan package:

dependencies:
  guideline_cam: ^any

Tambah permission:

• Android – AndroidManifest.xml:

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

• iOS – Info.plist:

Deskripsi mikrofon dibutuhkan oleh plugin camera, walaupun kita hanya memotret foto.

One‑liner capture (tanpa controller, tanpa StatefulWidget)

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
  ),
);

Di skenario umum (kamera 1080p), Kita akan mendapatkan JPEG yang sudah di‑crop sesuai bingkai, di‑enhance (kontras/ketajaman), dan siap dikirim ke backend / OCR.

Kontrol Penuh dengan GuidelineCamBuilder

Butuh tombol kustom, shape kompleks, atau layout yang benar-benar sesuai kebutuhan? Gunakan GuidelineCamBuilder dengan 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);
      },
    );
  }
}

Fitur Multi-Region Auto-Crop

Tentukan beberapa area (region) pada overlay, lalu biarkan kamera secara otomatis menghasilkan output hasil crop terpisah untuk masing-masing area tersebut.

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
    }
  },
);


Dengan pendekatan ini, user cukup sekali foto dan otomatis menghasilkan beberapa crop area masing masing.

Ringkasan Image Processing

guideline_cam menyediakan dua preset utama dan satu konfigurasi kustom.

Secara internal, processing berjalan di background isolate sehingga UI tetap lancar ketika filter dijalankan.

Contoh Overlay Siap Pakai

Berikut beberapa konfigurasi overlay umum yang bisa langsung kamu gunakan di aplikasi Flutter untuk berbagai kebutuhan capture dokumen maupun wajah.

1. Oval untuk Foto Paspor / Selfie Formal

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


2. Kartu Nama dengan Garis Sudut

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. Foto Mentah (Tanpa Crop & Filter)

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


Troubleshooting Cepat

Kapan Sebaiknya Menggunakan Alternatif

guideline_cam bagus untuk kebutuhan capture dokumen dan ID, namun ada beberapa situasi di mana tools lain lebih cocok digunakan:

• Membutuhkan dewarping/perspective correction intensif (kertas kusut, dokumen melengkung) : Guakan MLKit / OpenCV.
• Butuh real-time barcode / QR scanning : Gunakan mobile_scanner atau plugin khusus barcode.
• Target platform web : saat ini guideline_cam hanya support Android/iOS.

Kesimpulan

Membuat fitur foto dokumen di Flutter sering kali terasa “mudah di awal, rumit di akhir”. Tantangannya bukan hanya mengambil gambar, tetapi:

• Mengarahkan pengguna supaya hasilnya konsisten,
• Mencegah foto buruk sebelum sampai ke backend,
• Menghasilkan file yang siap dipakai untuk OCR/validasi tanpa banyak post‑processing.

guideline_cam adalah package kamera Flutter yang menawarkan serangkaian fitur untuk menjawab tantangan tersebut. Dengan guideline_cam, Kita mendapatkan:

• Overlay panduan yang sudah siap pakai untuk dokumen, KTP, maupun selfie,
• API satu baris (one-liner) untuk kebutuhan sederhana,
• GuidelineCamBuilder untuk desain UI yang lebih kompleks,
• Auto‑crop & image processing berbasis Dart,
• Implementasi yang sudah menangani thread‑safety, pembatalan operasi, dan proteksi memori.

Package ini dapat dengan mudah diintegrasikan ke dalam flow KYC atau onboarding aplikasi, lalu kembangkan overlay & processing sesuai kebutuhan bisnis. Jika Anda ingin mengintegrasikan fitur ini ke dalam proses KYC, onboarding, atau alur verifikasi lainnya, LOGIQUE siap membantu. Kami menyediakan jasa pembuatan aplikasi Flutter lengkap dengan fitur pemindaian dokumen yang andal, aman, dan sesuai kebutuhan bisnis Anda. Hubungi tim kami sekarang untuk penjelasan lebih lanjut.