DOCSEARCHbyAlgolia
Submit Docs

UltimateMRZ SDK

repository·master·Indexed 41 days ago

https://github.com/doubangotelecom/ultimatemrz-sdk

A high-performance, deep-learning-based SDK for detecting and recognizing Machine Readable Zones (MRZ) and Machine Readable Travel Documents (MRTD). It supports Android, iOS, Windows, Linux, and Raspbian, providing local on-device processing without requiring license keys. The SDK requires OpenCL 1.2 or higher and offers integration for C++ and Python, with support for various architectures including arm64-v8a, x86_64, and armv7l.

Tokens
15.1K
Snippets
48
Records
94
Agent score
52%

What's inside UltimateMRZ SDK

  1. Overview of ultimateMRZ-SDK

    master

    The ultimateMRZ-SDK is a deep-learning-based SDK for detecting and recognizing Machine Readable Zones (MRZ) and Machine Readable Travel Documents (MRTD).

    Key features include:

    • High Accuracy: Processes the entire image (up to 4K) without requiring a predefined Region of Interest (ROI). It handles small, far, blurred, occluded, skewed, or slanted MRZ lines.
    • Agnostic Detection: Does not rely on pre-defined regular expressions for detection, making it compatible with all MRZ types (Travel Documents 1/2/3, MRVA, MRVB, etc.) regardless of font or country.
    • High Performance: Capable of running up to 50fps on ARM devices (e.g., iPhone 7) and 114fps on x86_64 (e.g., Core i7) using 720p HD images.
    • Privacy-Focused: All processing happens locally on the device; no data leaves the machine.
    • No Licensing Required: No registration, license keys, or internet connection are needed to use the SDK binaries provided in the repository.

  2. Overview of C++ Samples

    master

    The SDK provides 5 C++ samples for testing and integration. Each sample typically contains a single C++ source file, making them easy to cross-compile.

    Available samples:

    • Benchmark: Performance testing.
    • Parser: Data parsing functionality.
    • Recognizer: Video/image recognition.
    • RuntimeKey: Runtime key management.
    • Validation: Validation logic.

    Note: For mobile platforms, it is recommended to use the platform-specific samples instead of C++:

    • Android: Use the Java samples in the ../android folder (requires Android Studio).
    • iOS: Use the Obj-C samples in the ../iOS folder (requires Xcode).

  3. Use the C++ Video Recognizer sample application

    master

    The recognizer application is a reference implementation for the C++ API. It allows you to process JPEG, PNG, or BMP images to check MRZ (Machine Readable Zone) accuracy.

    Note on Performance: While this sample accepts image files, it is not the recommended way to use the SDK in production. For optimal performance, you should read data directly from a camera and feed the SDK with uncompressed YUV data to avoid the overhead of file I/O and RGB conversion.

  4. Compatibility and Architecture for Raspbian Binaries

    master

    The provided binaries are cross-compiled for Raspbian Buster and are compatible with Raspberry Pi 3 and Raspberry Pi 4.

    Important Architecture Note: Even though Raspberry Pi 3 and 4 feature 64-bit CPUs, Raspbian typically uses a 32-bit kernel. Consequently, this SDK provides armv7l binaries rather than arm64-a. Ensure your target environment is running a 32-bit Raspbian OS to match these binaries.

  6. Explore sample applications by platform

    master

    The ultimatemrz-sdk repository provides several sample applications to demonstrate different capabilities like Video Recognition, Benchmarking, Parsing, and Validation. You can find samples tailored to your target platform in the following directories:

    • Android: GUI applications for Android 5.0+ written in Java (located in android/).
    • iOS: GUI applications for iOS 8.0+ (located in iOS/).
    • Windows, Raspberry Pi, and Linux: Command-line applications written in C++ (located in c++/). Note that while these can be used for Android or iOS, it is recommended to use the platform-specific Java or Swift/Objective-C samples instead.
    • Cross-platform (Command-line):
      • Java: Command-line applications compatible with all supported platforms (located in java/).
      • Python: Command-line applications compatible with all supported platforms (located in python/).
      • C#: Visual Studio command-line applications configured for Win64, but compatible with any platform supporting C# (located in csharp/).

  7. Android Sample Applications: Benchmark and VideoRecognizer

    master

    The Android directory contains two specific sample applications for testing and demonstrating the SDK's capabilities:

    1. Benchmark: Used for performance testing and measuring SDK metrics.
    2. VideoRecognizer: Demonstrates real-time video recognition capabilities.

    For detailed instructions on how to build and run these samples on Android devices, refer to the Trying the samples (Android) section in the main repository README.

  9. Understand Android application-wide licenses

    master

    Starting from version v2.10.0, the SDK supports application-wide licenses. Unlike device-based licenses, these are attached to an application identifier, making them suitable for apps distributed via stores (like Google Play) with no limit on the number of devices.

    An Android license is a base64 encrypted string containing three elements:

    1. The application identifier: Your app's unique ID.
    2. The list of allowed installers: The stores from which the app can be installed (e.g., Google Play, Amazon, Huawei).
    3. The signing certificate's fingerprint: The SHA256 fingerprint of your app's signing key.

    Runtime Validation Checks

    At runtime, the SDK performs three checks:

    • Check #1: Verifies the application identifier matches the license.
    • Check #2: Verifies the application was signed with the certificate fingerprint stored in the license.
    • Check #3: Verifies the application was installed from a registered store listed in the license.

    Note on Testing: Because of Check #3, you cannot test an application-wide license during local development (via debug/direct install) because the installer won't match a registered store. For testing, use (free) device-based licenses instead.

  10. Add the SDK to an iOS project

    master

    The SDK is provided as a FAT C++ framework located at binaries/ios/ultimate_mrz-sdk.framework.

    Note: The framework contains a single C++ header file. If you are using Swift, you will need to write an Objective-C wrapper. Please contact Doubango if you require a Swift-native framework.

    Integration Steps (Xcode):

    1. Add Framework: Select your target, go to the General section, find Framework, Libraries, and Embedded Content, and press + to add binaries/ios/ultimate_mrz-sdk.framework.
    2. Set Search Paths: In the Build Settings section, find Framework Search Paths and add the path to the folder containing the framework (e.g., ultimateMRZ-SDK/binaries/ios).
    3. Add Models: Right-click your project, select Add Files to..., and browse to the ultimateMRZ-SDK/assets/models folder. This ensures the models and configuration files are included in the app bundle resources.

  11. Build the Video Recognizer using Visual Studio (Windows)

    master

    Open the recognizer.vcxproj file in Visual Studio and configure the following settings:

    1. Command Arguments: Set the --image and --assets paths. Default: --image $(ProjectDir).\..\..\..\assets\images\Czech_passport_2005_MRZ_orient1_1300x1002.jpg --assets $(ProjectDir)\..\..\..\assets
    2. Environment: Update the PATH variable to include the binaries directory. Default: PATH=$(VCRedistPaths)%PATH%;$(ProjectDir)\..\..\..\binaries\windows\x86_64

  12. Build the C++ benchmark sample with GCC

    master

    The benchmark sample consists of a single C++ source file (main.cxx). You can build it using a generic GCC command. You must replace <yourOS> and <yourArch> with the appropriate values for your system (e.g., linux and x86_64).

    If cross-compiling (e.g., for Android ARM64), replace g++ with the appropriate compiler triplet like aarch64-linux-android-g++.

    cd ultimateMRZ-SDK/samples/c++/benchmark

g++ main.cxx -O3 -I../../../c++ -L../../../binaries/<yourOS>/<yourArch> -lultimate_mrz-sdk -o benchmark