Data Scanner | iOS Document Scanner

The Scanbot SDK comes with separate scanners for many specific use cases. Use cases that are not covered by any of these specialized scanners can be tackled with the Data Scanner module. This module's main class is SBSDKGenericTextLineRecognizer. You can configure its behavior using the SBSDKGenericTextLineRecognizerConfiguration class.

The Data Scanner recognizes text (OCR) within a user-defined rectangular area of interest, in consecutive video frames. A customizable block lets you clean up the raw string by filtering it against unwanted characters and OCR noise. Additionally, you can validate the result using pattern-matching or another block.

The Data Scanner returns an SBSDKGenericTextLineRecognizerResult object when it recognizes text. This result contains the cleaned-up string as well as a boolean flag that informs you whether the validation was successful or not.

Use cases for the Data Scanner module are the recognition of single-line text like IBAN numbers, insurance numbers, dates and other textual data fields that can be easily validated i.e. pattern-matched.

How is the Data Scanner different from regular OCR? In short, it is more reliable and robust, with higher confidence in text recognition because it accumulates the results of multiple video frames as well as your input from the raw text clean-up block.

To make the integration painless, the Scanbot SDK provides a simple-to-use plugin-viewcontroller named SBSDKGenericTextLineRecognizerViewController that takes over the camera handling, displays the area of interest, and runs the Data Scanner. The scanner's results are passed to a delegate.

The Generic Text Line Recognizer is based on the OCR feature and thus requires the proper installation of the corresponding OCR language files (e.g. for English please add the file eng.traineddata). For more details on how to set up the OCR language files please refer to the OCR section.

Generic Text Line Recognizer UI

There are two ways to integrate the component into the application:

• Ready to use UI component (more about RTU UI)
• Classic UI component (more about Classic components)

danger

Please be aware that processing really large images may lead to out-of-memory crashes on iOS. Since this limit is highly dynamic and untransparent in iOS, depending on the device, your app's current memory usage, the other running apps, the iOS version, the system configuration and many other unknown variables, we did not add a hard limit for image sizes.

As a general rule of thumb, it is quite safe to assume that processing images of the resolution the camera can shoot will most likely not crash your app. On most modern iOS devices this currently translates to 12 megapixels. But even much larger images may work without crashing as well.

Thus we cannot take responsibility for out-of-memory crashes when dealing with very high-resolution images. It is your responsibility, as an app developer, to properly manage the handling of large images and keep the memory footprint of your app as small as possible.

In case you have any questions on this topic, please reach out to our support team.

caution

Please do not use multiple scanners at the same time. For example, do not combine generic document scanner, health insurance scanner, text data scanner, etc. at the same time! Each scanner instance requires a lot of memory, GPU, and processor resources. Using multiple scanners will lead to performance issues for the entire application.

Ready-To-Use UI Component

The main class of the Ready-To-Use UI (RTU UI) component is SBSDKUITextDataScannerViewController.

Usually, this view controller is used as a separate screen for scanning one-line texts in a UIImage or SampleBufferRef. It returns the recognition results in a delegate method.

While you don't have direct control of the actual scanner view controller you can use the SBSDKUITextDataScannerConfiguration to customize it in a variety of ways, such as colors, texts, and behavior.

Swift

import UIKit
import ScanbotSDK

class GenericTextLineRecognizerUISwiftViewController: UIViewController {

    override func viewDidAppear(_ animated: Bool) {
        super.viewDidAppear(animated)

        // Start scanning here. Usually this is an action triggered by some button or menu.
        self.startScanning()
    }

    func startScanning() {

        // Create the default configuration object.
        let configuration = SBSDKUITextDataScannerConfiguration.defaultConfiguration

        // Behavior configuration:
        // e.g. enable highlighting of the detected word boxes.
        configuration.behaviorConfiguration.wordBoxHighlightEnabled = true

        // UI configuration:
        // e.g. configure various colors.
        configuration.uiConfiguration.topBarBackgroundColor = UIColor.red
        configuration.uiConfiguration.topBarButtonsColor = UIColor.white

        // Text configuration:
        // e.g. customize a UI element's text.
        configuration.textConfiguration.cancelButtonTitle = "Cancel"

        // Create the data scanner step.
        let step = SBSDKUITextDataScannerStep()

        // Set the finder's unzoomed height.
        step.unzoomedFinderHeight = 100

        // Set the aspect ratio.
        step.aspectRatio = SBSDKAspectRatio(width: 4.0, height: 1.0)

        // Set the guidance text.
        step.guidanceText = "Scan a document"

        configuration.behaviorConfiguration.recognitionStep = step
        // Present the recognizer view controller modally on this view controller.
        SBSDKUITextDataScannerViewController.present(on: self,
                                                     configuration: configuration,
                                                     delegate: self)
    }
}

extension GenericTextLineRecognizerUISwiftViewController: SBSDKUITextDataScannerViewControllerDelegate {
    func textLineRecognizerViewController(_ viewController: SBSDKUITextDataScannerViewController,
                                          didFinish step: SBSDKUITextDataScannerStep,
                                          with result: SBSDKUITextDataScannerStepResult) {
        // Process the recognized result.
    }
}

Objective-C

