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 B channel is stored at the lowest memory address followed by G, R 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.

ULTMRZ_SDK_IMAGE_TYPE_Y¶

Grayscale image with single channel (luminance only). Each pixel is stored in single byte (8 bit Y samples).

  Available since: 2.1.0

ULTMRZ_SDK_IMAGE_TYPE_BGR24¶

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

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

Available since: 2.3.4

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

jsonConfig: JSON string containing configuration entries. May be null. More info at https://www.doubango.org/SDKs/mrz/docs/Configuration_options.html

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.

Return

a result

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.

Return

a result

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 int exifOrientation(const void *jpegMetaDataPtr, const size_t jpegMetaDataSize)¶

Retrieve EXIF orientation value from JPEG meta-data.

Available since: 2.9.0

Return

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

Parameters

jpegMetaDataPtr: Pointer to the meta-data.
jpegMetaDataSize: Size of the meta-data.

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.