SimulScan

The SimulScan Document Capture is a software solution that enables customers to extract and process various types of information from documents. A single document may contain barcodes, text, image data and forms, using SimulScan Document Capture this data can be extracted programmatically using OCR, barcode decoding and image capture. For example, a driver’s license can be thought of as a template containing regions such as name and address, signature and photo, each of these regions are processed and returned to RhoElements separately by SimulScan Document Capture so Optical Character Recognition captures the owners name and address whilst their photo is captured separately. These regions are defined by a template which maps the various regions of the document to the data they contain and can be created on-line at The SimulScan Document Capture template builder. This API is available only on Symbol Android devices with firmware supporting SimulScan Document Capture.

Enabling the API

In order to use this API you must include the following extension in your build.yml.

extensions: ["simulscan"]

JavaScript Usage

Be sure to review the JavaScript API Usage guide for important information about using this API in JavaScript.

Ruby Usage

Be sure to review the Ruby API Usage guide for important information about using this API in Ruby.

Methods

captureDocument(CallBackHandler callback)

Capture a document by either taking a photo of it and process that image for fields defined in the template. You must specify the template associated with the capture either through the template property or as part of the propertyMap when calling this method. If the document processing does not succeed the returned callback will contain failure description. If the captured document is processed successfully a callback will contain document data.

Parameters

  • callback : CallBackHandler Mandatory

Async Callback Returning Parameters: HASH

    • callbackType : STRING

      Indicates whether the document was decoded successfully or not.

      Possible Values :

      Constant: Rho.SimulScan.SUCCESS (For Ruby use "::" for all "." when referencing constants)
      String:success

      The document was decoded and processed successfully and this callback contains information about the processed form. Look at processedForm parameter.

      Constant: Rho.SimulScan.FAILURE (For Ruby use "::" for all "." when referencing constants)
      String:failure

      An error has occurred whilst processing the document. Look at failureReason parameter.

      Constant: Rho.SimulScan.STOP (For Ruby use "::" for all "." when referencing constants)
      String:stop

      The processing is over. No more notifications until next captureDocument.

    • failureReason : STRING

      Describes reason for failure.

      Possible Values :

      Constant: Rho.SimulScan.FAILURE_ERROR (For Ruby use "::" for all "." when referencing constants)
      String:error

      SimulScan Document Capture engine generic error.

      Constant: Rho.SimulScan.FAILURE_IDENTIFICATION_TIMEOUT (For Ruby use "::" for all "." when referencing constants)
      String:identificationTimeout

      Identification timeout. Refer to identificationTimeout property.

      Constant: Rho.SimulScan.FAILURE_PROCESSING_TIMEOUT (For Ruby use "::" for all "." when referencing constants)
      String:processingTimeout

      Processing timeout. Refer to processingTimeout property.

    • processedForm : HASH

      • template : HASH

        • name : STRING

          The name of the template was used for recognition.

        • number : INTEGER

          The number of the template was used for recognition.

      • formCapture : HASH

        • name : STRING

          The name of the template was used for recognition.

        • image : HASH

          The image of whole scanned form.

          • width : INTEGER

            Width of scanned form in pixels.

          • height : INTEGER

            Height of scanned form in pixels.

          • id : INTEGER

            Id of scanned form image. Use getDataUri method to retrieve image data. The id is valid until close method is called.

      • regions : ARRAY

        • group : STRING

          The name of the group this region is found in, as defined in the template associated with the recognized region. It’s optional parameter.

        • name : STRING

          The name of the region, as defined in the template associated with the document.

        • number : INTEGER

          The number of the region, as defined in the template section associated with the recognized region.

        • processingMode : STRING

          The type of region which has been decoded.

          Possible Values :

          Constant: Rho.SimulScan.PM_OCR (For Ruby use "::" for all "." when referencing constants)
          String: ocr

          Optical Character Recognition. The region is a text field. The processedData parameter contains array of lines.

          Constant: Rho.SimulScan.PM_OMR (For Ruby use "::" for all "." when referencing constants)
          String: omr

          Optical Mark Recognition. The region is a check box or radio box. The processedData parameter of this callback will contain a boolean value.

          Constant: Rho.SimulScan.PM_PICTURE (For Ruby use "::" for all "." when referencing constants)
          String: picture

          The defined region was captured as a picture. No processedData parameter. Use the image callback property with the getDataUri() to get a DataURI of the image.

          Constant: Rho.SimulScan.PM_BARCODE (For Ruby use "::" for all "." when referencing constants)
          String: barcode

          The region is a barcode and the decoded barcode data is given in the processedData parameter.

        • processedData : STRING

          The processed data contained in the specified region, this will depend on the type of region being captured. See the values of the processingMode parameter.

        • image : STRING

          The image of region.

          • width : INTEGER

            Width of region in pixels.

          • height : INTEGER

            Height of region in pixels.

          • id : INTEGER

            Id of region image. Use getDataUri method to retrieve image data. Id is valid until the close method is called.

        • relativeOcrConfidence : INTEGER

          Relative OCR confidence for processed data if applicable.

        • absoluteOcrConfidence : INTEGER

          Absolute OCR confidence for processed data if applicable.

