feat(abbyy-rtr): add ABBYY Real-Time Recognition plugin (#2580)

* feat(abbyy-rtr): add ABBYY Real-Time Recognition plugin

* refactor(abbyy-rtr) add CordovaCheck

src/@ionic-native/plugins/abbyy-rtr/index.ts

@@ -0,0 +1,336 @@
+import { Injectable } from '@angular/core';
+import { CordovaCheck, IonicNativePlugin, Plugin } from '@ionic-native/core';
+
+declare const AbbyyRtrSdk: any;
+
+/**
+ * JSON object that you can pass as the options argument to change text
+ * capture settings. All keys are optional. Omitting a key means that a
+ * default setting will be used.
+ */
+export interface TextCaptureOptions {
+
+ /**
+ * The name of the license file. This file must be located in the
+ * www/rtr_assets/ directory in your project.
+ */
+ licenseFileName?: string;
+
+ /**
+ * Recognition languages which can be selected by the user,
+ * for example: ["English", "French", "German"]. Empty array
+ * disables language selection.
+ */
+ selectableRecognitionLanguages?: Array<string>;
+
+ /**
+ * Recognition language selected by default.
+ */
+ recognitionLanguages?: Array<string>;
+
+ /**
+ * Width and height of the recognition area, separated by a
+ * whitespace — for example: "0.8 0.3". The area of interest is
+ * centered in the preview frame, its width and height are
+ * relative to the preview frame size and should be in the [0.0, 1.0] range.
+ */
+ areaOfInterest?: string;
+
+ /**
+ * Whether to stop the plugin as soon as the result status is
+ * "Stable" (see Result status). When enabled (true), the
+ * recognition process can be stopped automatically. When
+ * disabled (false), recognition can be stopped only manually
+ * by user.
+ */
+ stopWhenStable?: boolean;
+
+ /**
+ * Show (true) or hide (false) the flashlight button in the text
+ * capture dialog.
+ */
+ isFlashlightVisible?: boolean;
+
+ /**
+ * Show (true) or hide (false) the stop button in the text
+ * capture dialog. When the user taps stop, RTR SDK returns
+ * the latest recognition result.
+ */
+ isStopButtonVisible?: boolean;
+}
+
+/**
+ * JSON object that represents text recognition results.
+ * The callback you implement should parse this object and show results to user.
+ */
+export interface TextCaptureResult {
+
+ /**
+ * An array of objects representing recognized lines of text.
+ * These objects have the following keys:
+ * · text (string): the recognized text.
+ * · quadrangle (string): vertex coordinates of the bounding quadrangle,
+ * a string of 8 integers separated with whitespaces ("x1 y1 ... x4 y4"),
+ * goes clockwise starting from the bottom left.
+ * · rect (string): position and size of the bounding rectangle,
+ * a string of 4 integers separated with whitespaces ("x y width height").
+ */
+ textLines: Array<{ text: string, quadrangle: string, rect?: string }>;
+
+ /**
+ * Additional information. This object has the following keys:
+ * · stabilityStatus (string): result stability status.
+ * See Result status for details.
+ * · userAction (string): the user's action which stopped the plugin,
+ * if any. Can be "Manually Stopped" if the stop button has been used,
+ * and "Canceled" if the user canceled processing. If the plugin has
+ * stopped automatically, the userAction key is not present in resultInfo.
+ * · frameSize (string): full size of the preview frame, a string
+ * with 2 integers separated with a whitespace ("720 1280").
+ * · recognitionLanguages (string array): languages used for recognition,
+ * the array contains language identifiers (["English", "French", "German"]).
+ */
+ resultInfo: {
+ stabilityStatus: string,
+ userAction: string,
+ frameSize: string,
+ recognitionLanguages: Array<string>
+ };
+
+ /**
+ * Error details. This key is present only if an error occurs.
+ * The value is an object which has a single key:
+ * · description (string): human-readable error description.
+ */
+ error?: {
+ description: string;
+ };
+}
+
+/**
+ * JSON object that you can pass as the options argument to change data
+ * capture settings. All keys are optional. Omitting a key means that a default
+ * setting will be used, except the profile and customDataCaptureScenario
+ * keys: you must specify either one of them, but not both at the same time.
+ */
+export interface DataCaptureOptions {
+
+ /**
+ * The predefined data capture profile to use, for example: "MRZ".
+ * Note: For the list of supported documents, see Specifications — Data
+ * Capture Profiles in the ABBYY Real-Time Recognition SDK 1 Developer's Guide.
+ */
+ profile?: string;
+
+ /**
+ * Custom data capture settings. This object has the following keys:
+ * · name (string): the name of your custom data capture scenario, required.
+ * · description (string): a more detailed description. This key is optional;
+ * if not given, it will be assigned the same value as name.
+ * · recognitionLanguages (string array): recognition languages to use.
+ * Default is ["English"].
+ * · fields (object array): describes data fields to capture. Each object
+ * in this array has a single regEx key; its value is a string containing
+ * the regular expression that should be matched when capturing a field.
+ */
+ customDataCaptureScenario?: {
+ name: string,
+ description: string,
+ recognitionLanguages: Array<string>,
+ fields: Array<{ regEx: string }>
+ };
+
+ /**
+ * The name of the license file. This file must be located in the
+ * www/rtr_assets/ directory in your project.
+ */
+ licenseFileName?: string;
+
+ /**
+ * Width and height of the recognition area, separated by a
+ * whitespace — for example: "0.8 0.3". The area of interest is
+ * centered in the preview frame, its width and height are
+ * relative to the preview frame size and should be in the [0.0, 1.0] range.
+ */
+ areaOfInterest?: string;
+
+ /**
+ * Whether to stop the plugin as soon as the result status is
+ * "Stable" (see Result status). When enabled (true), the
+ * recognition process can be stopped automatically. When
+ * disabled (false), recognition can be stopped only manually
+ * by user.
+ */
+ stopWhenStable?: boolean;
+
+ /**
+ * Show (true) or hide (false) the flashlight button in the text
+ * capture dialog.
+ */
+ isFlashlightVisible?: boolean;
+
+ /**
+ * Show (true) or hide (false) the stop button in the text
+ * capture dialog. When the user taps stop, RTR SDK returns
+ * the latest recognition result.
+ */
+ isStopButtonVisible?: boolean;
+}
+
+/**
+ * JSON object that represents data recognition results. The callback you
+ * implement should parse this object and show results to user.
+ */
+export interface DataCaptureResult {
+
+ /**
+ * The data scheme which was applied during data capture.
+ * The value is an object which has two keys:
+ * · id (string): the internal scheme identifier.
+ * · name (string): the scheme name.
+ * If you had defined a custom data capture scenario in options, both the
+ * id and name will be the same as the scenario name you specified. If
+ * you selected a predefined profile, the id and name are specified by the
+ * profile. If an error occurs during processing, the dataScheme key is not
+ * present in the result.
+ */
+ dataScheme?: {
+ id: string,
+ name: string
+ };
+
+ /**
+ * Recognized data fields. Each object in the array represents a separate
+ * data field. The data field objects have the following keys:
+ * · id (string): the internal identifier of the field.
+ * · name (string): the field name.
+ * Similarly to dataScheme, in custom scenarios both id and name are the same
+ * as the scenario name you specified (currently custom scenarios allow
+ * only 1 recognized field).
+ * · text (string): full text of the field.
+ * · quadrangle (string): vertex coordinates of the bounding quadrangle, a
+ * string of 8 integers separated with whitespaces ("x1 y1 ... x4 y4"),
+ * goes clockwise starting from the bottom left.
+ * · components (object array): an array of objects representing field
+ * components, that is, the text fragments found on the image, which
+ * constitute the field.
+ * In the components array each element is an object with the following keys:
+ * · text (string): text of this fragment.
+ * · quadrangle (string): vertex coordinates of the bounding quadrangle of
+ * this fragment, similar to the field's quadrangle.
+ * · rect (string): position and size of the bounding rectangle, a string
+ * of 4 integers separated with whitespaces ("x y width height").
+ */
+ dataFields: {
+ id: string,
+ name: string,
+ text: string,
+ quadrangle: string,
+ components: {
+ text: string,
+ quadrangle: string,
+ rect: string
+ }
+ };
+
+ /**
+ * Additional information. This object has the following keys:
+ * · stabilityStatus (string): result stability status.
+ * See Result status for details.
+ * · userAction (string): the user's action which stopped the plugin,
+ * if any. Can be "Manually Stopped" if the stop button has been used,
+ * and "Canceled" if the user canceled processing. If the plugin has
+ * stopped automatically, the userAction key is not present in resultInfo.
+ * · frameSize (string): full size of the preview frame, a string
+ * with 2 integers separated with a whitespace ("720 1280").
+ */
+ resultInfo: {
+ stabilityStatus: string,
+ userAction: string,
+ frameSize: string
+ };
+
+ /**
+ * Error details. This key is present only if an error occurs.
+ * The value is an object which has a single key:
+ * · description (string): human-readable error description.
+ */
+ error?: {
+ description: string;
+ };
+}
+
+/**
+ * @name ABBYY Real-Time Recognition
+ * @description
+ * This plugin allows to use the Text Capture and Data Capture features of
+ * ABBYY Real-Time Recognition SDK (RTR SDK) in apps.
+ *
+ * @usage
+ * ```typescript
+ * import { AbbyyRTR } from '@ionic-native/abbyy-rtr';
+ *
+ *
+ * constructor(private abbyyRTR: AbbyyRTR) { }
+ *
+ * ...
+ *
+ *
+ * this.abbyyRTR.startTextCapture(options)
+ * .then((res: any) => console.log(res))
+ * .catch((error: any) => console.error(error));
+ *
+ *
+ * this.abbyyRTR.startDataCapture(options)
+ * .then((res: any) => console.log(res))
+ * .catch((error: any) => console.error(error));
+ *
+ * ```
+ */
+@Plugin({
+ pluginName: 'AbbyyRTR',
+ plugin: 'cordova-plugin-abbyy-rtr-sdk',
+ pluginRef: 'AbbyyRtrSdk',
+ repo: 'https://github.com/abbyysdk/RTR-SDK.Cordova',
+ install: 'ionic cordova plugin add cordova-plugin-abbyy-rtr-sdk',
+ platforms: ['Android', 'iOS']
+})
+@Injectable()
+export class AbbyyRTR extends IonicNativePlugin {
+
+ /**
+ * Opens a modal dialog with controls for the Text Capture scenario.
+ * @param {TextCaptureOptions} options
+ * @return {Promise<TextCaptureResult>}
+ */
+ @CordovaCheck()
+ startTextCapture(options: TextCaptureOptions): Promise<TextCaptureResult> {
+ return new Promise<any>((resolve, reject) => {
+ AbbyyRtrSdk.startTextCapture((result: DataCaptureResult) => {
+ if (result.error) {
+ reject(result);
+ } else {
+ resolve(result);
+ }
+ }, options);
+ });
+ }
+
+ /**
+ * Opens a modal dialog with controls for the Data Capture scenario.
+ * @param {DataCaptureOptions} options
+ * @return {Promise<DataCaptureResult>}
+ */
+ @CordovaCheck()
+ startDataCapture(options: DataCaptureOptions): Promise<DataCaptureResult> {
+ return new Promise<any>((resolve, reject) => {
+ AbbyyRtrSdk.startDataCapture((result: DataCaptureResult) => {
+ if (result.error) {
+ reject(result);
+ } else {
+ resolve(result);
+ }
+ }, options);
+ });
+ }
+}