iOS User Guide for MRZ Integration

In this guide, you will learn step by step on how to build a MRZ scanner application with Dynamsoft Capture Vision iOS SDK.

iOS User Guide for MRZ Integration

Supported Machine-Readable Travel Document Types

The Machine Readable Travel Documents (MRTD) standard specified by the International Civil Aviation Organization (ICAO) defines how to encode information for optical character recognition on official travel documents.

Currently, the SDK supports three types of MRTD:

Note: If you need support for other types of MRTDs, our SDK can be easily customized. Please contact support@dynamsoft.com.

ID (TD1 Size)

The MRZ (Machine Readable Zone) in TD1 format consists of 3 lines, each containing 30 characters.

ID (TD2 Size)

The MRZ (Machine Readable Zone) in TD2 format consists of 2 lines, with each line containing 36 characters.

Passport (TD3 Size)

The MRZ (Machine Readable Zone) in TD3 format consists of 2 lines, with each line containing 44 characters.

Requirements

Supported OS: iOS 11+ (iOS 13+ recommended).
Supported ABI: arm64 and x86_64.
Development Environment: Xcode 13+ (Xcode 14.1+ recommended).

Add the SDK

There are two ways to add the SDK into your project - CocoaPods, or via Swift Package Manager.

Add the xcframeworks via CocoaPods

Add the frameworks in your Podfile, replace TargetName with your real target name.
```
 target '{Your project name}' do
     use_frameworks!

     pod 'DynamsoftCaptureVisionBundle','2.2.3000'

 end
```
Read more about the modules of DynamsoftCaptureVisionBundle
Execute the pod command to install the frameworks and generate workspace({Your project name}.xcworkspace):
```
pod install
```

Add the xcframeworks via Swift Package Manager

In your Xcode project, go to File –> AddPackages.
In the top-right section of the window, search “https://github.com/Dynamsoft/capture-vision-spm”
Select capture-vision-spm, choose Exact version, enter 2.2.3000, then click Add Package.
Check all the frameworks and add.

Build Your First Application

In this section, we will explain how to create a HelloWorld implementation similar to our simple MRZScanner app for reading the MRZ zone from camera video input.

Note:

The following steps are completed in XCode 14.2

You can get similar source code from MRZScanner Sample(Swift)

Create a New Project

Open XCode and select Create a new Xcode Project or in the File > New > Project menu to create a new project.
Select iOS -> App for your application.
Input your product name (HelloWorld), interface (StoryBoard) and language (Swift)
Click on Next and select the location to save the project.
Click on Create to finish creating the new project.

Include the Library

To add the SDK to your new project, please read Add the SDK section for more details.

Deploy the CharacterModel & Template

A CharacterModel is a model file trained using deep neural networks for character recognition. A Template file in the Dynamsoft Capture Vision SDK offers a customizable configuration for optimizing barcode recognition, label recognition, document normalization, and bytes parsing settings. This enables users to tailor the capture process to their specific needs. For MRZ scanning, you have to include the required the MRZ CharacterModel and Template in your project first.

Create a DynamsoftResources folder in the finder. Under the DynamsoftResources folder create two new folders, CharacterModel and Templates.
Copy the MRZ.data to the CharacterModel folder.
Copy your template file MRZScanner.json to the Templates folder.
Rename the DynamsoftResources folder’s extension name to .bundle and drag the DynamsoftResources.bundle into your project on Xcode. Select Create groups for the Added folders option.

Initialize the License

Use the LicenseManager class and initialize the license in AppDelegate.

 import DynamsoftLicense
 class AppDelegate: UIResponder, UIApplicationDelegate, LicenseVerificationListener {
     func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
         LicenseManager.initLicense("DLS2eyJvcmdhbml6YXRpb25JRCI6IjIwMDAwMSJ9", verificationDelegate:self)
         return true
     }
     func onLicenseVerified(_ isSuccess: Bool, error: Error?) {
         if(error != nil)
         {
             if let msg = error?.localizedDescription {
                 print("Server license verify failed, error:\(msg)")
             }
         }
     }
 }

Note:

The license string here grants a time-limited free trial which requires network connection to work.

You can request for a 30-day trial license via the Trial License link.

Initialize the Camera Module

Create the instances of CameraEnhancer and CameraView in ViewController.

import DynamsoftCameraEnhancer
...
class ViewController: UIViewController {
    private var dce: CameraEnhancer!
    private var dceView: CameraView!
    private var dlrDrawingLayer: DrawingLayer!

