Using MRTD recognizer in Swift

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
let mrtdRecognizerSettings : PPMrtdRecognizerSettings = PPMrtdRecognizerSettings()
    
/**
 * 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.0, 0.52, 1.0, 0.18);

/**
 * 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 = false;

/**
 * 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 = false;

// 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.

func scanningViewController(scanningViewController: UIViewController?, didOutputResults results: [PPRecognizerResult]) {

    let scanController : PPScanningViewController = scanningViewController as! PPScanningViewController

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

    // first, pause scanning until we process all the results
    scanController.pauseScanning()

    // Collect data from the result
    for result in results {
        if(result.isKindOfClass(PPMrtdRecognizerResult)) {
            let mrtdResult : PPMrtdRecognizerResult = result as! PPMrtdRecognizerResult
        
            // 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
            print("Primary ID: %@\n",mrtdResult.primaryId())

            // for Last name (secondary ID), use secondaryId method
            print("Secondary ID: %@\n",mrtdResult.secondaryId())

            // for Issuing state, use issuer method
            print("Issuing state: %@\n",mrtdResult.issuer())

            // for Document number, use documentNumber method
            print("Document number: %@\n",mrtdResult.documentNumber())

            // for Document code, use documentCode method
            print("Document code: %@\n",mrtdResult.documentCode())

            // for Date of expiry, use dateOfExpiry method
            print("Date of expiry: %@\n",mrtdResult.dateOfExpiry())

            // for Date of birth, use dateOfBirth method
            print("Date of birth: %@\n",mrtdResult.dateOfBirth())

            // for Date of birth, use nationality method
            print("Nationality: %@\n",mrtdResult.nationality())

            // for Date of birth, use sex method
            print("Sex: %@\n",mrtdResult.sex())

            // for Date of birth, use opt1 method
            print("Opt1: %@\n",mrtdResult.opt1())

            // for Date of birth, use opt2 method
            print("Opt2: %@\n",mrtdResult.opt2())

            // for obtaining the whole MRZ text, use mrzText method
            print("MRZ text: %@\n",mrtdResult.mrzText())
        }
    }

    // either resume scanning, or dismiss Scanning View controller
    // scanningViewController.resumeScanningAndResetState(true)
    scanningViewController.dismissViewControllerAnimated(true, completion:nil)
}