License Plate Recognition Algorithm

REVISION HISTORY

Revision No.
Description
 Date
1.0
  • First version
    		•  03/05/2025

    1. General Description

    1.1. Algorithm Description

    License Plate Recognition(LPR) includes the following functions: license plate detection, license plate number recognition, license plate color recognition, license plate type recognition. The models used are described as follows:

    • license plate detection model (lpr_det48y.img), outputs two label, i.e. single-line plate(class_id=0), double-line plate(class_id=1);

    • license plate number recognition model (lpr_rec_s.img/lpr_rec_l.img) outputs license plate number;

    • license plate color recognition model (lpr_cls.img)outputs five labels, i.e. blue(class_id=0), green(class_id=1), yellow(class_id=2), white(class_id=3), black(class_id=4);

    2. API Reference

    This function module provides the following APIs:

    API Name Function
    ALGO_LPR_CreateHandle Create handle
    ALGO_LPR_InitHandle Initialize handle
    ALGO_LPR_GetInputAttr Get model attribute information
    ALGO_LPR_SetParams Set configurable parameters
    ALGO_LPR_Detect Run license plate detection
    ALGO_LPR_Recognize Run license plate recognize on detected plates
    ALGO_LPR_DeInitHandle Deinitialize algorithm
    ALGO_LPR_ReleaseHandle Release handle

    2.1. ALGO_LPR_CreateHandle

    • Function

      Create handle

    • Syntax

      MI_S32 ALGO_LPR_CreateHandle(void **handle);

    • Parameter

      Parameter Name Description Input/Output
      handle Handle Input

    • Return Value

      Return Value Description
      0 Successful.
      Other Failed, see Error Code for details

    • Dependency

      • Header file: sgs_lpr_api.h

      • Library file: libsgsalgo_lpr.a/libsgsalgo_lpr.so

    2.2. ALGO_LPR_InitHandle

    • Function

      Initialize handle

    • Syntax

      MI_S32 ALGO_LPR_InitHandle(void *handle, LprInitInfo_t *lpr_init_info);

    • Parameter

      Parameter Name Description Input/Output
      handle Handle Input
      lpr_init_info Set ipu_firmware_path path, model file paths, thresholds Input

    • Return Value

      Return Value Description
      0 Successful.
      Other Failed, see Error Code for details

    • Dependency

      • Header file: sgs_lpr_api.h

      • Library file: libsgsalgo_lpr.a/libsgsalgo_lpr.so

    2.3. ALGO_LPR_GetInputAttr

    • Function

      Get model attribute information, including model input resolution and input data type

    • Syntax

      MI_S32 ALGO_LPR_GetInputAttr(void *handle, LprInputAttr_t *input_attr);

    • Parameter

      Parameter Name Description Input/Output
      handle Handle Input
      input_attr input_attr Output

    • Return Value

      Return Value Description
      0 Successful.
      Other Failed, see Error Code for details

    • Dependency

      • Header file: sgs_lpr_api.h

      • Library file: libsgsalgo_lpr.a/libsgsalgo_lpr.so

    2.4. ALGO_LPR_SetParams

    • Function

      Set configurable parameters

    • Syntax

      MI_S32 ALGO_LPR_SetParams(void *handle, const LprParams_t *params);

    • Parameter

      Parameter Name Description Input/Output
      handle Handle Input
      params Configurable parameters Input

    • Return Value

      Return Value Description
      0 Successful.
      Other Failed, see Error Code for details

    • Dependency

      • Header file: sgs_lpr_api.h

      • Library file: libsgsalgo_lpr.a/libsgsalgo_lpr.so

    2.5. ALGO_LPR_Detect

    • Function

      Run license plate detection

    • Syntax

      MI_S32 ALGO_LPR_Detect(void *handle, const LprInput_t *algo_input, LprResult_t lp_result[MAX_LPR_OBJECT], MI_S32 *lp_num);

    • Parameter

      Parameter Name Description Input/Output
      handle Handle Input
      algo_input Input image buffer information Input
      lp_result The information of license plate Output
      lp_num The number of license plates Output

    • Return Value

      Return Value Description
      0 Successful.
      Other Failed, see Error Code for details

    • Dependency

      • Header file: sgs_lpr_api.h

      • Library file: libsgsalgo_lpr.a/libsgsalgo_lpr.so

    2.6. ALGO_LPR_Recognize

    • Function

      Run license plate information recognition

    • Syntax

      MI_S32 ALGO_LPR_Recognize(void *handle, const LprInput_t *algo_input, LprInputAttr_t *input_attr, LprResult_t lp_result[MAX_LPR_OBJECT], MI_S32 *lp_num);

    • Parameter

      Parameter Name Description Input/Output
      handle Handle Input
      algo_input Original image input buffer Input
      input_attr Original image input attributes Input
      lp_result The information of license plate Output
      lp_num The number of license plates Output

    • Return Value

      Return Value Description
      0 Successful.
      Other Failed, see Error Code for details

    • Dependency

      • Header file: sgs_lpr_api.h

      • Library file: libsgsalgo_lpr.a/libsgsalgo_lpr.so

    2.7. ALGO_LPR_DeInitHandle

    • Function

      Deinitialize algorithm

    • Syntax

      MI_S32 ALGO_LPR_DeinitHandle(void *handle);

    • Parameter

      Parameter Name Description Input/Output
      handle Handle Input

    • Return Value

      Return Value Description
      0 Successful.

    • Dependency

      • Header file: sgs_lpr_api.h

      • Library file: libsgsalgo_lpr.a/libsgsalgo_lpr.so

    2.8. ALGO_LPR_ReleaseHandle

    • Function

      Release handle

    • Syntax

      MI_S32 ALGO_LPR_ReleaseHandle(void *handle);

    • Parameter

      Parameter Name Description Input/Output
      handle Handle Input

    • Return Value

      Return Value Description
      0 Successful.

    • Dependency

      • Header file: sgs_lpr_api.h

      • Library file: libsgsalgo_lpr.a/libsgsalgo_lpr.so

    3. Structure Type

    The detection related data types are defined as follows:

    Data Type Definition
    LprInitInfo_t Algorithm initial parameter structure
    LprInputAttr_t Algorithm input attribute structure
    LprParams_t Algorithm configurable parameter structure
    LprInput_t Algorithm input structure
    LprBox_t Algorithm detection box structure
    LprQuality_t Algorithm license plate quality structure
    LpColor_e License plate color enumeration variables
    LpType_e License plate type enumeration variables
    LprInfo_t License plate information structure
    LprResult_t License plate result structure

    3.1 LprInitInfo_t

    • Description

      Algorithm initial parameter structure

    • Definition

      typedef struct
{
    char ipu_firmware_path[MAX_LPR_STRLEN];
    char det_model[MAX_LPR_STRLEN];
    char rec_model[MAX_LPR_STRLEN];
    char cls_model[MAX_LPR_STRLEN];

    MI_BOOL create_device;
    MI_BOOL destroy_device;
} LprInitInfo_t;

    • Member

      Member Name Description
      ipu_firmware_path Ipu firmware path
      det_model License plate detection model path
      rec_model License plate number recognition model path
      cls_model License plate color recognition model path
      create_device Whether to create IPU device in algorithm, default is true; You can set false when create IPU device outside
      destroy_device Whether to destroy IPU device in algorithm, default is true; You can set false when destroy IPU device outside

    • Related data type and interface

      ALGO_LPR_InitHandle

    3.2 LprInputAttr_t

    • Description

      Algorithm input attribute structure

    • Definition

      typedef struct
{
    MI_U32 width;
    MI_U32 height;
    MI_IPU_ELEMENT_FORMAT format;
}LprInputAttr_t;

    • Member

      Member Name Description
      width Model input data width
      height Model input data height
      format Model input pixel format

    • Related data type and interface

      ALGO_LPR_GetInputAttr

    3.3 LprParams_t

    • Description

      Algorithm configurable parameter structure

    • Definition

      typedef struct
{
    MI_S32 disp_width;
    MI_S32 disp_height;

    MI_FLOAT det_threshold;
    MI_FLOAT rec_threshold;
    MI_FLOAT cls_threshold;

    MI_FLOAT quality_threshold;
    MI_FLOAT horizon_angle_threshold;
    MI_FLOAT vertical_angle_threshold;
    MI_FLOAT plate_area_threshold;
    MI_FLOAT keypoints_distance_threshold;
}LprParams_t;

    • Member

      Member Name Description
      disp_width Display width (used for mapping the location of detection boxes), default is 1920
      disp_height Display height (used for mapping the location of detection boxes), default is 1080
      det_threshold License plate detecton threshold
      rec_threshold License plate number recognition threshold
      color_threshold License plate color recognition threshold
      quality_threshold License plate quality threshold
      horizon_angle_threshold License plate horizon angle threshold
      vertical_angle_threshold License plate vertical angle threshold
      plate_area_threshold License plate area threshold
      keypoints_distance_threshold License plate keypoint distance threshold

    • Related data type and interface

      ALGO_LPR_SetParams

    3.4 LprInput_t

    • Description

      Algorithm input structure

    • Definition

      typedef struct
{
    void *p_vir_addr;
    MI_PHY phy_addr;
    MI_U32 buf_size;
    MI_U64 pts;
    MI_U16 width;
    MI_U16 height;
    MI_BOOL filter;
} LprInput_t;

    • Member

      Member Name Description
      p_vir_addr Input buffer virtual address
      phy_addr Input buffer physical address
      buf_size Input buffer size
      pts Input buffer timestamp
      width Input buffer width
      height Input buffer height
      filter Whether to filer license plates by quality

    • Related data type and interface

      ALGO_LPR_Detect

      ALGO_LPR_Recognize

    3.5 LprBox_t

    • Description

      Algorithm detection box structure

    • Definition

      typedef struct
{
    MI_U32 x;
    MI_U32 y;
    MI_U32 width;
    MI_U32 height;
    MI_S32 cls;
    MI_FLOAT det_score;
    MI_U64 pts;
    MI_FLOAT keypts[NUM_LPR_KEYPOINTS][2];
    MI_U64 track_id;
} LprBox_t;

    • Member

      Member Name Description
      x, y, width, height Detection result box position
      class_id Detection result box class ID
      score Detection result box score
      pts Timestamp of the incoming detection frame
      keypts License plate keypoints
      track_id License plate keypoints

    • Related data type and interface

      LprResult_t

    3.6 LprQuality_t

    • Description

      Algorithm license plate quality structure

    • Definition

      typedef struct
{
    MI_FLOAT quality_score;
    MI_FLOAT horizon_angle;
    MI_FLOAT vertical_angle;
    MI_FLOAT plate_area;
    MI_FLOAT keypoints_distance;
} LprQuality_t;

    • Member

      Member Name Description
      quality_score License plate quality
      horizon_angle License plate horizon angle
      vertical_angle License plate vertical angle
      plate_area License plate area
      keypoints_distance License plate keypoints distance

    • Related data type and interface

      ALGO_LPR_Detect

    3.7 LpColor_e

    • Description

      License plate color enumeration variables

    • Definition

      typedef enum
{
    LP_COLOR_BLUE=0,
    LP_COLOR_GREEN,
    LP_COLOR_YELLOW,
    LP_COLOR_WHITE,
    LP_COLOR_BLACK
}LpColor_e;

    • Member

      Member Name Description
      LP_COLOR_BLUE Blue license plate
      LP_COLOR_GREEN Green license plate
      LP_COLOR_YELLOW Yellow license plate
      LP_COLOR_WHITE White license plate
      LP_COLOR_BLACK Black license plate

    • Related data type and interface

      LprResult_t

    3.8 LpType_e

    • Description

      License plate type enumeration variables

    • Definition

      typedef enum
{
    LP_TYPE_NORM=0,
    LP_TYPE_POLICE,
    LP_TYPE_ARMY,
    LP_TYPE_HONGKONG,
    LP_TYPE_MACAO,
    LP_TYPE_EMBASSY
}LpType_e;

    • Member

      Member Name Description
      LP_TYPE_NORM Normal license plate
      LP_TYPE_POLICE Police license plate
      LP_TYPE_ARMY Army license plate
      LP_TYPE_HONGKONG Hong kong license plate
      LP_TYPE_MACAO MACAO license plate
      LP_TYPE_EMBASSY Embassy license plate

    • Related data type and interface

      LprResult_t

    3.9 LprInfo_t

    • Description

      License plate information structure

    • Definition

      typedef struct
{
    MI_FLOAT rec_score;
    char lp_number[MAX_LP_RESULT_LEN];
    MI_FLOAT cls_score;
    LpColor_e lp_color;
    LpType_e lp_type;
} LprInfo_t;

    • Member

      Member Name Description
      rec_score License plate number recognition score
      lp_number License plate number
      cls_score License plate color recognition score
      lp_color License plate color
      lp_type License plate type

    • Related data type and interface

      LprResult_t

    3.10 LprResult_t

    • Description

      License plate number recognition result structure

    • Definition

      typedef struct
{
    LprBox_t box;
    LprQuality_t quality;
    LprInfo_t info;
}LprResult_t;

    • Member

      Member Name Description
      LprBox_t License plate detection structure
      LprQuality_t License plate quality structure
      LprInfo_t License plate information structure

    • Related data type and interface

      ALGO_LPR_Detect

      ALGO_LPR_Recognize

    4. Error code

    Error Code Value Description
    E_ALGO_SUCCESS 0 Operation successful
    E_ALGO_HANDLE_NULL 1 Algorithm handle is null
    E_ALGO_INVALID_PARAM 2 Invalid input parameter
    E_ALGO_DEVICE_FAULT 3 Hardware error
    E_ALGO_LOADMODEL_FAIL 4 Failed to load model
    E_ALGO_INIT_FAIL 5 Algorithm initialization failed
    E_ALGO_NOT_INIT 6 Algorithm not initialized
    E_ALGO_INPUT_DATA_NULL 7 Algorithm input data is null
    E_ALGO_INVALID_INPUT_SIZE 8 Invalid algorithm input data dimension
    E_ALGO_INVALID_LICENSE 9 Invalid license
    E_ALGO_MEMORY_OUT 10 Out of memory
    E_ALGO_FILEIO_ERROR 11 File read and write operation error
    E_ALGO_INVALID_OUTPUT_SIZE 12 Invalid algorithm output data dimension
    E_ALGO_INVALID_DECODE_MODE 13 Invalid decode mode
    E_ALGO_MODEL_INVOKE_ERROR 14 Invoke fail