@capacitor-mlkit/document-scanner¶

Unofficial Capacitor plugin for ML Kit Document Scanner.¹

Deliver Live Updates to your Capacitor app with Capawesome Cloud

Installation¶

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

Android¶

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-beta1)

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

Usage¶

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

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

    console.log('Scan successful:', result);

    if (result.scannedImages && result.scannedImages.length > 0) {
      console.log('First image URI:', result.scannedImages[0]);
      // Handle image URIs (e.g., display them)
    }

    if (result.pdf) {
      console.log('PDF URI:', result.pdf.uri);
      console.log('PDF Page Count:', result.pdf.pageCount);
      // Handle PDF URI (e.g., open or upload it)
    }
  } catch (error) {
    console.error('Scan failed:', error);
  }
}

API¶

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

scanDocument(...)¶

scanDocument(options: ScanOptions) => Promise<ScanResult>

Starts the document scanning process.

Only available on Android.

Param	Type	Description
`options`	`ScanOptions`	Configuration options for the scanner.

Returns: Promise<ScanResult>

Since: 7.2.1

isGoogleDocumentScannerModuleAvailable()¶

isGoogleDocumentScannerModuleAvailable() => Promise<IsGoogleDocumentScannerModuleAvailableResult>

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.2.1

installGoogleDocumentScannerModule()¶

installGoogleDocumentScannerModule() => Promise<void>

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.2.1

addListener('googleDocumentScannerModuleInstallProgress', ...)¶

addListener(eventName: 'googleDocumentScannerModuleInstallProgress', listenerFunc: (event: GoogleDocumentScannerModuleInstallProgressEvent) => void) => Promise<PluginListenerHandle>

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.2.1

removeAllListeners()¶

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Only available on Android.

Since: 7.2.1

Interfaces¶

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.2.1
`pdf`	`PdfInfo`	Information about the generated PDF. Present if 'PDF' or 'JPEG_PDF' was requested in resultFormats.	7.2.1

PdfInfo¶

Information about a generated PDF document.

Prop	Type	Description	Since
`uri`	`string`	The URI of the generated PDF file.	7.2.1
`pageCount`	`number`	The number of pages in the PDF.	7.2.1

ScanOptions¶

Options for the document scanner.

Prop	Type	Description	Default	Since
`galleryImportAllowed`	`boolean`	Whether to allow importing from the photo gallery.	`false`	7.2.1
`pageLimit`	`number`	The maximum number of pages that can be scanned.	`10`	7.2.1
`resultFormats`	`'JPEG' \| 'PDF' \| 'JPEG_PDF'`	The desired result formats. Can be 'JPEG', 'PDF', or 'JPEG_PDF'.	`'JPEG_PDF'`	7.2.1
`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.2.1

IsGoogleDocumentScannerModuleAvailableResult¶

Prop	Type	Description	Since
`available`	`boolean`	Whether or not the Google Document Scanner module is available.	7.2.1

PluginListenerHandle¶

Prop	Type
`remove`	`() => Promise<void>`

GoogleDocumentScannerModuleInstallProgressEvent¶

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

Enums¶

GoogleDocumentScannerModuleInstallState¶

Members	Value	Since
`UNKNOWN`	`0`	7.2.1
`PENDING`	`1`	7.2.1
`DOWNLOADING`	`2`	7.2.1
`CANCELED`	`3`	7.2.1
`COMPLETED`	`4`	7.2.1
`FAILED`	`5`	7.2.1
`INSTALLING`	`6`	7.2.1
`DOWNLOAD_PAUSED`	`7`	7.2.1

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:

Changelog¶

See CHANGELOG.md.

License¶

See LICENSE.

This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries. ↩