How to Capture a Custom Data Field with Android

This section contains a step-by-step guide to creating an application that captures a single custom data field.

How it Works

With Mobile Capture SDK you can create custom data capture profiles for documents that are not supported out-of-the-box. In the corresponding result schemes you define custom data fields. (Currently, only one scheme per profile is supported, and only one field may be defined in the scheme). To tell the recognition engine that some text string is a data value (a field value), you will have to specify a regular expression that should match the strings you are looking for. The value may be a date, some code with a known format, and so on: the more specific the data is, the easier it would be to capture it.

This guide uses an alphanumeric code as an example of data that can be captured. Code format is the following: it contains 15 characters that are either digits or capital letters, and the first two characters are always digits. Example: 69KL46D7WF2AR5U.

Implementation

 Note: Before you begin, see How to Add the Library to Your Android Studio Project.

To implement the custom data field capture scenario, follow these steps:

  1. Begin with the Callback interface implementation. Its methods will be used to pass the data to and from the recognition service. Here are the brief recommendations on what the methods should do:
  2. Call the Engine.load method on the UI thread to create an engine object via which all other objects may be created. This object should be reused for every new operation and should not be created again in the same activity.
  3. Use the createDataCaptureService method of the Engine object to create a background recognition service (implementing the IDataCaptureService interface). The profileName should be an empty string (or null): you are going to add your custom profile and then apply it to the service.
    Only one instance of the service per application is necessary: multiple threads will be started internally.
  4. Call the configureDataCaptureProfile method of the IDataCaptureService object to create an IDataCaptureProfileBuilder object. Then use its addScheme method to create an ISchemeBuilder object. The scheme builder allows you to set a human-readable name to the scheme (for example, it can be used for UI labels) and to add field definitions.
  5. Call ISchemeBuilder.addField to create an IFieldBuilder object. The field builder is used to configure field's properties — its human-readable name and recognition rules.
  6. Call IFieldBuilder.setRegEx to set the regular expression that should match the field text. The regEx parameter is "[0-9]{2}[0-9A-Z]{13}" — match 2 digits followed by 13 characters which are digits or capital letters.
     Note: For details on regular expression syntax supported in ABBYY Mobile Capture SDK, see the Regular Expressions section.
    Also you can implement any string predicate and use it for additional validation after the data has passed the regular expression check — for example, calculate the field's checksum. To do so, implement Predicate<T> for the String type and set it as the additional validation callback using setOnValidate. An alphanumeric code needs no additional checks, so this step is skipped here.
  7. After you have configured the field and scheme builders, call IDataCaptureProfileBuilder.checkAndApply to submit the profile for use in the data capture service. If an error is returned at this stage, it is probable the regular expression has mistakes in the syntax, please check it again.
     Note: The methods of builder objects return these objects, so in your code the steps above can be shortened as follows:

IDataCaptureService dataCaptureService = engine.createDataCaptureService( "", callback );
IDataCaptureProfileBuilder profileBuilder = dataCaptureService.configureDataCaptureProfile()
    .setRecognitionLanguage( "English" );

profileBuilder.addScheme( "sampleScheme" )
    .setName( "Sample Profile" )
    .addField( "sampleField" )
        .setName( "Some Alphanumeric Code" )
        .setRegEx( "[0-9]{2}[0-9A-Z]{13}" );

profileBuilder.checkAndApply();

  1. When the camera is ready, call the start method of the IDataCaptureService interface. Its required input parameters are the size and orientation of the video frame and the rectangular area of interest (e.g. if your application displays a highlighted rectangle in the center of the image, this rectangle should be specified as the "area of interest").
    The service will then start up several working threads and continue interacting with your application via the Callback interface.
  2. Whenever the Callback.onRequestLatestFrame method is called, provide the current video frame from the camera by calling IDataCaptureService.submitRequestedFrame.
  3. The Callback.onFrameProcessed method will be called on the UI thread to return the result. Its parameters are:
    • A DataScheme object; its Id property should return the same identifier that you have specified when adding the scheme (the id argument to addScheme).
    • An array of DataField objects, each representing one of the fields found and recognized. A DataField object provides the identifier and the human-readable name for the field, the field text, and its location.
    • The result stability status, which indicates if the result is available and if it is likely to be improved by adding further frames. Use it to determine whether the application should stop processing and display the result to the user. We do not recommend using the result until the stability level has reached at least Available and the data scheme has been matched.
  4. Save the results. Call the IDataCaptureService.stop method to terminate the processing threads and clean up image buffers.

See the description of classes and methods in the API Reference section.

02.03.2022 12:59:15

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.