Synchronous Return:

  • Void : this method also supports async callbacks - check the Callback tab for callback return parameters.

Method Access:

  • Instance Method: This method can be accessed via an instance object of this class:
    • myObject.captureDocument(CallBackHandler callback)
  • Default Instance: This method can be accessed via the default instance object of this class.
    • JavaScript: Rho.SimulScan.captureDocument(CallBackHandler callback)
    • Ruby: Rho::SimulScan.captureDocument(CallBackHandler callback)

Destructor close()

Close SimulScan Document Capture engine, and release allocated resources. When capturing images, this is especially important since they are made available temporarily.

Synchronous Return:

  • Void

Method Access:

  • Class Method: This method is a destructor and can only be accessed via the object that was created by the `new` constructor.
    • JavaScript: myObj.close()
    • Ruby: @myObj.close()

fetchTemplates(STRING userName, STRING password)

Fetch templates from dedicated SimulScan Document Capture server and place into template directory. See templateDirectory property. The device must have access to the network and can access the SimulScan Document Capture Template Builder Website

Parameters

  • userName : STRING

    Username of the user.

  • password : STRING

    Password of the user.

Synchronous Return:

  • Void

Method Access:

  • Instance Method: This method can be accessed via an instance object of this class:
    • myObject.fetchTemplates(STRING userName, STRING password)
  • Default Instance: This method can be accessed via the default instance object of this class.
    • JavaScript: Rho.SimulScan.fetchTemplates(STRING userName, STRING password)
    • Ruby: Rho::SimulScan.fetchTemplates(STRING userName, STRING password)

getAllProperties(CallBackHandler callback)

This method will return all of object/value pairs for the propertyNames of the API class.

Parameters

  • callback : CallBackHandler Optional

Async Callback Returning Parameters: HASH

    • : STRING

Synchronous Return:

  • HASH :

    Map of all available properties

    : this method also supports async callbacks - check the Callback tab for callback return parameters.
    • : STRING

Method Access:

  • Instance Method: This method can be accessed via an instance object of this class:
    • myObject.getAllProperties(CallBackHandler callback)
  • Default Instance: This method can be accessed via the default instance object of this class.
    • JavaScript: Rho.SimulScan.getAllProperties(CallBackHandler callback)
    • Ruby: Rho::SimulScan.getAllProperties(CallBackHandler callback)

getDataUri(INTEGER imageId)

Return data URI encoding of the raw image associated with the region or captured form, this allows the operator to easily verify that the captured data is accurate and if necessary perform any post processing changes by hand. To show the image on the HTML page insert the data URI string into the src attribute of the img tag:

        <img src="dataURI string;">

Parameters

  • imageId : INTEGER

    Id of image to retrieve. Ids are valid until close method call.

Synchronous Return:

  • Void