#import "GenericTextLineRecognizerUIObjcViewController.h"
@import ScanbotSDK;

@interface GenericTextLineRecognizerUIObjcViewController () <SBSDKUITextDataScannerViewControllerDelegate>

@end

@implementation GenericTextLineRecognizerUIObjcViewController

- (void)viewDidAppear:(BOOL)animated {
    [super viewDidAppear:animated];

    // Start scanning here. Usually this is an action triggered by some button or menu.
    [self startScanning];
}

- (void)startScanning {

    // Create the default configuration object.
    SBSDKUITextDataScannerConfiguration *configuration = [SBSDKUITextDataScannerConfiguration defaultConfiguration];

    // Behavior configuration:
    // e.g. enable highlighting of the detected word boxes.
    configuration.behaviorConfiguration.wordBoxHighlightEnabled = YES;

    // UI configuration:
    // e.g. configure various colors.
    configuration.uiConfiguration.topBarBackgroundColor = [UIColor redColor];
    configuration.uiConfiguration.topBarButtonsColor = [UIColor whiteColor];

    // Text configuration:
    // e.g. customize a UI element's text.
    configuration.textConfiguration.cancelButtonTitle = @"Cancel";

    // Create the data scanner step.
    SBSDKUITextDataScannerStep *step = [[SBSDKUITextDataScannerStep alloc] init];

    // Set the finder's unzoomed height.
    step.unzoomedFinderHeight = 100;

    // Set the aspect ratio.
    step.aspectRatio = [[SBSDKAspectRatio alloc] initWithWidth:4.0 andHeight:1.0];

    // Set the guidance text.
    step.guidanceText = @"Scan a document";

    configuration.behaviorConfiguration.recognitionStep = step;
    // Present the recognizer view controller modally on this view controller.
    [SBSDKUITextDataScannerViewController presentOn:self
                                      configuration:configuration
                                           delegate:self];
}

- (void)textLineRecognizerViewController:(nonnull SBSDKUITextDataScannerViewController *)viewController
                           didFinishStep:(nonnull SBSDKUITextDataScannerStep *)step
                              withResult:(nonnull SBSDKUITextDataScannerStepResult *)result {
    // Process the recognized result.
}

@end

Classic UI Component

The main class of the Classic UI component is SBSDKGenericTextLineRecognizerViewController.

Usually, this view controller is embedded as a child view controller into another view controller, the parent view controller. The parent view controller usually acts as the delegate and processes the recognition results. You still have full control over the UI elements and can add additional views and buttons to your view controller. The Classic component does not display results, instead, it just forwards them to the delegate.

Swift

import UIKit
import ScanbotSDK

class GenericTextLineRecognizerSwiftViewController: UIViewController {

    // The instance of the scanner view controller.
    var recognizerController: SBSDKGenericTextLineRecognizerViewController?

    override func viewDidLoad() {
        super.viewDidLoad()

        // Create the default SBSDKGenericTextLineRecognizerConfiguration object.
        let configuration = SBSDKGenericTextLineRecognizerConfiguration.defaultConfiguration

        // Create the SBSDKGenericTextLineRecognizerViewController instance.
        self.recognizerController = SBSDKGenericTextLineRecognizerViewController(parentViewController: self,
                                                                                 parentView: self.view,
                                                                                 configuration: configuration,
                                                                                 delegate: self)
    }
}

extension GenericTextLineRecognizerSwiftViewController: SBSDKGenericTextLineRecognizerViewControllerDelegate {
    func textLineRecognizerViewController(_ controller: SBSDKGenericTextLineRecognizerViewController,
                                          didValidate result: SBSDKGenericTextLineRecognizerResult) {
        // Process the recognized result.
    }
}

Objective-C

#import "GenericTextLineRecognizerObjcViewController.h"
@import ScanbotSDK;

@interface GenericTextLineRecognizerObjcViewController () <SBSDKGenericTextLineRecognizerViewControllerDelegate>

// The instance of the scanner view controller.
@property (strong, nonatomic) SBSDKGenericTextLineRecognizerViewController *recognizerController;

@end

@implementation GenericTextLineRecognizerObjcViewController

- (void)viewDidLoad {
    [super viewDidLoad];

    // Create the default SBSDKGenericTextLineRecognizerConfiguration object.
    SBSDKGenericTextLineRecognizerConfiguration *configuration = [SBSDKGenericTextLineRecognizerConfiguration defaultConfiguration];

    // Create the SBSDKGenericTextLineRecognizerViewController instance.
    self.recognizerController = [[SBSDKGenericTextLineRecognizerViewController alloc] initWithParentViewController:self
                                                                                                        parentView:self.view
                                                                                                     configuration:configuration
                                                                                                          delegate:self];
}

- (void)textLineRecognizerViewController:(SBSDKGenericTextLineRecognizerViewController *)controller
                       didValidateResult:(SBSDKGenericTextLineRecognizerResult *)result {
    // Process the recognized result.
}

@end

Want to scan longer than one minute?

Generate your free "no-strings-attached" Trial License and properly test the Scanbot SDK.

Get your free Trial License

What do you think of this documentation?

What can we do to improve it? Please be as detailed as you like.

---