C++ API

The APIs from all other languages are generated from the C++ code using SWIG. It’s straightforward to use the API from different languages based on this documentation as threre are only #3 useful functions.

Sample code for Android using Java could be found here.

The header file to include is defined at https://github.com/DoubangoTelecom/ultimateMRZ-SDK/blob/master/c++/ultimateMRZ-SDK-API-PUBLIC.h

enum ultimateMrzSdk::ULTMRZ_SDK_IMAGE_TYPE

Defines the image types.

Values:

ULTMRZ_SDK_IMAGE_TYPE_RGB24

Each pixel is stored on 3 bytes. Each channel (R, G, B) is stored with 8 bits (1 byte) of precision (256 possible values). The R channel is stored at the lowest memory address followed by G then B channels. Here is how the pixels are packed:

const int pixel = (B & 0xff) << 16 | (G & 0xff) << 8 | (R & 0xff);

ULTMRZ_SDK_IMAGE_TYPE_RGBA32

Each pixel is stored on 4 bytes. Each channel (R, G, B, A) is stored with 8 bits (1 byte) of precision (256 possible values). The R channel is stored at the lowest memory address followed by G, B then A channels. If you’re using Android then, this is the same as ARGB_8888. Here is how the pixels are packed:

const int pixel = (A & 0xff) << 24 | (B & 0xff) << 16 | (G & 0xff) << 8 | (R & 0xff);

ULTMRZ_SDK_IMAGE_TYPE_BGRA32

Each pixel is stored on 4 bytes. Each channel (B, G, R, A) is stored with 8 bits (1 byte) of precision (256 possible values). The R channel is stored at the lowest memory address followed by G, B then A channels. If you’re using iOS then, this is the same as kCVPixelFormatType_32BGRA. Here is how the pixels are packed:

const int pixel = (A & 0xff) << 24 | (R & 0xff) << 16 | (G & 0xff) << 8 | (B & 0xff);

ULTMRZ_SDK_IMAGE_TYPE_NV12

YUV 4:2:0 image with a plane of 8 bit Y samples followed by an interleaved U/V plane containing 8 bit 2x2 subsampled colour difference samples. More information at https://www.fourcc.org/pixel-format/yuv-nv12/

ULTMRZ_SDK_IMAGE_TYPE_NV21

YUV 4:2:0 image with a plane of 8 bit Y samples followed by an interleaved V/U plane containing 8 bit 2x2 subsampled chroma samples. The same as ULTMRZ_SDK_IMAGE_TYPE_NV12 except the interleave order of U and V is reversed. More information at https://www.fourcc.org/pixel-format/yuv-nv21/

ULTMRZ_SDK_IMAGE_TYPE_YUV420P

These formats are identical to YV12 except that the U and V plane order is reversed. They comprise an NxM Y plane followed by (N/2)x(M/2) U and V planes. This is the format of choice for many software MPEG codecs. More information at https://www.fourcc.org/pixel-format/yuv-i420/

ULTMRZ_SDK_IMAGE_TYPE_YVU420P

Same as ULTMRZ_SDK_IMAGE_TYPE_YUV420P except the order of U and V is reversed. More information at https://www.fourcc.org/pixel-format/yuv-yv12/

ULTMRZ_SDK_IMAGE_TYPE_YUV422P

YUV 4:2:2 image with an NxM Y plane followed by (N/2)x(M) V and U planes.

ULTMRZ_SDK_IMAGE_TYPE_YUV444P

YUV 4:4:4 image with an NxM Y plane followed by NxM V and U planes.

class UltMrzSdkResult

Result returned by the engine at initialization, deInitialization and processing stages.

Public Functions

int code() const

The result code. 0 if success, nonzero otherwise.

const char *phrase() const

Short description for the code.

const char *json() const

The MRZ zones as JSON content string. May be null if no zone found.

const size_t numZones() const

Number of zones in json string. This is a helper function to quickly check whether the result contains zones without parsing the json string.

bool isOK() const

Whether the result is success. true if success, false otherwise.

class UltMrzSdkEngine

The Machine-readable zone/passport (MRZ/MRP) engine.

Public Static Functions

static UltMrzSdkResult init(const char *jsonConfig = nullptr)

Initializes the engine. This function must be the first one to call.

Return

a result

Parameters

static UltMrzSdkResult deInit()

DeInitialize the engine. This function must be the last one to be call. Deallocate all the resources allocated using init function.

Return

a result

static UltMrzSdkResult process(const ULTMRZ_SDK_IMAGE_TYPE imageType, const void *imageData, const size_t imageWidthInSamples, const size_t imageHeightInSamples, const size_t imageStrideInSamples = 0, const int imageExifOrientation = 1)

Performs MRZ detection and recognition operations.

Parameters
  • imageType: The image type.

  • imageData: Pointer to the image data.

  • imageWidthInSamples: Image width in samples.

  • imageHeightInSamples: Image height in samples.

  • imageStrideInSamples: Image stride in samples. Should be zero unless your the data is strided.

  • imageExifOrientation: Image EXIF/JPEG orientation. Must be within [1, 8]. More information at https://www.impulseadventure.com/photo/exif-orientation.html

static UltMrzSdkResult process(const ULTMRZ_SDK_IMAGE_TYPE imageType, const void *yPtr, const void *uPtr, const void *vPtr, const size_t widthInSamples, const size_t heightInSamples, const size_t yStrideInBytes, const size_t uStrideInBytes, const size_t vStrideInBytes, const size_t uvPixelStrideInBytes = 0, const int exifOrientation = 1)

Performs MRZ detection and recognition operations.

Parameters
  • imageType: The image type.

  • yPtr: Pointer to the start of the Y (luma) samples.

  • uPtr: Pointer to the start of the U (chroma) samples.

  • vPtr: Pointer to the start of the V (chroma) samples.

  • widthInSamples: Image width in samples.

  • heightInSamples: Image height in samples.

  • yStrideInBytes: Stride in bytes for the Y (luma) samples.

  • uStrideInBytes: Stride in bytes for the U (chroma) samples.

  • vStrideInBytes: Stride in bytes for the V (chroma) samples.

  • uvPixelStrideInBytes: Pixel stride in bytes for the UV (chroma) samples. Should be 1 for planar and 2 for semi-planar formats. Set to 0 for auto-detect.

  • exifOrientation: Image EXIF/JPEG orientation. Must be within [1, 8]. More information at https://www.impulseadventure.com/photo/exif-orientation.html

static UltMrzSdkResult requestRuntimeLicenseKey(const bool &rawInsteadOfJSON = false)

Build a unique runtime license key associated to this device. You must initialize the engine before calling this function. This function doesn’t require internet connection. The runtime key must be activated to obtain a token. The activation procedure is explained at https://www.doubango.org/SDKs/LicenseManager/docs/Activation_use_cases.html.

Return

a result

Parameters
  • rawInsteadOfJSON: Whether to output the runtime key as raw string intead of JSON entry. Requesting raw string instead of JSON could be helpful for applications without JSON parser to extract the key.