    private func configureDCE() -> Void {
        dceView = .init(frame: view.bounds)
        dceView.scanLaserVisible = true
        dceView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        self.view.addSubview(dceView)
        
        dlrDrawingLayer = dceView.getDrawingLayer(DrawingLayerId.DLR.rawValue)
        dlrDrawingLayer!.visible = true
        dce = CameraEnhancer(view: dceView)
        dce.enableEnhancedFeatures(.frameFilter)
   }
}

Initialize the Capture Vision Router

Create an instance of CaptureVisionRouter and bind it with the already created instance of DynamsoftCameraEnhancer.

import DynamsoftCaptureVisionRouter
import DynamsoftUtility
...
class ViewController: UIViewController {
    private var cvr: CaptureVisionRouter!
    private var resultFilter: MultiFrameResultCrossFilter!
    ...
    private func configureCVR() -> Void {
        cvr = CaptureVisionRouter()

        try? cvr.initSettingsFromFile("MRZScanner.json")
        try? cvr.setInput(dce)
        
        // Add filter.
        resultFilter = MultiFrameResultCrossFilter()
        resultFilter.enableResultCrossVerification(.textLine, isEnabled: true)
        cvr.addResultFilter(resultFilter)
    }
}

Implement Result Receiver

Set up result callback in order to receive the parsed MRZ results after the capturing starts.

import DynamsoftCodeParser
...
// Add CapturedResultReceiver to the class.
class ViewController: UIViewController, CapturedResultReceiver {
    ...
    private func configureCVR() -> Void {
        ...
        // Add a CaptureResultReceiver to receive results.
        cvr.addResultReceiver(self)
    }
    
    func onParsedResultsReceived(_ result: ParsedResult) {
        // Deal with the parsed results.
    }
}

Extract Parsed Results

class ViewController: UIViewController, CapturedResultReceiver {
    ...
    func onParsedResultsReceived(_ result: ParsedResult) {
        guard let items = result.items else { return }
        guard let firstItem = items.first else { return }
        let parsedFields = firstItem.parsedFields
        let passportNumber = parsedFields["passportNumber"] ?? parsedFields["documentNumber"] ?? ""
        let sex = parsedFields["sex"] ?? ""
        let issuingState = parsedFields["issuingState"] ?? ""
        let nationality = parsedFields["nationality"] ?? ""
        let secondaryIdentifier = parsedFields["secondaryIdentifier"] ?? ""
        let primaryIdentifier = parsedFields["primaryIdentifier"] ?? ""
        let dateOfBirth = parsedFields["dateOfBirth"] ?? ""
        let dateOfExpiry = parsedFields["dateOfExpiry"] ?? ""
        let parsedString = "Name: " + secondaryIdentifier + " " + primaryIdentifier + "\n" + "Gender: " + sex + "\n" + "Issuing State: " + issuingState + "\n" + "Nationality: " + nationality + "\n" + "Date of Birth(YY-MM-DD): " + dateOfBirth + "\n" + "Date of Expiry(YY-MM-DD): " + dateOfExpiry
        print(parsedString)
    }
}

Configure viewWillAppear, viewWillDisappear, viewDidLoad

Time to configure these core functions that will connect everything together. All of the configuration code such as the configureCVR and configureDCE goes in viewDidLoad. While viewWillAppear contains the method that will open the camera and start MRZ scanning.

class ViewController: UIViewController, CapturedResultReceiver {
    override func viewDidLoad() {
        super.viewDidLoad()
            // Do any additional setup after loading the view.
        self.title = "MRZScanner"
        
        configureDCE()
        configureCVR()
        dce.open()
        print("Open")
        cvr.startCapturing("ReadPassportAndId") {
            isSuccess, error in
            if let error = error {
                print(error.localizedDescription)
            }
        }
    }
        
    override func viewWillAppear(_ animated: Bool) {
        super.viewWillAppear(animated)
        self.navigationController?.navigationBar.tintColor = .white
        self.navigationController?.navigationBar.titleTextAttributes = [
            NSAttributedString.Key.foregroundColor: UIColor.white]
        self.navigationController?.navigationBar.barTintColor = UIColor(red: 59.003 / 255.0, green: 61.9991 / 255.0, blue: 69.0028 / 255.0, alpha: 1)


    }

    override func viewWillDisappear(_ animated: Bool) {
        super.viewWillDisappear(animated)
        dce.close()
    }
}

Configure Camera Privacy

Add Privacy - Camera Usage Description to the info.plist of your project to request camera permission. An easy way to do this is to access your project settings, go to Info and then add this Privacy property to the iOS target properties list.

Build and Run the Project

Before deploying the project, select the device that you want to run your app on.
Run the project, then your app will be installed on your device.

Note: View the similar source code from MRZScanner Sample(Swift)