startDataCapture method

Opens a modal dialog with controls for the Data Capture scenario.

AbbyyRtrSdk.startDataCapture(callback, options)

Parameters

callback
The callback function which receives the data capture operation result. Your callback should expect a single JSON object as an argument (see Result).
options
JSON object specifying data capture parameters (see Options).

Options

The table below describes the 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.

Key Value type Description
profile string The predefined data capture profile to use, for example: "BusinessCards".
customDataCaptureScenario object

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.

 Note: For details, see the How to Capture a Custom Data Field guide in the ABBYY Mobile Capture SDK Developer's Guide.

 Note: Currently a custom data capture profile supports one recognized field only (fields must contain only 1 element).

See below for an example of a custom data capture scenario definition.
licenseFileName string

The name of the license file. This file must be located in the www/rtr_assets/ directory in your project.

Default: "AbbyyRtrSdk.license".
areaOfInterest 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.

Default: "0.8 0.3" (intended to capture a few lines of text in portrait mode).
orientation string

The type of image orientation. This key can be set to the following values:

  • "portrait"
  • "landscape"
  • "default" (the orientation will be detected automatically)

Default: "default".
stopWhenStable boolean

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.

Default: true (automatic stop enabled).
isFlashlightVisible boolean

Show (true) or hide (false) the flashlight button in the text capture dialog.

Default: true (flashlight available).
isStopButtonVisible boolean

Show (true) or hide (false) the stop button in the text capture dialog. When the user taps stop, Mobile Capture SDK returns the latest recognition result.

Default: true (manual stop available).
recognitionLanguages string

Recognition languages to use. If any of defined languages is not supported for current profile, an error will occur.

Default: ["English"].

An example of a custom data capture scenario definition in the options JSON.

{
  ...

  customDataCaptureScenario : {
    name : "Code",
    description : "Alphanumeric code, for example: X6YZ64 32VPA zyy777.",
    recognitionLanguages : ["English"],
    fields : [ {
      regEx : "([a-zA-Z]+[0-9]+|[0-9]+[a-zA-Z]+)[0-9a-zA-Z]*"
    } ]
  },

  ...

}

Result

This section describes the JSON object that represents data recognition results. The callback you implement should parse this object and show results to user.

Key Value type Description
dataScheme object

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.
dataFields object array

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 (object): quadrangle containing text, represented by an array of its four vertices' coordinates: { x: int, y: int }. The vertices are indexed 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 (object): quadrangle containing text, represented by an array of its four vertices' coordinates: { x: int, y: int }. The vertices are indexed clockwise starting from the bottom left.
  • rect (object): bounding rectangle for quadrangle. The rectangle is set by the following parameters:
      • top (int): upper left point ordinate
      • bottom (int): bottom left point ordinate
      • left (int): upper left point abscissa
      • right (int): upper right point abscissa

    #ERROR_snippet# The rect key exists in the iOS version only.

If an error occurs during processing, the dataFields key is not present in the result.
resultInfo object

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").
error object

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.

Below is an example of a result JSON when data capture succeeds.

{
  dataScheme : {
    id : "Hello",
    name : "Hello"
  },
  dataFields : [
    {
      id : "Hello",
      name : "Hello",
      text : "Hello world!",
      "quadrangle": [
        {
         "x": 82,
         "y": 567
       },
        {
         "x": 82,
         "y": 567
       },
        {
         "x": 82,
         "y": 567
       },
        {
         "x": 82,
         "y": 567
       }
      ],
      components : [ 
        {
          text : "Hello",
      "quadrangle": [
        {
         "x": 100,
         "y": 780
       },
        {
         "x": 100,
         "y": 600
       },
        {
         "x": 350,
         "y": 600
       },
        {
         "x": 350,
         "y": 780
       }
      ],
          "rect": {
  "top": 515,
       "bottom": 568,
       "left": 82,
       "right": 528
    },
        },
...
        }
      ]
    }
  ],
  resultInfo : {
    stabilityStatus : "Available",
    userAction : "Manually Stopped",
    frameSize : "720 1280"
  }
}

On error, you will receive a JSON which does not contain recognized data but provides an error message.

{
  error : {
    description : "Something unexpected have happened."
  }
  resultInfo : {
    stabilityStatus : "Tentative",
    userAction : "Canceled",
    frameSize : "720 1280"
  }
}

3/2/2022 12:59:15 PM

Usage of Cookies. In order to optimize the website functionality and improve your online experience ABBYY uses cookies. You agree to the usage of cookies when you continue using this site. Further details can be found in our Privacy Notice.