@thegrizzlylabs/react-native-genius-scan

Genius Scan SDK for React Native

Description

This React Native component allows you to access the Genius Scan SDK core features from a React Native application. The component relies on the ScanFlow module which provides a all-in-one scanner module with simple configurable input.

• Automatic document detection
• Document perspective correction
• Image enhancement with 4 different modes (Black & white, Monochrome, Color, Photo)
• Batch scanning of several pages in row
• OCR to extract raw text from images and generate PDF with invisible text layer

License

This plugin is based on the Genius Scan SDK for which you need to setup a license. You can aleady try the "demo" version for free by not setting a license key, the only limitation being that the app will exit after 60 seconds.

To buy a license:

1. Sign up to our developer console
2. Submit a quote request for each application

You can learn more about licensing in our website and contact us at [e-mail] for further questions.

Demo application

As an example, you can check our demo application

Getting started

From your React Native root folder:

$ npm install @thegrizzlylabs/react-native-genius-scan --save

If you use ReactNative below 0.60, you will also need to link the plugin:

$ react-native link @thegrizzlylabs/react-native-genius-scan

Additional steps on Android

• Open the android/build.gradle file, change minSdkVersion to 21 and add the following repository:

allprojects {
	repositories {
	    ...
	    maven { url 'https://s3.amazonaws.com/tgl.maven' }
	}
}

Additional steps for iOS

• Add the required permission to your Info.plist

NSCameraUsageDescription - "We use the camera for <provide a good reason why you are using the camera>"

• In your Podfile, add the following line:

platform :ios, '13.0'

Run pod install from the ios folder

Usage

Set the license key

Initialize the SDK with a valid license key:

RNGeniusScan.setLicenseKey(licenseKey, /* autoRefresh = */ true)

setLicenseKey doesn't return anything. However, other methods of the plugin will fail if the license key is invalid or expired. Note that, for testing purpose, you can also use the plugin without setting a license key, but it will only work for 60 seconds.

It is recommended to show a message to users asking them to update the application in case the license has expired.

Start the scanner module

val result = await RNGeniusScan.scanWithConfiguration(configuration)

The method scanWithConfiguration takes a configuration parameter which can take the following options:

• source: camera, image or library (defaults to camera)
• sourceImageUrl: an absolute image url, required if source is image. Example: file:///var/…/image.png
• multiPage: boolean (defaults to true). If true, after a page is scanned, a prompt to scan another page will be displayed. If false, a single page will be scanned.
• multiPageFormat: pdf, tiff, none (defaults to pdf)
• defaultFilter: the filter that will be applied by default to enhance scans, or none if no enhancement should be performed by default. Possible values are listed in the Available filters section. Default value is automatic.
• availableFilters: an array of filters that the user can select when they tap on the edit filter button. Defaults to [none, automatic, automaticMonochrome, automaticBlackAndWhite, automaticColor, photo].
• pdfPageSize: fit, a4, letter, defaults to fit.
• pdfMaxScanDimension: max dimension in pixels when images are scaled before PDF generation, for example 2000 to fit both height and width within 2000px. Defaults to 0, which means no scaling is performed.
• pdfFontFileUrl: Custom font file used during the PDF generation to embed an invisible text layer. If null, a default font is used, which only supports Latin languages.
• jpegQuality: JPEG quality used to compress captured images. Between 0 and 100, 100 being the best quality. Default is 60.
• postProcessingActions: an array with the desired actions to display during the post processing screen (defaults to all actions). Possible actions are rotate, editFilter and correctDistortion.
• defaultCurvatureCorrection: enabled or disabled whether a curvature correction should be applied by default (Android only). Disabled by default.
• photoLibraryButtonHidden: boolean specifying whether the button allowing the user to pick an image on the Camera screen should be hidden (default to false).
• flashButtonHidden: boolean (default to false)
• defaultFlashMode: auto, on, off (default to off)
• foregroundColor: string representing a color, must start with a #. The color of the icons, text (defaults to '#ffffff').
• backgroundColor: string representing a color, must start with a #. The color of the toolbar, screen background (defaults to black)
• highlightColor: string representing a color, must start with a #. The color of the image overlays (default to blue)
• menuColor: string representing a color, must start with a #. The color of the menus (defaults to system defaults.)
• ocrConfiguration: text recognition options. Text recognition will run on a background thread for every captured image. No text recognition will be applied if this parameter is not present.
  • languages: list of the BCP 47 language codes (eg ["en-US"]) for which to run text recognition. Note that text recognition will take longer if multiple languages are specified.
  • outputFormats: an array with the formats in which the OCR result is made available in the ScanFlow result (defaults to all formats). Possible formats are rawText, hOCR and textLayerInPDF.
• structuredData: an array of the structured data you want to extract. E.g.: ['receipt', 'businessCard']. Possible values are bankDetails, receipt, businessCard. Only available on iOS.

It returns a promise with result object containing:

• multiPageDocumentUrl: a document containing all the scanned pages (example: "file://.pdf")
• scans: an array of scan objects. Each scan object has:
  • originalUrl: the original file as scanned from the camera. "file://.jpeg"
  • enhancedUrl: the cropped and enhanced file, as processed by the SDK. "file://.{jpeg|png}"
  • ocrResult: the result of text recognition for this scan
    • text: the raw text that was recognized
    • hocrTextLayout: the recognized text in hOCR format (with position, style…)
  • structuredData: the result of the structured data extraction. A subdictionary will be present for each type of structured data detected by the scan flow.

Available filters

The ScanFlow offers a variety of filters to enhance the appearance of different kinds of documents. Some filters are dynamic (or automatic), meaning they will apply the best enhancement possible, possibly with some constraints. For example, the automaticBlackAndWhite filter will apply the best enhancement, assuming that the scan is a text document and making sure the output will have a grayscale color palette. Here is a list of all possible dynamic filters: automatic, automaticColor, automaticBlackAndWhite, automaticMonochrome.

Other filters are static filters, which means they always perform the same enhancement operation, without any logic on the document characteristics. The different static filters are: photo, softBlackAndWhite, softColor, strongMonochrome, strongBlackAndWhite, strongColor, darkBackground.

(Optional) Generate a PDF document from multiple pages

If you'd like to rearrange the pages returned by the ScanFlow or add some more pages, you can do so and generate a PDF document from these pages:

await RNGeniusScan.generateDocument(document, configuration)

The document parameter is a map containing the following values:

• pages: an array of page objects. Each page object has:
  • imageUrl: the URL of the image file for this page, e.g. file://<filepath>.{jpeg|png}
  • hocrTextLayout: the text layout in hOCR format

The configuration parameter provides the following options:

• outputFileUrl: the URL where the document should be generated, e.g. file://<filepath>.pdf
• pdfFontFileUrl: Custom font file used during the PDF generation to embed an invisible text layer. If null, a default font is used, which only supports Latin languages.

Examples

Scanning a document from the camera

import RNGeniusScan from '@thegrizzlylabs/react-native-genius-scan';

RNGeniusScan.scanWithConfiguration({ source: 'camera'})
.then((result) => {
	// Do something with the result
})
.catch((error) => {
	// Handle error
})

Cropping and filtering an existing scan

import RNGeniusScan from '@thegrizzlylabs/react-native-genius-scan';

const imageUri = 'file://xxxxx' // imageUri from an existing file

RNGeniusScan.scanWithConfiguration({ source: 'image', sourceImageUrl: imageUri })
.then((result) => {
	// Do something with the enhanced image
})
.catch((error) => {
	// Handle error
})

FAQ

How do I get the UI translated to another language?

The device's locale determines the languages used by the plugin for all strings: user guidance, menus, dialogs…

The plugin supports a wide variety of languages: English (default), Arabic, Chinese (Simplified), Chinese (Traditional), Danish, Dutch, French, German, Hebrew, Indonesian, Italian, Japanese, Korean, Portuguese, Russian, Spanish, Swedish, Turkish, Vietnamese.

NB: iOS applications must be localized in XCode by adding each language to the project.

What should I do if my license is invalid?

Make sure that the license key is correct, that is has not expired, and that it is used with the App ID it was generated for. To learn more about the procurement and replacement of license keys, refer to the Licensing FAQ.

Troubleshooting

Refer to the troubleshooting guides of the native libraries to resolve common configuration and build problems:

• iOS
• Android

Changelog

See changelog