README

delphi-docscanner

A production-ready Delphi/FMX JNI bridge for Google ML Kit Document Scanner on Android. Scan documents with automatic edge detection, perspective correction, and cropping — output as JPEG or multi-page PDF.

One unit. One singleton call. Zero UI code.

Features

• Automatic document detection and edge recognition
• Perspective correction and cropping
• JPEG output (per page) and PDF output (multi-page)
• Gallery import support
• ML Kit availability check (IsMLKitAvailable)
• Re-entrancy protection (IsScanning)
• Configurable output directory (OutputSubDir)

Requirements

• RAD Studio 12 Athens or later
• Target platform: Android 32-bit or 64-bit
• Minimum Android API: 21 (Android 5.0)
• Google Play Services on the target device

Installation

1. Download the dependencies

The scanner requires two Android libraries. They are published as .aar files on Google's Maven repository (not Maven Central — com.google.android.gms:* artifacts are only hosted by Google):

RAD Studio's Java references only accepts .jar files, so extract the classes.jar from inside each .aar (an .aar is a ZIP archive), rename it (e.g. play-services-mlkit-document-scanner-16.0.0.jar) and put it in your project's lib\ folder.

Alternative: Download via Gradle

Create a build.gradle in your lib\ folder — this resolves all transitive dependencies automatically:

plugins { id 'java' }
repositories {
    google()
    mavenCentral()
}
configurations { mlkit }
dependencies {
    mlkit 'com.google.android.gms:play-services-mlkit-document-scanner:16.0.0'
}
task copyDeps(type: Copy) {
    from configurations.mlkit
    into "$projectDir/deps"
}

Run: gradle copyDeps

2. Add the JARs to your Delphi project

In RAD Studio:

1. Project > Options > Delphi Compiler > Other > Java references
2. Add both .jar files (the classes.jar extracted from each .aar)
3. Set Container to Classes.dex

3. Add Search Path

Add the path to Source\ to your Delphi project search path:

Project > Options > Delphi Compiler > Search path:

<path-to>\delphi-docscanner\Source

4. AndroidManifest.template.xml

Add the following entries inside the <application> tag of your AndroidManifest.template.xml:

<!-- Google ML Kit Document Scanner -->
<service
    android:name="com.google.mlkit.common.internal.MlKitComponentDiscoveryService"
    android:exported="false"
    android:directBootAware="true">
    <meta-data
        android:name="com.google.firebase.components:com.google.mlkit.common.internal.CommonComponentRegistrar"
        android:value="com.google.firebase.components.ComponentRegistrar" />
</service>

<activity
    android:name="com.google.mlkit.vision.documentscanner.internal.GmsDocumentScanningDelegateActivity"
    android:exported="false"
    android:screenOrientation="portrait"
    android:theme="@android:style/Theme.Black.NoTitleBar.Fullscreen" />

Important: These entries must be placed inside <application>...</application>, not at the root level. Without them, the scanner will fail silently at runtime.

Quick Start

uses
  mxDocScannerUnit;

procedure TForm1.btnScanClick(Sender: TObject);
begin
  if not TmxDocScanner.Instance.IsMLKitAvailable then
  begin
    ShowMessage('ML Kit Document Scanner not available on this device.');
    Exit;
  end;

  TmxDocScanner.Instance.StartScan(
    5,           // max pages
    True,        // allow gallery import
    dsfJPEG,     // output format: dsfJPEG or dsfPDF
    procedure(const AFilePath: string; APageIndex, ATotalPages: Integer)
    begin
      // Called once per page (JPEG) or once (PDF)
      ShowMessage('Page ' + IntToStr(APageIndex + 1) + ': ' + AFilePath);
    end,
    procedure(const AErrorMessage: string)
    begin
      ShowMessage('Error: ' + AErrorMessage);
    end
  );
end;

Custom output directory

Scanned files are saved to <SharedPictures>/<OutputSubDir>/. The default subdirectory is mxDocScanner. To change it:

TmxDocScanner.Instance.OutputSubDir := 'MyApp';

Set this before calling StartScan.

API Reference

TmxDocScanner

StartScan parameters

Types

TDocScanMode   = (dsmBase, dsmBaseWithFilter, dsmFull);
TDocScanFormat = (dsfJPEG, dsfPDF);

TDocScanPageCallback  = reference to procedure(
  const AFilePath: string; APageIndex, ATotalPages: Integer);
TDocScanErrorCallback = reference to procedure(
  const AErrorMessage: string);

Scanner modes

PDF mode behavior

In PDF mode (dsfPDF), the scanner delivers both JPEG and PDF results:

1. AOnPageResult is called once per page with the JPEG file path (useful for preview)
2. AOnPageResult is called once more with the PDF file path

This allows apps to show page previews while also receiving the final PDF for upload or storage.

Edge Cases

Known Limitations

• Internal ML Kit API: The unit uses com.google.mlkit.common.sdkinternal.MlKitContext for manual initialization, which is an internal Google API. This is necessary because Delphi does not support Android ContentProvider-based auto-initialization. The class has been stable across ML Kit versions, but could change without notice in future SDK updates.
• Google Play Services required: The scanner depends on Google Play Services. Devices without GMS (e.g., Huawei) are not supported. Use IsMLKitAvailable to check at runtime.
• Singleton pattern: TmxDocScanner is designed for main-thread use. Do not call StartScan from background threads.

Cleanup

The singleton is automatically released in the finalization section. To release it manually:

TmxDocScanner.ReleaseInstance;

License

MIT License — see LICENSE for details.

Copyright (c) 2026 MicrotronX - Speditionssoftware vom Profi