Developer's Documentation for free mobile OCR SDK

Documentation Menu

Capture a Custom Data Field: Android

This section contains a step-by-step guide to creating an application that captures a single field which conforms to a certain regular expression. This could be a date, some code, etc. The more specific the data is, the easier it would be to capture it. In this guide we will capture an alphanumeric code, for example: X6Yz647a.

See also Build your application with the OCR library for Android.

  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's text. In this example the field contains an alphanumeric code, so the regEx parameter would be "([a-zA-Z]+[0-9]+|[0-9]+[a-zA-Z]+)[0-9a-zA-Z]*"

    noteNote: The regular expression syntax is derived from ICU regular expressions, with some minor features not supported. See the Regular Expressions section in the ICU User Guide.
    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.
    noteNote: 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( "([a-zA-Z]+[0-9]+|[0-9]+[a-zA-Z]+)[0-9a-zA-Z]*" );
     
    profileBuilder.checkAndApply();
  8. 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.
  9. Whenever the Callback.onRequestLatestFrame method is called, provide the current video frame from the camera by calling IDataCaptureService.submitRequestedFrame.
  10. 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).
      warningImportant! 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.
  11. 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.