startImageCapture method of AbbyyRtrSdk module

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

AbbyyRtrSdk.startImageCapture(callback, options)

Parameters

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

Options

The table below describes the JSON object that you can pass as the options argument to change image capture settings. All keys are optional. Omitting a key means that a default setting will be used.

Key Value type Description
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".
cameraResolution string

The resolution of the images captured from the camera preview. This key can be set to the following values:

  • "HD"
  • "FullHD"
  • "4K" (for iOS only)

Default: "FullHD".
isFlashlightButtonVisible boolean

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

Default: true (flashlight visible).
isCaptureButtonVisible boolean

Show (true) or hide (false) the button for taking photo manually.

Default: false (button is hidden).
isGalleryButtonVisible boolean

Show (true) or hide (false) the button for choosing an image from photo gallery.

Default: true (flashlight visible).
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".
destination string

Captured image will be saved to corresponding file ("file") or returned as encode base64 image string ("base64").

 Note: If more than 1 image is captured, this option value will be ignored and the images will be saved to files anyway.

Default: "file".
exportType string

Captured image will be saved to this format. This key can be set to the following values:

  • "jpg"
  • "png"
  • "pdf" (all images will be saved to one pdf file)

Default: "jpg".
showPreview boolean

Show image preview after capture (true) or wait until the number of captured images is equal to the requiredPageCount (false).

Default: false.
requiredPageCount int

Total number of pages to be captured.

Set the page-limitation mode of the image capture as following:

  • 0 to allow unlimited image capture. The set of the result images can be saved or edited at any time;
  • a positive value to set the exact number of images that should be captured. Images saving is enabled only when this number of images are been captured.

Default: 0.
compressionLevel string

The uniform image compression scale for lossy formats. This key can be set to the following values:

  • "Low"
  • "Normal"
  • "High"
  • "ExtraHigh"

Default: "Low".
defaultImageSettings object

Custom image capture settings. This object has the following keys:

  • aspectRatioMin (float): Lower limit of the document's aspect ratio.
    This property is used in pair with the aspectRatioMax, defining an interval of acceptable aspect ratio values of the document to be captured. Setting aspect ratio will help to improve boundary detection accuracy.
    If only aspectRatioMax is set, aspectRatioMin will be set to 1. Default: 0 (aspect ratio is not set).
  • aspectRatioMax (float): Upper limit of document's aspect ratio.
    This property is used in pair with the aspectRatioMin, defining an interval of acceptable aspect ratio values of the document to be captured. Setting aspect ratio will help to improve boundary detection accuracy.
    If only aspectRatioMin is set, aspectRatioMax will be set to infinity. Default: 0 (aspect ratio is not set).
  • imageFromGalleryMaxSize (int): Maximum available size of an image, loaded from the gallery. The size is defined as the length of the largest side of an image (in pixels). Default: 4096.minimumDocumentToViewRatio (float): the minimum document area relative to the whole frame area, required for capture. If the document area is less than this ratio, the image will not be captured. The value can be from 0 to 1. Default: 0.15.
  • documentSize (string): expected size of the original document in millimeters. This key can be set to the following constant values:
    • "A4"
    • "BusinessCard"
    • "Letter"
    • "Any"

  or defined as a string with 2 integers separated with a whitespace: "54 86".

All keys are optional.

Result

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

Key Value type Description
images object array

Captured images. This parameter is returned only if the exportType is set to "jpg" or "png".
Each object in the array represents a single image with corresponding information. The image objects have the following parameters:

  • resultInfo (object): this object has the following parameters:
    • exportType (string): the format of the captured image.
    • imageSize (object): full size of the preview frame, an object with int parameters width and height.
  • filePath (string): full path to the exported file. This parameter is present if the destination is 'file'.
  • base64 (string): the original image returned as base64 image string. This parameter is present if the destination parameter was set to "base64".
pdfInfo object

This parameter is returned if the exportType is set to "pdf". The value is an object which has the following parameters:

  • filePath (string): full path to the exported PDF file.
  • pagesCount (integer): number of pages in the exported PDF file. Normally fits the number of captured images.
resultInfo object

Additional information. This object has the following parameters:

  • userAction (string): the user's action which stopped the module, if any. Can be "Canceled" if the user canceled processing. If the module has stopped automatically, the userAction parameter is not present in resultInfo.
  • uriPrefix (string): add this string to the beginning of the filePath or base64 parameter to get a URI. This parameter can be 'file://'  if the destination is 'File' and 'data:image/jpeg;base64,' or 'data:image/png;base64,' if the destination is 'Base64'.  
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 image capture succeeds.

{  
   "images":[  
      {  
         "resultInfo":{  
            "exportType":"jpg"
         },
         "filePath":"/private/var/mobile/Containers/Data/Application/ХХХХХХХХ-ХХХХ-ХХХХ-ХХХХ-ХХХХХХХХХХХХ/tmp/1562917370501.jpg"
      }
   ],
   "resultInfo":{  
      "userAction":"Manually Stopped"
   },
   "pdfInfo":{  
      "compressionLevel":"Normal",
      "pdfCompressionType":"jpg",
      "pagesCount":1,
      "filePath":"/private/var/mobile/Containers/Data/Application/ХХХХХХХХ-ХХХХ-ХХХХ-ХХХХ-ХХХХХХХХХХХХ/tmp/ImageCapture - 2019-07-12 10_42_57.pdf"
   }
}

On error, you will receive a JSON which does not contain image capture result but provides an error message.

{
   "error":
   {
      "description":"Unacceptable license information is used or the functionality is not available under the license."
   }
}

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.