Method Access:

  • Instance Method: This method can be accessed via an instance object of this class:
    • myObject.getDataUri(INTEGER imageId)
  • Default Instance: This method can be accessed via the default instance object of this class.
    • JavaScript: Rho.SimulScan.getDataUri(INTEGER imageId)
    • Ruby: Rho::SimulScan.getDataUri(INTEGER imageId)

getDefault()

This method will return an object that represents the default instance of the API Class. For example Camera.getDefault will return a Camera object that represents the default camera.

Synchronous Return:

  • SELF_INSTANCE :

    Default object of Module.

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.SimulScan.getDefault()
    • Ruby: Rho::SimulScan.getDefault()

getProperties(ARRAY arrayofNames, CallBackHandler callback)

This method will return a set of object/value pairs for the list of the propertyName that is passed in. The propertyNames must be a valid property of the API class.

Parameters

  • arrayofNames : ARRAY

    List of properties I want to know about

    • Object : STRING

  • callback : CallBackHandler Optional

Async Callback Returning Parameters: HASH

    • : STRING

Synchronous Return:

  • HASH :

    Map of properties I want to know about

    : this method also supports async callbacks - check the Callback tab for callback return parameters.
    • : STRING

Method Access:

  • Instance Method: This method can be accessed via an instance object of this class:
    • myObject.getProperties(ARRAY arrayofNames, CallBackHandler callback)
  • Default Instance: This method can be accessed via the default instance object of this class.
    • JavaScript: Rho.SimulScan.getProperties(ARRAY arrayofNames, CallBackHandler callback)
    • Ruby: Rho::SimulScan.getProperties(ARRAY arrayofNames, CallBackHandler callback)

getProperty(STRING propertyName, CallBackHandler callback)

This method will return the value of the propertyName that is passed in. The propertyName must be a valid property of the API class.

Parameters

  • propertyName : STRING

    The property to return info about.

  • callback : CallBackHandler Optional

