Retrieval以文搜图算法说明

REVISION HISTORY

Revision No. Description Date
1.0 First version 07/03/2024

1. 概述

1.1. 算法说明

以文搜图(Retrieval, Ret)可以实现使用文本对图像内容进行检索的功能,可以配合检测+跟踪算法实现对检测目标的属性进行搜索的能力。

1.2. 算法规格

  • 379G板端指标

    Model ElementFormat Resolution Rom Ram InferenceTime
    ret_img_224a.img argb8888 224*224 38,691KB 39,639KB 9.975ms
    ret_txt_52.img int16 1x52 58,487KB 58,491KB 5.158ms

  • 377板端指标

    Model ElementFormat Resolution Rom Ram InferenceTime
    ret_img_224a.img argb8888 224*224 39,287KB 41,359KB 40.052ms
    ret_txt_52.img int16 1x52 56,685KB 59,177KB 16.422ms

2. API参考

该功能模块提供以下API:

API名称 功能
ALGO_RET_CreateHandle 创建句柄
ALGO_RET_InitHandle 初始化句柄
ALGO_RET_GetInputAttr 获取模型的属性信息
ALGO_RET_SetParams 设置算法可配置参数
ALGO_RET_LoadDb 加载之前保存的检索数据库文件
ALGO_RET_GetCurrentDbSize 获取当前数据库的目标数
ALGO_RET_AddBoxToDb 往数据库中添加检索目标
ALGO_RET_SearchDb 按照输入文本对数据进行检索
ALGO_RET_SaveDb 将数据库导出为文件
ALGO_RET_ClearDb 清空数据库
ALGO_RET_DeInitHandle 反初始化句柄
ALGO_RET_ReleaseHandle 删除句柄

2.1. ALGO_RET_CreateHandle

  • 功能

    创建句柄

  • 语法

    MI_S32 ALGO_RET_CreateHandle(void **handle);

  • 形参

    参数名称 描述 输入/输出
    handle 句柄 输入

  • 返回值

    返回值 描述
    0 成功
    其他 错误码

  • 依赖

    • 头文件: sgs_ret_api.h

    • 库文件: libsgsalgo_ret.a/libsgsalgo_ret.so

2.2. ALGO_RET_InitHandle

  • 功能

    初始化句柄

  • 语法

    MI_S32 ALGO_RET_InitHandle(void *handle, const RetInit_t *init);

  • 形参

    参数名称 描述 输入/输出
    handle 句柄 输入
    init 配置ipu_firmware_path路径、模型路径等初始化参数 输入

  • 返回值

    返回值 描述
    0 成功
    其他 错误码

  • 依赖

    • 头文件: sgs_ret_api.h

    • 库文件: libsgsalgo_ret.a/libsgsalgo_ret.so

2.3. ALGO_RET_GetInputAttr

  • 功能

    获取模型的属性信息,包括模型输入分辨率以及输入数据的类型

  • 语法

    MI_S32 ALGO_RET_GetInputAttr(void *handle, RetInputAttr_t *ret_input_attr);

  • 形参

    参数名称 描述 输入/输出
    handle 句柄 输入
    ret_input_attr 输入属性 输出

  • 返回值

    返回值 描述
    0 成功
    其他 错误码

  • 依赖

    • 头文件: sgs_ret_api.h

    • 库文件: libsgsalgo_ret.a/libsgsalgo_ret.so

2.4. ALGO_RET_SetParams

  • 功能

    设置算法的可配置参数

  • 语法

    MI_S32 ALGO_RET_SetParams(void *handle, const RetParams_t *params);

  • 形参

    参数名称 描述 输入/输出
    handle 句柄 输入
    params 参数结构体 输入

  • 返回值

    返回值 描述
    0 成功
    其他 错误码

  • 依赖

    • 头文件: sgs_ret_api.h

    • 库文件: libsgsalgo_ret.a/libsgsalgo_ret.so

2.5. ALGO_RET_LoadDb

  • 功能

    加载之前保存的检索数据库文件

  • 语法

    MI_S32 ALGO_RET_LoadDb(void *handle, const char *img_db_path, const char *box_db_path);

  • 形参

    参数名称 描述 输入/输出
    handle 句柄 输入
    img_db_path 图像数据库文件 输入
    box_db_path box数据库文件 输入

  • 返回值

    返回值 描述
    0 成功
    其他 错误码

  • 依赖

    • 头文件: sgs_ret_api.h

    • 库文件: libsgsalgo_ret.a/libsgsalgo_ret.so

2.6. ALGO_RET_GetCurrentDbSize

  • 功能

    获取当前数据库的目标数

  • 语法

    MI_S32 ALGO_RET_GetCurrentDbSize(void *handle, MI_U32 *db_size);

  • 形参

    参数名称 描述 输入/输出
    handle 句柄 输入
    db_size 数据库包含的目标数 输出

  • 返回值

    返回值 描述
    0 成功
    其他 错误码

  • 依赖

    • 头文件: sgs_ret_api.h

    • 库文件: libsgsalgo_ret.a/libsgsalgo_ret.so

