Using USDL recognizer

USDL recognizer is responsible for scanning, decoding and parsing of PDF417 bardoces on the back sides of US and Canadian drivers licenses (in the following text - USDLs)

If you completed Obtaining scanning results guide, you learned that in order to use a specific recognizer, you need to specify Recognizer Settings object in the initialization stage, and collect Recognizer Result object in the success callback.

Here we explain how to use USDL recognizer, it's settings class PPUsdlRecognizerSettings, and result class PPUsdlRecognizerResult to obtain Driver's license information from the scanning results.

Back to "Getting started" guide.

Initializing the scanning of US driver's licenses

Below is the sample source code which initializes the scanning for US driver's licenses.

// 3. ************* Setup Scan Settings **************/

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

// Set this to YES to scan even barcode not compliant with standards
// For example, malformed PDF417 barcodes which were incorrectly encoded
// Use only if necessary because it slows down the recognition process
// Default: NO
usdlRecognizerSettings.scanUncertain = NO;

// Set this to YES to scan barcodes which don't have quiet zone (white area) around it
// Disable if you need a slight speed boost
// Default: YES
usdlRecognizerSettings.allowNullQuietZone = YES;

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

Retrieving results

By default, scanningViewController:didOutputResults: callback returns results as a PPRecognizerResults object. When the instance of this result is of type PPUsdlRecognizerResult, this means we got the result of USDL scanning and parsing.

Below is the sample source code which demonstrates how to collect results of USDL scanning.

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

    // Here you process scanning results. Scanning results are given in the array of PPRecognizerResult objects.

    // first, pause scanning until we process all the results
    [scanningViewController pauseScanning];

    // Collect data from the result
    for (PPRecognizerResult* result in results) {

        // Check if result is USDL result
        if ([result isKindOfClass:[PPUsdlRecognizerResult class]]) {

            // Cast result to PPUsdlRecognizerResult
            PPUsdlRecognizerResult *usdlResult = (PPUsdlRecognizerResult *)result;

            // Fields of the driver's license can be obtained by using keys defined in PPUsdlRecognizerResult.h header file

            // for First name, use kPPCustomerFirstName
            NSLog(@"First name: %@", [usdlResult getField:kPPCustomerFirstName]);

            // for Middle names, use kPPCustomerMiddleName
            NSLog(@"Middle names: %@", [usdlResult getField:kPPCustomerMiddleName]);

            // for Family name, use kPPCustomerFamilyName
            NSLog(@"Family name: %@", [usdlResult getField:kPPCustomerFamilyName]);
        }
    };

    // either resume scanning, or dismiss Scanning View controller
    // [scanningViewController resumeScanningAndResetState:YES];
    [scanningViewController dismissViewControllerAnimated:YES completion:nil];
}

USDL data in the PPUsdlRecognizerResult object are stored inside a NSDictionary called fields. From this Dictionary you can obtain specific fields using keys declared on top of the PPUsdlRecognizerResult.h header file.

The value for a given key can be obtained the following way:

NSString *value = [usdlResult getField:key]

The USDL Keys document lists all fields that can be obtained from the PPUsdlRecognizerResult object. If pdf417 USDL library didn't recognize a fields value for given key, you will receive nil value.