Get Started With Text Capture#

Note

Please note that Text Capture requires a version of our SDK which isn’t publicly available. To get access to the SDK with Text Capture, please contact us at support@scandit.com.

In this guide you will learn step by step how to add text capture to your application. Roughly, the steps are:

Prerequisites#

Before starting with adding a capture mode, make sure that you have a valid Scandit Data Capture SDK license key and that you added the necessary dependencies. If you have not done that yet, check out this guide.

Note

You can retrieve your Scandit Data Capture SDK license key, by signing in to your account at ssl.scandit.com.

Create the Data Capture Context#

The first step to add barcode capture capabilities to your application is to create a new data capture context. The context expects a valid Scandit Data Capture SDK license key during construction.

DataCaptureContext dataCaptureContext = DataCaptureContext.forLicenseKey("-- ENTER YOUR SCANDIT LICENSE KEY HERE --");

Configure the Text Capture Behavior#

Text capture is orchestrated by the TextCapture data capture mode. This class is the main entry point for capturing text. It is configured through TextCaptureSettings and allows to register one or more listeners that will get informed whenever a new text has been captured.

For creating a TextCaptureSettings instance, you need a JSON containing the necessary configuration for the text capture back-end. For details about the format of the JSON check Text Capture Settings’s JSON Structure.

First, create a TextCaptureSettings instance:

TextCaptureSettings settings = TextCaptureSettings.fromJson(json);

Next, create a TextCapture instance with the settings from the previous step:

this.textCapture = TextCapture.forDataCaptureContext(dataCaptureContext, settings);

Register the Text Capture Listener#

To get informed whenever a new text has been captured, add a TextCaptureListener through TextCapture.addListener() and implement the listener methods to suit your application’s needs.

First implement the TextCaptureListener interface. For example:

@Override
public void onTextCaptured(@NonNull TextCapture textCapture,
        @NonNull TextCaptureSession session, @NonNull FrameData frameData) {
    List<CapturedText> capturedTexts = session.getNewlyCapturedTexts();
    // Do something with the captured texts.
}

Then add the listener:

textCapture.addListener(this);

Use the Built-in Camera#

The data capture context supports using different frame sources to perform recognition on. Most applications will use the built-in camera of the device, e.g. the world-facing camera of a device. The remainder of this tutorial will assume that you use the built-in camera.

When using the built-in camera there are recommended settings for each capture mode. These should be used to achieve the best performance and user experience for the respective mode. The following couple of lines show how to get the recommended settings and create the camera from it:

CameraSettings cameraSettings = TextCapture.createRecommendedCameraSettings();

// Depending on the use case further camera settings adjustments can be made here.

Camera camera = Camera.getDefaultCamera();

if (camera != null) {
    camera.applySettings(cameraSettings);
}

Because the frame source is configurable, the data capture context must be told which frame source to use. This is done with a call to DataCaptureContext.setFrameSource():

dataCaptureContext.setFrameSource(camera);

The camera is off by default and must be turned on. This is done by calling FrameSource.switchToDesiredState() with a value of FrameSourceState.ON:

if (camera != null) {
  camera.switchToDesiredState(FrameSourceState.ON);
}

Note

On Android the Scandit Data Capture SDK is not lifecycle aware which means it is not able to turn off the camera when the app goes in the background etc. which has to be done as otherwise the camera is locked for other apps. This responsibility to do this is left to the implementer. Make sure that you always turn the camera off in the activity’s onPause lifecycle method. Often this means that you want to (re)start it in onResume. You can see a way of doing this in all of the samples.

There is a separate guide for more advanced camera functionality.

Use a Capture View to Visualize the Scan Process#

When using the built-in camera as frame source, you will typically want to display the camera preview on the screen together with UI elements that guide the user through the capturing process. To do that, add a DataCaptureView to your view hierarchy:

DataCaptureView dataCaptureView = DataCaptureView.newInstance(this, dataCaptureContext);
setContentView(dataCaptureView);

To visualize the results of text capture, the following overlay can be added:

TextCaptureOverlay overlay = TextCaptureOverlay.newInstance(textCapture, dataCaptureView);

Disabling Text Capture#

To disable text capture, for instance as a consequence of a text being captured, set TextCapture.isEnabled to false. There will not be any new results until the capture mode is enabled again. Note that disabling the capture mode does not stop the camera, the camera continues to stream frames until it is turned off.

What’s next?

To dive further into the Scandit Data Capture SDK we recommend the following articles: