KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #developer-tools #ai-agent #claude-code #codex #typescript #ai-agents #deepseek-harness #mcp #cli #rust

delphi-docscanner

★ 17 Open GitHub ↗

Google ML Kit Document Scanner for Delphi/FMX Android — JPEG & PDF output, one unit, zero UI code

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 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):

| Dependency | Version | Direct download (`.aar`) |
|---|---|---|
| play-services-mlkit-document-scanner | 16.0.0 | [dl.google.com](https://dl.google.com/dl/android/maven2/com/google/android/gms/play-services-mlkit-document-scanner/16.0.0/play-services-mlkit-document-scanner-16.0.0.aar) |
| mlkit-common (`com.google.mlkit:common`) | 18.11.0 | [dl.google.com](https://dl.google.com/dl/android/maven2/com/google/mlkit/common/18.11.0/common-18.11.0.aar) |

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:

```gradle
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`:

```xml

<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

```pascal
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:

```pascal
TmxDocScanner.Instance.OutputSubDir := 'MyApp';
```

Set this **before** calling `StartScan`.

## API Reference

### TmxDocScanner

| Member | Description |
|---|---|
| `class function Instance: TmxDocScanner` | Singleton access |
| `class procedure ReleaseInstance` | Free the singleton (typically not needed) |
| `function IsMLKitAvailable: Boolean` | Check if ML Kit Document Scanner is available on the device |
| `procedure StartScan(...)` | Start a document scan |
| `property IsScanning: Boolean` | `True` while a scan is in progress |
| `property OutputSubDir: string` | Subdirectory name for scanned files (default: `'mxDocScanner'`) |

### StartScan parameters

| Parameter | Type | Description |
|---|---|---|
| `AMaxPages` | `Integer` | Maximum number of pages to scan |
| `AGalleryImport` | `Boolean` | Allow importing images from gallery |
| `AFormat` | `TDocScanFormat` | `dsfJPEG` for JPEG per page, `dsfPDF` for multi-page PDF |
| `AOnPageResult` | `TDocScanPageCallback` | Called per scanned page with file path, page index, and total pages. In PDF mode, JPEG callbacks fire first (for preview), then one PDF callback. |
| `AOnError` | `TDocScanErrorCallback` | Called on error or cancellation with message |
| `AMode` | `TDocScanMode` | Scanner mode (optional, default: `dsmFull`) |

### Types

```pascal
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

| Mode | Description |
|---|---|
| `dsmBase` | Basic scanning (edge detection, cropping) |
| `dsmBaseWithFilter` | Basic scanning + image filters |
| `dsmFull` | Full features: edge detection, cropping, rotation, filters (default) |

### 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

| Scenario | Behavior |
|---|---|
| Device without Google Play Services | `IsMLKitAvailable` returns `False` |
| User cancels scan | Error callback fires with `'Scan cancelled'`, `IsScanning` resets to `False` |
| PDF mode with 1 page | Produces a single-page PDF, JPEG preview callback fires first |
| Multiple concurrent scan calls | Blocked by `IsScanning` check, error callback fired |
| Non-Android platform | `StartScan` fires error callback: `'Document Scanner is only available on Android'` |

## 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:

```pascal
TmxDocScanner.ReleaseInstance;
```

## License

MIT License — see [LICENSE](LICENSE) for details.

delphi-docscanner

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README