Using MRTD recognizer

MRTD recognizer is used for scanning and parsing Machine readable travel documents. Typical MRTDs are passports, visas, ID cards - They can be recognized by two or three lines of monospace text, which contains all personal information.

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 MRTD recognizer, it's settings class PPMrtdRecognizerSettings, and result class PPMrtdRecognizerResult to obtain personal ID information from scanned travel document.

Back to "Getting started" guide.

Initializing the scanning of MRTD documents

Below is the sample source code which initializes the scanning for MRTD documents

// To specify we want to perform MRTD (machine readable travel document) recognition, initialize the MRTD recognizer settings
PPMrtdRecognizerSettings *mrtdRecognizerSettings = [[PPMrtdRecognizerSettings alloc] init];
    
/**
 * Region of the image which will be OCR-ed.
 *
 * If detectMachineReadableZonePosition is set to YES, then the OCR area will be determined automatically, and this property
 * does not have any effect.
 *
 * Default:
 *  When device is in portrait: (0.0f, 0.52f, 1.0f, 0.18f);
 *  When device is in landscape: (0.15f, 0.535f, 0.7f, 0.315f);
 *
 * If you want to change this, keep in mind:
 *  - it might be a good idea to have different values for portrait and landscape
 *  - larger area means easier positioning of the device above the ID card or passport
 *  - larger area also means slower OCR process (time consumption depends roughly linearly to image size)
 */
mrtdRecognizerSettings.mrtdRoi = CGRectMake(0.0f, 0.52f, 1.0f, 0.18f);

/**
 * If YES, MRTD recognizer will try to detect the position of Machine readable zone,
 * instead of using mrtdRoi as position. Effectively, if YES is used, value in mrtdRoi isn't used.
 *
 * Default is NO.
 *
 * In general, NO is the safe variant, if your UI is designed so that the user needs to place the camera
 * correctly above the ID document.
 */
mrtdRecognizerSettings.detectMachineReadableZonePosition = NO;

/**
 * If YES, and detectMachineReadableZonePosition is YES, MRTD recognizer will determine the position of the whole
 * MRTD document, based on the position of the machine readable zone.
 *
 * Also, MRTD recognizer will dewarp and crop the image around the MRTD.
 *
 * This is useful if you're at the same time obtaining Dewarped image metadata, since it allows you to obtain dewarped and cropped
 * images of MRTD documents. Dewarped images are returned to scanningViewController:didOutputMetadata: callback,
 * as PPImageMetadata objects with name @"MRTD"
 *
 * If NO, or if detectMachineReadableZonePosition is NO, this logic is not performed.
 */
mrtdRecognizerSettings.dewarpFullDocument = NO;

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

Retrieving results

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

Below is the sample source code which demonstrates how to collect results of MRTD 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 MRTD result
        if ([result isKindOfClass:[PPMrtdRecognizerResult class]]) {

            // Cast result to PPMrtdRecognizerSettings
            PPMrtdRecognizerResult *mrtdResult = (PPMrtdRecognizerResult *)result;

            // Fields of the MRTD document can be obtained by using keys defined in PPMrtdRecognizerResult.h header file

            // for First name (primary ID), use primaryId method
            NSLog(@"Primary ID: %@\n", [mrtdResult primaryId]);

            // for Last name (secondary ID), use secondaryId method
            NSLog(@"Secondary ID: %@\n", [mrtdResult secondaryId]);

            // for Issuing state, use issuer method
            NSLog(@"Issuing state: %@\n", [mrtdResult issuer]);

            // for Document number, use documentNumber method
            NSLog(@"Document number: %@\n", [mrtdResult documentNumber]);

            // for Document code, use documentCode method
            NSLog(@"Document code: %@\n", [mrtdResult documentCode]);

            // for Date of expiry, use dateOfExpiry method
            NSLog(@"Date of expiry: %@\n", [mrtdResult dateOfExpiry]);

            // for Date of birth, use dateOfBirth method
            NSLog(@"Date of birth: %@\n", [mrtdResult dateOfBirth]);

            // for Date of birth, use nationality method
            NSLog(@"Nationality: %@\n", [mrtdResult nationality]);

            // for Date of birth, use sex method
            NSLog(@"Sex: %@\n", [mrtdResult sex]);

            // for Date of birth, use opt1 method
            NSLog(@"Opt1: %@\n", [mrtdResult opt1]);

            // for Date of birth, use opt2 method
            NSLog(@"Opt2: %@\n", [mrtdResult opt2]);

            // for obtaining the whole MRZ text, use mrzText method
            NSLog(@"MRZ text: %@\n", [mrtdResult mrzText]);
        }
    };

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