Get Started With Text Capture

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

  • Include the ScanditTextCapture framework and its dependencies to your project, if any.

  • Create a new data capture context instance, initialized with your license key.

  • Create a text capture settings instance.

  • Create a new text capture mode instance and initialize it with the settings created above.

  • Register a text capture listener to receive events when a new text is captured.

  • Obtain a camera instance and set it as the frame source on the data capture context.

  • Display the camera preview by creating a data capture view.

  • If displaying a preview, optionally create a new overlay and add it to data capture view for a better visual feedback.

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/dashboard/sign-in.

Internal dependencies

Some of the Scandit Data Capture SDK modules depend on others to work:

Module

Dependencies

ScanditCaptureCore

No dependencies

ScanditBarcodeCapture

  • ScanditCaptureCore

ScanditParser

No dependencies

ScanditOCR

No dependencies

ScanditTextCapture

  • ScanditCaptureCore

  • ScanditTXT

ScanditIdCapture

  • ScanditCaptureCore

  • ScanditIDC (VIZ documents)

ScanditIDC

No dependencies

ScanditTXT

No dependencies

Create the Data Capture Context

The first step to add 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.

self.context = DataCaptureContext(licenseKey: "-- ENTER YOUR SCANDIT LICENSE KEY HERE --")

Configure the Text Capture Behavior

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

For creating a SDCTextCaptureSettings 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 JSON Structure.

First, create a SDCTextCaptureSettings instance:

let settings = try TextCaptureSettings(jsonString: json)

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

self.textCapture = TextCapture(context: context, settings: settings)

Register the Text Capture Listener

To get informed whenever a new text has been captured, add a SDCTextCaptureListener through SDCTextCapture.addListener: and implement the listener methods to suit your application’s needs.

First conform to the SDCTextCaptureListener protocol. For example:

extension ViewController: TextCaptureListener {
    func textCapture(_ textCapture: TextCapture,
                   didCaptureIn session: TextCaptureSession,
                   frameData: FrameData) {
        let capturedTexts = session.newlyCapturedTexts
        for text in capturedTexts {
            // Do something with the captured text.
        }
    }
}

Then add the listener:

textCapture.addListener(self)

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.

Important

In iOS, the user must explicitly grant permission for each app to access cameras. Your app needs to provide static messages to display to the user when the system asks for camera permission. To do that include the NSCameraUsageDescription key in your app’s Info.plist file.

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:

let cameraSettings = TextCapture.recommendedCameraSettings()

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

let camera = Camera.default
camera?.apply(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 SDCDataCaptureContext.setFrameSource:completionHandler::

context.setFrameSource(camera)

The camera is off by default and must be turned on. This is done by calling SDCFrameSource.switchToDesiredState:completionHandler: with a value of SDCFrameSourceStateOn:

camera?.switch(toDesiredState: .on)

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 SDCDataCaptureView to your view hierarchy:

let captureView = DataCaptureView(for: context, frame: view.bounds)
captureView.dataCaptureContext = context
captureView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
view.addSubview(captureView)

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

let overlay = TextCaptureOverlay(textCapture: textCapture, view: captureView)

Disabling Text Capture

To disable text capture, for instance as a consequence of a text being captured, set SDCTextCapture.enabled to NO. The effect is immediate: no more frames will be processed after the change. However, if a frame is currently being processed, this frame will be completely processed and deliver any results/callbacks to the registered listeners. 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: