@thegrizzlylabs/cordova-plugin-genius-scan

Genius Scan SDK Cordova plugin

Description

This Cordova plugin allows you to access the Genius Scan SDK core features from a Cordova application:

• Automatic document detection
• Document perspective correction
• Image enhancement with 3 different modes (Black & white, Color, Photo)

Licence

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

To buy a licence or for any question regarding the SDK, please contact us at [e-mail]!

Demo application

As an example, you can check our demo application

Requirements

This plugin requires cordova-cli above 7.0.0: see this page for upgrading if you have an older version.

Platform-specific requirements

• iOS: cordova-ios above 4.3.0 Nothing to do on a new project; use cordova platform update ios --save within your existing cordova project to upgrade it.
• Android: cordova-android at least 6.x.x

Note for Xcode 10 users: Cordova-ios is not fully compatible with Xcode 10 yet, you may need to use cordova run ios --buildFlag="-UseModernBuildSystem=0" command to build the project properly

Upgrade from an older version

If you are using an older plugin version, you will first need to remove the plugin from your cordova project:

cordova plugin remove @thegrizzlylabs/cordova-plugin-genius-scan

Then you can install the new version following the instructions below.

Installation

You can install the plugin with Cordova CLI, plugman, or using the config.yml file.

Note for Phonegap, Ionic and other cordova-based tools:

You can usually run cordova commands from the phonegap/ionic cli.

• ionic cordova prepare
• ionic cordova plugin add ....
• phonegap cordova prepare (or, shorter phonegap prepare)
• ...

Android Support Library

This plugin requires the Android support libraries support-v4 and appcompat-v7. The version of the libraries used can be set at installation. The minimum version is 26.0.0 and the default version is 27.0.1.

With Cordova CLI

From your Cordova project folder, install the plugin with the following command:

cordova plugin add @thegrizzlylabs/cordova-plugin-genius-scan --variable ANDROID_SUPPORT_VERSION="27.0.1"

With config.yml

Add the following lines to your project's config.yml file:

<plugin name="@thegrizzlylabs/cordova-plugin-genius-scan" spec="~3.0.5">
  <variable name="ANDROID_SUPPORT_VERSION" value="27.0.1" />
</plugin>

And run cordova prepare.

With plugman

From your Cordova project folder, you can also use plugman to install the plugin only for a specific platform.

plugman install --platform ios --project ./platforms/ios --plugin @thegrizzlylabs/cordova-plugin-genius-scan

Usage

Once the deviceReady Cordova event has been fired, the following methods will be available:

Set the licence key

Initialize the SDK with a valid licence key:

cordova.plugins.GeniusScan.setLicenceKey(licenceKey, onSuccess, onFail)

setLicenseKey returns a promise that is resolved if the licence key is valid and rejected if it is not. Note that, for testing purpose, you can also use the plugin without a licence 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

cordova.plugins.GeniusScan.scanWithConfiguration(configuration, onSuccess, onFail)

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

• source: camera or image (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.
• defaultFilter: none, blackAndWhite, color, photo (by default, the filter is chosen automatically)
• 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.
• 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.
• 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 language codes (eg ["eng"]) for which to run text recognition. They should match the provided language files. Note that text recognition will take longer if multiple languages are specified.
  • languagesDirectoryUrl: folder containing the language files used for text recognition. Language files can be downloaded from https://github.com/tesseract-ocr/tessdata_fast.

It returns a promise with result object containing:

• pdfUrl: a PDF file of 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

Error callback

In case of failure, error callback function is called with an error message as a string

Usage with Ionic

You can use this plugin with any Cordova-based framework, for example Ionic. The way to detect that the device is ready is slightly different, but after that you also access the plugin with cordova.plugins.GeniusScan.scanWithConfiguration(configuration, onSuccess, onFail)

In the controller where you need the plugin, you will have to import Platform and pass it to the constructor, and also declare the cordova variable so that TypeScript recognizes it.

import { Platform } from 'ionic-angular';

declare var cordova:any;

export class HomePage {
  constructor(private platform: Platform) {
    platform.ready().then(() => {
      // platform.ready is the equivalent of the deviceReady event described above
      // the plugin method is now available:
      cordova.plugins.GeniusScan.scanWithConfiguration(...)
    });
  }

}

FAQ

How do I get the UI translated to another language?

The plugin supports a wide variety of languages:

• English (default)
• Arabic
• Danish
• German
• Spanish
• French
• Hebrew
• Indonesian
• Italian
• Japanese
• Korean
• Dutch
• Portuguese
• Russian
• Swedish
• Turkish
• Vietnamese
• Chinese (Simplified)
• Chinese (Traditional)

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

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. Contact us at [e-mail] for any information regarding the procurement and replacement of license keys.

Changelog

See changelog