2.7. ALGO_RET_AddBoxToDb

  • 功能

    往数据库中添加检索目标

  • 语法

    MI_S32 ALGO_RET_AddBoxToDb(void *handle, const RetImage_t *image, const RetBox_t *box);

  • 形参

    参数名称 描述 输入/输出
    handle 句柄 输入
    image 检索目标的图像buffer 输入
    box 检索目标框信息 输入

  • 返回值

    返回值 描述
    0 成功
    其他 错误码

  • 依赖

    • 头文件: sgs_ret_api.h

    • 库文件: libsgsalgo_ret.a/libsgsalgo_ret.so

2.8. ALGO_RET_SearchDb

  • 功能

    按照输入文本对数据进行检索

  • 语法

    MI_S32 ALGO_RET_SearchDb(void *handle, const char *search_text, RetBox_t results    [MAX_RET_SEARCH_RESULTS], MI_S32 *num_results);

  • 形参

    参数名称 描述 输入/输出
    handle 句柄 输入
    search_text 搜索文本 输入
    results 检索结果的目标框信息 输出
    num_results 检索结果的个数 输出

  • 返回值

    返回值 描述
    0 成功
    其他 错误码

  • 依赖

    • 头文件: sgs_ret_api.h

    • 库文件: libsgsalgo_ret.a/libsgsalgo_ret.so

2.9. ALGO_RET_SaveDb

  • 功能

    将数据库导出为文件

  • 语法

    MI_S32 ALGO_RET_SaveDb(void *handle, const char *img_db_path, const char *box_db_path);

  • 形参

    参数名称 描述 输入/输出
    handle 句柄 输入
    img_db_path 图像数据库文件路径 输入
    box_db_path 目标框数据库文件路径 输入

  • 返回值

    返回值 描述
    0 成功
    其他 错误码

  • 依赖

    • 头文件: sgs_ret_api.h

    • 库文件: libsgsalgo_ret.a/libsgsalgo_ret.so

2.10. ALGO_RET_ClearDb

  • 功能

    清空数据库

  • 语法

    MI_S32 ALGO_RET_ClearDb(void *handle);

  • 形参

    参数名称 描述 输入/输出
    handle 句柄 输入

  • 返回值

    返回值 描述
    0 成功
    其他 错误码

  • 依赖

    • 头文件: sgs_ret_api.h

    • 库文件: libsgsalgo_ret.a/libsgsalgo_ret.so

2.11. ALGO_RET_DeInitHandle

  • 功能

    反初始化句柄

  • 语法

    MI_S32 ALGO_RET_DeinitHandle(void *handle);

  • 形参

    参数名称 描述 输入/输出
    handle 句柄 输入

  • 返回值

    返回值 描述
    0 成功

  • 依赖

    • 头文件: sgs_ret_api.h

    • 库文件: libsgsalgo_ret.a/libsgsalgo_ret.so

2.12. ALGO_RET_ReleaseHandle

  • 功能

    删除句柄

  • 语法

    MI_S32 ALGO_RET_ReleaseHandle(void *handle);

  • 形参

    参数名称 描述 输入/输出
    handle 句柄 输入

  • 返回值

    返回值 描述
    0 成功

  • 依赖

    • 头文件: sgs_ret_api.h

    • 库文件: libsgsalgo_ret.a/libsgsalgo_ret.so

3. 结构体说明

算法相关数据类型定义如下:

数据类型 定义
RetInit_t 算法初始化信息性结构体
RetParams_t 算法可配置参数结构体
RetInputAttr_t 算法输入属性相关结构体
RetImage_t 图像buffer输入结构体
RetBox_t 目标框信息结构体

3.1 RetInit_t

  • 说明

    算法初始化信息结构体

  • 定义

    typedef struct
{
    char ipu_firmware_path[MAX_RET_STRLEN]; // ipu_firmware.bin path
    char img_model_path[MAX_RET_STRLEN];    // image model path
    char txt_model_path[MAX_RET_STRLEN];    // text model path
    MI_BOOL create_device;                  // set false to create ipu device outside algo lib
    MI_BOOL destroy_device;                 // set false to destroy ipu device outside algo lib
    void *img_model_buffer;                 // set it when load image model from memory
    MI_U32 img_model_buffer_len;            // set it when load image model from memory
    void *txt_model_buffer;                 // set it when load text  model from memory
    MI_U32 txt_model_buffer_len;            // set it when load text  model from memory
    MI_U32 max_db_size;                     // set max size of image/text database default = 30,000
    char vocab_path[MAX_RET_STRLEN];        // vocab path
    RetLanguage_e language;                 // text language type; default = E_RET_EN
    MI_BOOL low_memory_mode;                // keep only one model in memory at the same time to save memory, default = false
} RetInit_t;

  • 成员

    成员名称 描述
    ipu_firmware_bin ipu_firmware_path路径
    img_model_path 图像模型路径
    txt_model_path 文本模型路径
    create_device 设置是否算法库内创建IPU_Device, 默认为false
    destroy_device 设置是否算法库内销毁IPU_Device, 默认为false
    img_model_buffer 图像模型内存buffer(仅当从内存buffer形式加载图像模型时使用)
    img_model_buffer_len 图像模型内存buffer长度 (仅当从内存buffer形式加载图像模型时使用)
    txt_model_buffer 文本模型内存buffer(仅当从内存buffer形式加载文本模型时使用)
    txt_model_buffer_len 文本模型内存buffer长度 (仅当从内存buffer形式加载文本模型时使用)
    max_db_size 数据库最大可包含的目标数(超过时会自动顶掉最早的目标)
    vocab_path 文本模型的字典txt文件
    language 检索文本的语言
    low_memory_mode 低内存模式,设置为true为打开,默认为false

  • 相关数据类型及接口

    ALGO_RET_InitHandle

