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/ultimateALPR-SDK/blob/master/c++/ultimateALPR-SDK-API-PUBLIC.h

enum ultimateAlprSdk::ULTALPR_SDK_IMAGE_TYPE

Defines the image types.

Values:

ULTALPR_SDK_IMAGE_TYPE_RGB24

Each pixel is stored on 3 bytes. Each channel (R, G, B) is stored with 8 bits of precision (256 possible values). Here is how the pixels are packed:

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

Available since: 2.0.0

ULTALPR_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);

Available since: 2.1.0

ULTALPR_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);

Available since: 2.3.0

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

Available since: 2.0.0

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

Available since: 2.0.0

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

Available since: 2.0.0

ULTALPR_SDK_IMAGE_TYPE_YVU420P

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

Available since: 2.0.0

ULTALPR_SDK_IMAGE_TYPE_YUV422P

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

  Available since: 2.0.0

ULTALPR_SDK_IMAGE_TYPE_YUV444P

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

  Available since: 2.0.0

ULTALPR_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.6.2

ULTALPR_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.8.0

class UltAlprSdkResult

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 license plates as JSON content string. May be null if no plate found.

const size_t numPlates() const

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

const size_t numCars() const

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

Available since: 3.2.0

bool isOK() const

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

class UltAlprSdkEngine

The Automatic Number/License Plate Recognition (ANPR/ALPR) engine.

Public Static Functions

static UltAlprSdkResult init(const char *jsonConfig = nullptr, const UltAlprSdkParallelDeliveryCallback *parallelDeliveryCallback = 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/anpr/docs/Configuration_options.html

• parallelDeliveryCallback: callback function to enable parallel mode. Use null value to use sequential instead of parallel mode. More info at https://www.doubango.org/SDKs/anpr/docs/Parallel_versus_sequential_processing.html.

static UltAlprSdkResult 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 UltAlprSdkResult process(const ULTALPR_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 ANPR detection and recognition operations.

If you’re using OpenCV to capture images from the camera or RTSP stream, the function could be used like this:

VideoCapture cap(....);

while (1) {
    Mat frame;
    cap >> frame;

    if (frame.empty()) {
        break;
    }

    ULTALPR_SDK_ASSERT((result = UltAlprSdkEngine::process(
        ULTALPR_SDK_IMAGE_TYPE_BGR24,
        frame.ptr(),
        frame.size().width,
        frame.size().height
    )).isOK());
}

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. Available since: 2.3.0.

static UltAlprSdkResult process(const ULTALPR_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 ANPR detection and recognition operations.

If you’re using FFmpeg, the function could be used like this:

ULTALPR_SDK_ASSERT((result = UltAlprSdkEngine::process(
    ULTALPR_SDK_IMAGE_TYPE_YUV420P,
    frame->data[0], // Y
    frame->data[1], // U
    frame->data[2], // V
    frame->width, // Width
    frame->height, // Height
    frame->linesize[0], // Y-stride
    frame->linesize[1], // U-stride
    frame->linesize[2] // V-stride
)).isOK());

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. Available since: 2.3.0.

static int exifOrientation(const void *jpegMetaDataPtr, const size_t jpegMetaDataSize)

Retrieve EXIF orientation value from JPEG meta-data.

Available since: 3.4.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 UltAlprSdkResult 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.