Async Callback Returning Parameters: STRING

    Synchronous Return:

    • STRING :

      The property to return info about.

      : this method also supports async callbacks - check the Callback tab for callback return parameters.

    Method Access:

    • Instance Method: This method can be accessed via an instance object of this class:
      • myObject.getProperty(STRING propertyName, CallBackHandler callback)
    • Default Instance: This method can be accessed via the default instance object of this class.
      • JavaScript: Rho.SimulScan.getProperty(STRING propertyName, CallBackHandler callback)
      • Ruby: Rho::SimulScan.getProperty(STRING propertyName, CallBackHandler callback)

    setDefault(SELF_INSTANCE: Rho::SimulScan defaultInstance)

    This method allows you to set the attributes of the default object instance by passing in an object of the same class.

    Parameters

    • defaultInstance : SELF_INSTANCE: Rho::SimulScan

      An instance object that is of the same class.

    Synchronous Return:

    • Void

    Method Access:

    • Class Method: This method can only be accessed via the API class object.
      • JavaScript: Rho.SimulScan.setDefault(SELF_INSTANCE: Rho::SimulScan defaultInstance)
      • Ruby: Rho::SimulScan.setDefault(SELF_INSTANCE: Rho::SimulScan defaultInstance)

    setProperties(HASH propertyMap)

    This method will set the values of a list of properties for the API class. The propertyName must be a valid property for the class and must also not be read only.

    Parameters

    • propertyMap : HASH

      Map of properties I want to set

      • Object : STRING

    Synchronous Return:

    • Void

    Method Access:

    • Instance Method: This method can be accessed via an instance object of this class:
      • myObject.setProperties(HASH propertyMap)
    • Default Instance: This method can be accessed via the default instance object of this class.
      • JavaScript: Rho.SimulScan.setProperties(HASH propertyMap)
      • Ruby: Rho::SimulScan.setProperties(HASH propertyMap)

    setProperty(STRING propertyName, STRING propertyValue)

    This method will set the value of a property for the API class. The propertyName must be a valid property for the class and must also not be read only.

    Parameters

    • propertyName : STRING

      The one property name that I want to set

    • propertyValue : STRING

      The one property value that I want to set

    Synchronous Return:

    • Void

    Method Access:

    • Instance Method: This method can be accessed via an instance object of this class:
      • myObject.setProperty(STRING propertyName, STRING propertyValue)
    • Default Instance: This method can be accessed via the default instance object of this class.
      • JavaScript: Rho.SimulScan.setProperty(STRING propertyName, STRING propertyValue)
      • Ruby: Rho::SimulScan.setProperty(STRING propertyName, STRING propertyValue)

    Properties

    audioFeedback : BOOLEAN

    Whether or not to provide audio feedback to the user following document processing.

    Default: true

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.audioFeedback
    • Default Instance: This property can be accessed via the default instance object of this class.
      • JavaScript: Rho.SimulScan.audioFeedback
      • Ruby: Rho::SimulScan.audioFeedback

    autoImageCapture : BOOLEAN

    If true, form will be captured automatically when detected. If false, user must manually tap screen or press trigger to capture the form.

    Default: true

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.autoImageCapture
    • Default Instance: This property can be accessed via the default instance object of this class.
      • JavaScript: Rho.SimulScan.autoImageCapture
      • Ruby: Rho::SimulScan.autoImageCapture

    debug : BOOLEAN

    If enabled, allows a session to write form capture, region images, region values, and other data to storage.

    Default: false

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.debug
    • Default Instance: This property can be accessed via the default instance object of this class.
      • JavaScript: Rho.SimulScan.debug
      • Ruby: Rho::SimulScan.debug

    decodeAudioFeedback : STRING

    Specifies the decode sound (beep) that is heard when a form is decoded.

    Default: system/media/audio/notifications/decode.wav

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.decodeAudioFeedback
    • Default Instance: This property can be accessed via the default instance object of this class.
      • JavaScript: Rho.SimulScan.decodeAudioFeedback
      • Ruby: Rho::SimulScan.decodeAudioFeedback

    delayResultDisplay : BOOLEAN

    If true, the success event will be sent only after the SimulScan Document Capture dialog is dismissed. If false, the event will be sent immediately after the results are ready. A false value is recommended unless direct interaction with the underlying application is necessary (e.g. keystroke input).

    Default: false

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.delayResultDisplay
    • Default Instance: This property can be accessed via the default instance object of this class.
      • JavaScript: Rho.SimulScan.delayResultDisplay
      • Ruby: Rho::SimulScan.delayResultDisplay

    flashMode : STRING

    Flash mode (off, on, disabled).

    Default: off

    Possible Values (STRING):

    Constant: Rho.SimulScan.FLASH_OFF (For Ruby use "::" for all "." when referencing constants)
    String: off

    Turn flash off.

    Constant: Rho.SimulScan.FLASH_ON (For Ruby use "::" for all "." when referencing constants)
    String: on

    Turn flash on.

    Constant: Rho.SimulScan.FLASH_DISABLED (For Ruby use "::" for all "." when referencing constants)
    String: disabled

    Disable flash.

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.flashMode
    • Default Instance: This property can be accessed via the default instance object of this class.
      • JavaScript: Rho.SimulScan.flashMode
      • Ruby: Rho::SimulScan.flashMode

    frameThreshold : INTEGER

    Only used if autoImageCapture is enabled. The number of correct frames that is needed to pass before SimulScan Document Capture will automatically start to process form. This should be between 5 and 30.

    Default: 15

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.frameThreshold
    • Default Instance: This property can be accessed via the default instance object of this class.
      • JavaScript: Rho.SimulScan.frameThreshold
      • Ruby: Rho::SimulScan.frameThreshold

    hapticFeedback : BOOLEAN

    Whether or not to provide haptic feedback to the user following document processing.

    Default: true

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.hapticFeedback
    • Default Instance: This property can be accessed via the default instance object of this class.
      • JavaScript: Rho.SimulScan.hapticFeedback
      • Ruby: Rho::SimulScan.hapticFeedback

    identificationTimeout : INTEGER

    The length of time, in milliseconds that the processing engine has to recognize the image from the provided template. From 0 to 20000 in increments of 100.

    Default: 15000

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.identificationTimeout
    • Default Instance: This property can be accessed via the default instance object of this class.
      • JavaScript: Rho.SimulScan.identificationTimeout
      • Ruby: Rho::SimulScan.identificationTimeout

    inputSource : STRING

    Defines where the document should be captured from. The only supported source is camera.

    Default: camera

    Possible Values (STRING):

    Constant: Rho.SimulScan.SOURCE_CAMERA (For Ruby use "::" for all "." when referencing constants)
    String: camera

    The document will be captured from the device camera. After calling the captureDocument method the camera preview will be presented, the user should place the document to be captured in the preview frame and press the soft button to capture & process the image.

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.inputSource
    • Default Instance: This property can be accessed via the default instance object of this class.
      • JavaScript: Rho.SimulScan.inputSource
      • Ruby: Rho::SimulScan.inputSource

    ledFeedback : BOOLEAN

    Whether or not to provide LED feedback to the user following document processing.

    Default: true

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.ledFeedback
    • Default Instance: This property can be accessed via the default instance object of this class.
      • JavaScript: Rho.SimulScan.ledFeedback
      • Ruby: Rho::SimulScan.ledFeedback

    logDirectory : STRING

    Specify which directory to search for logs in.

    Default: /sdcard/SimulScanLog

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.logDirectory
    • Default Instance: This property can be accessed via the default instance object of this class.
      • JavaScript: Rho.SimulScan.logDirectory
      • Ruby: Rho::SimulScan.logDirectory

    negativeFrameThreshold : INTEGER

    Only used if autoImageCapture is enabled. Number of incorrect frames that is allowed to pass before the frame counter is reset for automatic image capture. This should be between 0 and 20.

    Default: 2

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.negativeFrameThreshold
    • Default Instance: This property can be accessed via the default instance object of this class.
      • JavaScript: Rho.SimulScan.negativeFrameThreshold
      • Ruby: Rho::SimulScan.negativeFrameThreshold

    processingTimeout : INTEGER

    Amount of time in milliseconds to wait before timing out processing.

    Default: 10000

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.processingTimeout
    • Default Instance: This property can be accessed via the default instance object of this class.
      • JavaScript: Rho.SimulScan.processingTimeout
      • Ruby: Rho::SimulScan.processingTimeout

    template : STRING

    The template XML which defines the document to be processed. This should be file URI to the template on the device. You must provide this property to define the form being captured and what is contained in each region on that form. Templates are specific to each document format you intend on capturing and can be created on-line at https://dpx-uat.motorolasolutions.com/.

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.template
    • Default Instance: This property can be accessed via the default instance object of this class.
      • JavaScript: Rho.SimulScan.template
      • Ruby: Rho::SimulScan.template

    templateDirectory : STRING

    Specify where to store downloaded templates. See fetchTemplates()

    Default: /sdcard/templates

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.templateDirectory
    • Default Instance: This property can be accessed via the default instance object of this class.
      • JavaScript: Rho.SimulScan.templateDirectory
      • Ruby: Rho::SimulScan.templateDirectory

    uiResultConfirmation : BOOLEAN

    If enabled, shows a UI confirmation with results in SimulScan Document Capture View before sending results back to application.

    Default: true

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.uiResultConfirmation
    • Default Instance: This property can be accessed via the default instance object of this class.
      • JavaScript: Rho.SimulScan.uiResultConfirmation
      • Ruby: Rho::SimulScan.uiResultConfirmation

    version : STRING Read Only

    Version of SimulScan Document Capture engine.

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.version
    • Default Instance: This property can be accessed via the default instance object of this class.
      • JavaScript: Rho.SimulScan.version
      • Ruby: Rho::SimulScan.version

    Examples

    Download Templates

    Before you are able to process any documents with the SimulScan Document Capture engine, you must have template files loaded on the device. These template files must be located in an area that is open to both the SimulScan Document Capture Engine as well as your application. To retrieve the templates from the server, you would use the fetchTemplates method. This method will communicate with the SimulScan Document Capture back-end and download the templates to the folder that is specified by the templateDirectory property

    function downloadSimulScanTemplates(user,password){
        // If you include your SimulScan Document Capture template files in the applications public folder
        // the SimulScan Document Capture engine will not be able to access them due to Android
        // security policies
    
        Rho.SimulScan.templateDirectory = 'file:///sdcard/Templates';
        Rho.SimulScan.fetchTemplates(user,password);
        templates = Rho.RhoFile.listDir(Rho.SimulScan.templateDirectory);
        for (var i = 0; i < templates.length; ++i) {
            console.log(templates[i]);
        }
    }
                         
    Capture Document

    The only requirement for capturing a document is to have the SimulScan Document Capture template file location set using the SimulScan.template property. This must be an absolute URI to the locale file. The location must also be in a folder that is openly available to both your application and the SimulScan Document Capture engine (i.e. it cannot be in the applications public folder)

    // POSTAL.XML was exported from the SimulScan Document Capture Template Builder
    // In the Template Builder there were several fields defined
    
    Rho.SimulScan.template = 'file:///sdcard/Templates/POSTAL.XML';
    
    // Once the captureDocument method is launched,
    // the SimulScan Document Capture Engine dialog appears instructing the
    // user to hold the device steady over the printed label
    // The callback function will be triggered possibly for
    // many reasons
    
    Rho.SimulScan.captureDocument(function(params){
        if(params.callbackType == Rho.SimulScan.SUCCESS ){
            // process the returned object:
            var returnedField = params.processedForm;
            processSimulScanForm(returnedField);
        }
    
        if(params.callbackType == Rho.SimulScan.FAILURE ){
            if(params.failureReason == Rho.SimulScan.FAILURE_IDENTIFICATION_TIMEOUT){
                // This means it could not identify the label based on the template used
                // Possible reasons
                //    -label is the wrong label
                //    -Template is poorly defined
                //      maybe scanned in image for defining was not high enough resolution
                //    -camera cannot focus
    
                // This may trigger multiple times and may not warrant display information
                // in your app - the SimulScan Document Capture engine will prompt the user in most cases
            }
            if(params.failureReason == Rho.SimulScan.FAILURE_PROCESSING_TIMEOUT){
                // This means it identified the form but could not process it
                // Possible reasons
                //    -Template is poorly defined
                //      maybe scanned in image for defining was not high enough resolution
                //    -Camera cannot focus or poorly lit
    
                // This will trigger once and return focus to your application
            }
        }
    });
                        

    Now we can loop through the processedForm object returned by the captureDocument method. Depending on how the template was defined will determine the type of information in this object. Typically the template will contain several regions that may be OCR (Text), OMR (Check-boxes), Barcode, Picture. It will only return regions that it was able to be processed.

    function processSimulScanForm(SimulScanForm){
        var regions = SimulScanForm.regions;
        for(i=0; i< regions.length; ++i){
            switch(regions[i].processingMode){
            case Rho.SimulScan.PM_OCR:
                // The text that OCR translated into an array of lines
                regionTextArray = regions[i].processedData;
    
                //maybe do something with returned confidence
                // PDXform.absoluteOcrConfidence
                // PDXform.relativeOcrConfidence
                break;
            case Rho.SimulScan.PM_OMR:
                // Checkbox region either True or False
                regionBooleanCheckbox = regions[i].processedData;
                break;
            case Rho.SimulScan.PM_PICTURE:
                // nothing in processedData
                // Image held temporarily until Rho.SimulScan.close()
                // use the id and the Rho.SimulScan.getDataUri method
                regionImageURI = Rho.SimulScan.getDataUri(regions[i].image.id);
                break;
            case Rho.SimulScan.PM_BARCODE:
                // Barcode data will be in processedData field
                regionBarCode = regions[i].processedData;
                break;
            }
        }
    }