3.2 RetParams_t

  • 说明

    算法可配置参数结构体

  • 定义

    typedef struct
{
    MI_U32 search_top_k;              // return topk of search, result; range from 0 to MAX_RET_SEARCH_RESULTS, default 10
    MI_BOOL update_existed_track_id;  // set true to update box with track_id already existed in db; default false
    MI_BOOL allow_duplicate_track_id; // set true to allow multi boxes with same track_id co-exist in db; default false
} RetParams_t;

  • 成员

    成员名称 描述
    search_top_k 检索结果后取最匹配的k个结果,默认为10
    update_existed_track_id 是否使用后输入的同track_id的目标更新数据库,默认为false,即忽略后输入的同track_id目标
    allow_duplicate_track_id 允许保留多个同track_id的目标,默认为false,即每个track_id在数据库中保留一个目标

  • 相关数据类型及接口

    ALGO_RET_SetParams

3.3 RetInputAttr_t

  • 说明

    算法输入信息结构体

  • 定义

    typedef struct
{
    MI_U32 image_width;
    MI_U32 image_height;
    MI_U32 image_format;
    MI_U32 max_text_len;
} RetInputAttr_t;

  • 成员

    成员名称 描述
    image_width 图像模型的输入宽度
    image_height 图像模型的输入高度
    image_format 图像模型的输入格式
    max_text_len 文本模型的最大输入长度

  • 相关数据类型及接口

    ALGO_RET_GetInputAttr

3.4 RetImage_t

  • 说明

    图像buffer输入结构体

  • 定义

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

  • 成员

    成员名称 描述
    p_vir_addr 输入buffer的虚拟地址
    phy_addr 输入buffer的物理地址
    buf_size 输入buffer的长度
    pts 输入buffer时间戳
    width 输入buffer的帧宽度
    height 输入buffer的帧高度

  • 相关数据类型及接口

    ALGO_RET_AddBoxToDb

3.5 RetBox_t

  • 说明

    目标框信息结构体

  • 定义

    typedef struct
{
    MI_U32 x;
    MI_U32 y;
    MI_U32 width;
    MI_U32 height;
    MI_U32 class_id;
    MI_FLOAT score;
    MI_U64 pts;
    MI_U64 track_id;
    MI_FLOAT search_score;
    char path[MAX_RET_STRLEN];
} RetBox_t;

  • 成员

    成员名称 描述
    x 目标框左上角坐标
    y 目标框右上角坐标
    width 目标框宽度
    height 目标框高度
    class_id 目标框检测类别
    score 目标框检测score
    pts 目标框所在帧时间戳
    track_id 目标框跟踪ID
    search_score 目标框检索score
    path 输入路径,用于对图片搜索时记录路径,对检测结果进行搜索时不需要设置

  • 相关数据类型及接口

    ALGO_RET_AddBoxToDb

    ALGO_RET_SearchDb

4. 枚举类型说明

RET枚举类型定义如下:

数据类型 定义
RetLanguage_e 检索文本语言枚举类型

4.1 RetLanguage_e

  • 说明

    检索文本语言枚举类型

  • 定义

    typedef enum
{
    E_RET_EN = 0,
    E_RET_CN = 1
} RetLanguage_e;

  • 成员

    成员名称 描述
    E_RET_EN 英文
    E_RET_CN 中文

  • 相关数据类型及接口

    RetInit_t

    ALGO_RET_InitHandle

5. 错误码

错误码 数值 描述
E_ALGO_SUCCESS 0 操作成功
E_ALGO_HANDLE_NULL 1 算法句柄为空
E_ALGO_INVALID_PARAM 2 无效的输入参数
E_ALGO_DEVICE_FAULT 3 硬件错误
E_ALGO_LOADMODEL_FAIL 4 加载模型失败
E_ALGO_INIT_FAIL 5 算法初始化失败
E_ALGO_NOT_INIT 6 算法尚未初始化
E_ALGO_INPUT_DATA_NULL 7 算法输入数据为空
E_ALGO_INVALID_INPUT_SIZE 8 无效的算法输入数据维度
E_ALGO_INVALID_LICENSE 9 无效的license许可
E_ALGO_MEMORY_OUT 10 内存不足
E_ALGO_FILEIO_ERROR 11 文件读写操作错误
E_ALGO_INVALID_OUTPUT_SIZE 12 无效的算法输出数据维度