Capture a Custom Data Field with Android

Documentation Menu

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

How it Works

With Real-Time Recognition SDK you can create custom data capture profiles for documents that are not supported out-of-the-box. In 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.


note Note: Before you begin, see Build your application with the OCR library for Android.

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.
  7. note Note: For details on regular expression syntax supported in ABBYY Real-Time Recognition 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.

  8. After you have configured the field and scheme builders, call IDataCaptureProfileBuilder.checkAndApplyto 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.
  9. note 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}" );
  10. 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 where to search for the text (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.
  11. Whenever the Callback.onRequestLatestFrame method is called, provide the current video frame from the camera by calling IDataCaptureService.submitRequestedFrame.
  12. 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).

    warning Important! If null is passed instead of a valid DataScheme object, the data scheme has not yet been matched, which may mean that there is no data of the required type in the area of interest. In this case, the results are not usable.

    • 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.
  13. 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 for Android OCR development in the API Reference section.