Obtaining scanning results

In this guide you will find out how to tell the scanning library what you want to scan, and how to collect subsequent scanning results. This guide assumes you completed "Getting started" guide.

While performing the initial integration in "Getting started" guide, you completed three important steps:

• a) initializing the scanning process (step 3. in Getting started)
• b) presenting the Scanning view controller (end of step 3.)
• c) registering for scanning events (step 4.)

In step a) you define what you want to scan. With step b) you start the scanning process. In step c) you handle scanning results.

Let's look at this in more details.

1. Initializing the scanning settings.

When initializing the scanning settings, you also define what you want to scan. This is specified with PPRecognizerSettings objects.

To see this in more detail, here's the example from Getting started guide:

// To specify we want to perform MRTD (machine readable travel document) recognition, initialize the MRTD recognizer settings
PPMrtdRecognizerSettings *mrtdRecognizerSettings = [[PPMrtdRecognizerSettings alloc] init];

// Add MRTD Recognizer setting to a list of used recognizer settings
[settings.scanSettings addRecognizerSettings:mrtdRecognizerSettings];

// To specify we want to perform USDL (US Driver's license) recognition, initialize the USDL recognizer settings
PPUsdlRecognizerSettings *usdlRecognizerSettings = [[PPUsdlRecognizerSettings alloc] init];

// Add USDL Recognizer setting to a list of used recognizer settings
[settings.scanSettings addRecognizerSettings:usdlRecognizerSettings];

First we initialized PPMrtdRecognizerSettings and PPUsdlRecognizerSettings settings objects.

Different PPRecognizerSettings have different customization options. You can use their properties to customize the behaviour to get what you need.

At last, we added both settings to PPSettings scanSettings array. Existence of PPMrtdRecognizerSettings in PPSettings scanSettings will tell the scanning library it should use PPMrtdRecognizer object in the scanning phase. Similarly, existence of PPUsdlRecognizerSettings in PPSettings scanSettings tells the library to use PPUsdlRecognizer object in the scanning phase.

For each type of object you want to scan on camera images (e.g. PDF417 barcode, US Drivers license, etc..), you need to instantiate the appropriate PPRecognizerSettings object. After initialization and setup, you should add PPRecognizerSettings to PPSettings scanSettings.

Depending on what you want to scan on the images, you will want to use different PPRecognizerSettings objects. For a complete list of available PPRecognizerSettings and subclasses, see the last section of this document.

2. Presenting the Scanning view controller

When Scanning view controller becomes visible on the screen, camera capture starts, and recognition begins. Video frames are collected one by one, and sent to all PPRecognizers defined in the previous step.

The way Scanning view controller is presented doesn't affect the scanning behaviour. Scanning view controller can be presented in many different ways:

1. Presented over the current view controller using presentViewController:animated:completion:
2. Presented on a navigation view controller using pushViewController:animated:
3. As a child view controller in existing VC using addChildViewController:
4. And others, e.g using UITabBarController, UIPageViewController, and so on.

All options for presenting the Scanning view controller are possible. What matters is that when Scanning view controller becomes visible, in viewDidAppear: method, scanning from the device's camera begins. Consequently, when Scanning view controller is being closed, in viewWillDisappear:, scanning stops.

Scanning view controller is created using factory method:

UIViewController<PPScanningViewController>* scanningViewController = [PPViewControllerFactory cameraViewControllerWithDelegate:self coordinator:coordinator error:nil];

Delegate object set in this call needs to define callback methods which will be notified with different scanning events.

3. Registering for scanning events

Delegate object passed to cameraViewControllerWithDelegate: method will be called with different scanning events.

Scanning results are passed to a callback method:

- (void)scanningViewController:(UIViewController<PPScanningViewController> *)scanningViewController
              didOutputResults:(NSArray<PPRecognizerResult *> *)results; 

Scanning library can output one or more PPRecognizerResult objects, all of which are contained in the NSArray results. In this callback you are responsible for handling the results.

PPRecognizerResult class hierarchy closely follows PPRecognizerSettings hierarchy. This means if you initialized the scanning library with PPMrtdRecognizerSettings settings object, you will get PPMrtdRecognizerResult result object (note the same name prefix). If you used PPUsdlRecognizerSettings, you will get PPUsdlRecognizerResult, and so on.

Use the isKindOfClass: method to determine the exact type of the results, like in the following example:

if ([result isKindOfClass:[PPMrtdRecognizerResult class]]) {
	PPMrtdRecognizerResult *mrtdRecognizerResult = (PPMrtdRecognizerResult*)result;
	NSLog(@"Primary ID is: %@", [mrtdRecognizerResult primaryId])
}

When you know the exact type of the result, use it's properties and methods to collect the information you're interested in.

The type of the RecognizerResult object obtained always matches the type of the RecognizerSettings object you used while intializing the scanning library.

4. Available Recognizers in the SDK

MicroBlink's scanning library allows many different Recognizers to be used in the scanning process. Here we provide a complete list, with a link to detailed guide.

Guide	RecognizerSettings	RecognizerResult
Scanning MRTD documents	PPMrtdRecognizerSettings	PPMrtdRecognizerResult
Scanning and parsing US drivers licenses	PPUsdlRecognizerSettings	PPUsdlRecognizerResult
Scanning EU driving licenses	PPEudlRecognizerSettings	PPEudlRecognizerResult
Using PDF417 Recognizer	PPPdf417RecognizerSettings	PPPdf417RecognizerResult
Using BarDecoderRecognizer	PPBarDecoderRecognizerSettings	PPBarDecoderRecognizerResult
Using ZXingRecognizer	PPZXingRecognizerSettings	PPZXingRecognizerResult
Using BlinkOcrRecognizer	PPBlinkOcrRecognizerSettings	PPBlinkOcrRecognizerResult
Using Detector Recognizer	PPDetectorSettings	PPDetectorResult