@capacitor-mlkit/document-scanner

Unofficial Capacitor plugin for ML Kit Document Scanner.[^1]

Compatibility

| Plugin Version | Capacitor Version | Status |
| -------------- | ----------------- | -------------- |
| 8.x.x | >=8.x.x | Active support |

Installation

``bash
npm install @capacitor-mlkit/document-scanner
npx cap sync
`

$3

#### Variables

If needed, you can define the following project variable in your app’s variables.gradle file to change the default version of the dependency:

- $mlkitDocumentScannerVersion version of com.google.android.gms:play-services-mlkit-document-scanner (default: 16.0.0)

This can be useful if you encounter dependency conflicts with other plugins in your project.

Usage

`typescript
import { DocumentScanner } from '@capacitor-mlkit/document-scanner';

const scanDocument = async () => {
const result = await DocumentScanner.scanDocument({
galleryImportAllowed: true,
pageLimit: 5,
resultFormats: 'JPEG_PDF',
scannerMode: 'FULL',
});

console.log('Scanned images:', result.scannedImages);
console.log('PDF info:', result.pdf);
};

const isGoogleDocumentScannerModuleAvailable = async () => {
const result = await DocumentScanner.isGoogleDocumentScannerModuleAvailable();
console.log('Is Google Document Scanner module available:', result.available);
};

const installGoogleDocumentScannerModule = async () => {
await DocumentScanner.installGoogleDocumentScannerModule();
console.log('Google Document Scanner module installation started.');
};

DocumentScanner.addListener('googleDocumentScannerModuleInstallProgress', (event) => {
console.log('Installation progress:', event.progress, '%');
console.log('Current state:', event.state);
});
`

API

* scanDocument(...)
* isGoogleDocumentScannerModuleAvailable()
* installGoogleDocumentScannerModule()
* addListener('googleDocumentScannerModuleInstallProgress', ...)
* removeAllListeners()
* Interfaces
* Enums

$3

`typescript
scanDocument(options: ScanOptions) => Promise
`

Starts the document scanning process.

Only available on Android.

| Param | Type |
| ------------- | --------------------------------------------------- |
| options | ScanOptions |

Returns: Promise<ScanResult>

Since: 7.3.0

--------------------

$3

`typescript
isGoogleDocumentScannerModuleAvailable() => Promise
`

Check if the Google Document Scanner module is available.

If the Google Document Scanner module is not available, you can install it by using installGoogleDocumentScannerModule().

Only available on Android.

Returns: Promise<IsGoogleDocumentScannerModuleAvailableResult>

Since: 7.3.0

--------------------

$3

`typescript
installGoogleDocumentScannerModule() => Promise
`

Install the Google Document Scanner module.

Attention: This only starts the installation.
The googleDocumentScannerModuleInstallProgress event listener will
notify you when the installation is complete.

Only available on Android.

Since: 7.3.0

--------------------

$3

`typescript
addListener(eventName: 'googleDocumentScannerModuleInstallProgress', listenerFunc: (event: GoogleDocumentScannerModuleInstallProgressEvent) => void) => Promise
`

Called when the Google Document Scanner module is installed.

Only available on Android.

| Param | Type |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| eventName | 'googleDocumentScannerModuleInstallProgress' |
| listenerFunc | (event: GoogleDocumentScannerModuleInstallProgressEvent) => void |

Returns: Promise<PluginListenerHandle>

Since: 7.3.0

--------------------

$3

`typescript
removeAllListeners() => Promise
`

Remove all listeners for this plugin.

Only available on Android.

Since: 7.3.0

--------------------

$3


#### ScanResult

Result of a document scan operation.

| Prop | Type | Description | Since |
| ------------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ----- |
| scannedImages | string[] | An array of URIs for the scanned image pages (JPEG). Present if 'JPEG' or 'JPEG_PDF' was requested in resultFormats. | 7.3.0 |
| pdf | PdfInfo | Information about the generated PDF. Present if 'PDF' or 'JPEG_PDF' was requested in resultFormats. | 7.3.0 |


#### PdfInfo

| Prop | Type | Description | Since |
| --------------- | ------------------- | ---------------------------------- | ----- |
| uri | string | The URI of the generated PDF file. | 7.3.0 |
| pageCount | number | The number of pages in the PDF. | 7.3.0 |


#### ScanOptions

| Prop | Type | Description | Default | Since |
| -------------------------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | ----- |
| galleryImportAllowed | boolean | Whether to allow importing from the photo gallery. | false | 7.3.0 |
| pageLimit | number | The maximum number of pages that can be scanned. | 10 | 7.3.0 |
| resultFormats | 'JPEG' \| 'PDF' \| 'JPEG_PDF' | The desired result formats. Can be 'JPEG', 'PDF', or 'JPEG_PDF'. | 'JPEG_PDF' | 7.3.0 |
| scannerMode | 'FULL' \| 'BASE' \| 'BASE_WITH_FILTER' | The scanner mode. BASE: Basic editing capabilities (crop, rotate, reorder pages, etc.). BASE_WITH_FILTER: Adds image filters (grayscale, auto image enhancement, etc.) to the BASE mode. FULL: Adds ML-enabled image cleaning capabilities (erase stains, fingers, etc.) to the BASE_WITH_FILTER mode. This mode will also allow future major features to be automatically added along with Google Play services updates, while the other two modes will maintain their current feature sets and only receive minor refinements. | "FULL" | 7.3.0 |


#### IsGoogleDocumentScannerModuleAvailableResult

| Prop | Type | Description | Since |
| --------------- | -------------------- | --------------------------------------------------------------- | ----- |
| available | boolean | Whether or not the Google Document Scanner module is available. | 7.3.0 |


#### PluginListenerHandle

| Prop | Type |
| ------------ | ----------------------------------------- |
| remove | () => Promise<void> |


#### GoogleDocumentScannerModuleInstallProgressEvent

| Prop | Type | Description | Since |
| -------------- | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ----- |
| state | GoogleDocumentScannerModuleInstallState | The current state of the installation. | 7.3.0 |
| progress | number | The progress of the installation in percent between 0 and 100. | 7.3.0 |

$3


#### GoogleDocumentScannerModuleInstallState

| Members | Value | Since |
| --------------------- | -------------- | ----- |
| UNKNOWN | 0 | 7.3.0 |
| PENDING | 1 | 7.3.0 |
| DOWNLOADING | 2 | 7.3.0 |
| CANCELED | 3 | 7.3.0 |
| COMPLETED | 4 | 7.3.0 |
| FAILED | 5 | 7.3.0 |
| INSTALLING | 6 | 7.3.0 |
| DOWNLOAD_PAUSED | 7 | 7.3.0 |

Notes

- The ML Kit Document Scanner models, scanning logic, and UI flow are dynamically downloaded by Google Play services. Users might have to wait for these to download before the first use. You can use the isGoogleDocumentScannerModuleAvailable and installGoogleDocumentScannerModule methods to check for and install the module, and listen to the googleDocumentScannerModuleInstallProgress event for progress updates.
- This API requires Android API level 21 or above.
- It also requires a minimal device total RAM of 1.7GB. If lower, it returns an MlKitException with error code UNSUPPORTED when calling the API (this plugin will reject the promise).
- Consider that generating document files takes time and requires processing power, so only request the output formats (JPEG, or PDF, or both) you actually need via the resultFormats` option.

Terms & Privacy

This plugin uses the Google ML Kit:

- Terms & Privacy
- Android Data Disclosure
- iOS Data Disclosure

Changelog

See CHANGELOG.md.

License

See LICENSE.

[^1]: This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries.