跨模态分类算法

---

REVISION HISTORY

Revision No.	Description	Date
1.0	First version	10/31/2023

---

1. 算法说明

跨模态分类算法（Open Vocabulary Classification, Ovcls），对文本模态和图像模态进行匹配，可以用于以文搜图或者以图搜文。

2. API参考

该功能模块提供以下API:

API名称	功能
ALGO_OVCLS_CreateHandle	创建句柄
ALGO_OVCLS_InitHandle	初始化句柄
ALGO_OVCLS_GetInputAttr	获取模型的属性信息
ALGO_OVCLS_SetThreshold	设置阈值
ALGO_OVCLS_CreateImageDatabase	创建图像数据库
ALGO_OVCLS_CreateTextDatabase	创建文本数据库
ALGO_OVCLS_AddImageToDatabase	添加图像到数据库
ALGO_OVCLS_AddTextToDatabase	添加文本到数据库
ALGO_OVCLS_SaveImageDatabase	保存图像数据库
ALGO_OVCLS_SaveTextDatabase	保存文本数据库
ALGO_OVCLS_SearchTextByImage	以图搜文
ALGO_OVCLS_SearchImageByText	以文搜图
ALGO_OVCLS_DeInitHandle	反初始化句柄
ALGO_OVCLS_ReleaseHandle	删除句柄

2.1. ALGO_OVCLS_CreateHandle

• 功能

  创建句柄

• 语法

  MI_S32 ALGO_OVCLS_CreateHandle (void** handle);
  

• 形参

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

• 返回值

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

• 依赖

  • 头文件：sstar_ovcls_api.h

  • 库文件：libsstaralgo_ovcls.a/libsstaralgo_ovcls.so

2.2. ALGO_OVCLS_InitHandle

• 功能

  初始化句柄

• 语法

  MI_S32 ALGO_OVCLS_InitHandle (void* handle, lipOvclsInitInfo_t* init_info);
  

• 形参

  参数名称	描述	输入/输出
  handle	句柄	输入
  init_info	配置ipu_firmware_path路径、模型文件夹路径、阈值	输入

• 返回值

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

• 依赖

  • 头文件：sstar_ovcls_api.h

  • 库文件：libsstaralgo_ovcls.a/libsstaralgo_ovcls.so

2.3. ALGO_OVCLS_GetInputAttr

• 功能

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

• 语法

  MI_S32 ALGO_OVCLS_GetInputAttr (void* handle, OvclsOvclsInputAttr_t* init_info);
  

• 形参

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

• 返回值

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

• 依赖

  • 头文件：sstar_ovcls_api.h

  • 库文件：libsstaralgo_ovcls.a/libsstaralgo_ovcls.so

2.4. ALGO_OVCLS_SetThreshold

• 功能

  设置阈值

• 语法

  MI_S32 ALGO_OVCLS_SetThreshold (void* handle, MI_FLOAT threshold);
  

• 形参

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

• 返回值

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

• 依赖

  • 头文件：sstar_ovcls_api.h

  • 库文件：libsstaralgo_ovcls.a/libsstaralgo_ovcls.so

2.5. ALGO_OVCLS_CreateImageDatabase

• 功能

  创建图像数据库

• 语法

  MI_S32 ALGO_OVCLS_CreateImageDatabase(void* handle, int img_num, char* img_database_path, char *img_label_path);
  

• 形参

  参数名称	描述	输入/输出
  handle	句柄	输入
  img_num	数据库图像数目	输入
  img_database_path	图像数据库地址，如果此变量不为NULL，则加载img_database_path对应数据库	输入
  img_label_path	图像标签路径，如果此变量不为NULL，则加载img_database_path对应标签	输入

• 返回值

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

• 依赖

  • 头文件：sstar_ovcls_api.h

  • 库文件：libsstaralgo_ovcls.a/libsstaralgo_ovcls.so

2.6. ALGO_OVCLS_CreateTextDatabase

• 功能

  创建文本数据库

• 语法

  MI_S32 ALGO_OVCLS_CreateTextDatabase(void* handle, int text_num, char* text_database_path, char *text_label_path);
  

• 形参

  参数名称	描述	输入/输出
  handle	句柄	输入
  text_num	数据库图像数目	输入
  text_database_path	图像数据库地址，如果此变量不为NULL，则加载text_database_path对应数据库	输入
  text_label_path	图像标签路径，如果此变量不为NULL，则加载text_label_path对应标签	输入

• 返回值

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

• 依赖

  • 头文件：sstar_ovcls_api.h

  • 库文件：libsstaralgo_ovcls.a/libsstaralgo_ovcls.so

2.7. ALGO_OVCLS_AddImageToDatabase

• 功能

  添加图像到数据库

• 语法

  MI_S32 ALGO_OVCLS_AddImageToDatabase(void* handle, const OvclsAlgo_Input_t *img_input, const char *img_str);
  

• 形参

  参数名称	描述	输入/输出
  handle	句柄	输入
  img_input	图像输入结构体	输入
  img_str	图像地址	输入

• 返回值

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

• 依赖

  • 头文件：sstar_ovcls_api.h

  • 库文件：libsstaralgo_ovcls.a/libsstaralgo_ovcls.so

2.8. ALGO_OVCLS_AddTextToDatabase

• 功能

  添加文本到数据库

• 语法

  MI_S32 ALGO_OVCLS_AddTextToDatabase(void* handle, const char *promopt_text, int language_type);
  

• 形参

  参数名称	描述	输入/输出
  handle	句柄	输入
  promopt_text	文本	输入
  language_type	语种，0表示中文，1表示英文	输入

• 返回值

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

• 依赖

  • 头文件：sstar_ovcls_api.h

  • 库文件：libsstaralgo_ovcls.a/libsstaralgo_ovcls.so

2.9. ALGO_OVCLS_SaveImageDatabase

• 功能

  保存图像数据库

• 语法

  MI_S32 ALGO_OVCLS_SaveImageDatabase(void* handle, char* img_database_path, char *img_label_path);
  

• 形参

  参数名称	描述	输入/输出
  handle	句柄	输入
  img_database_path	图像数据库地址	输入
  img_label_path	图像标签地址	输入

• 返回值

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

• 依赖

  • 头文件：sstar_ovcls_api.h

  • 库文件：libsstaralgo_ovcls.a/libsstaralgo_ovcls.so

2.10. ALGO_OVCLS_SaveTextDatabase

• 功能

  保存文本数据库

• 语法

  MI_S32 ALGO_OVCLS_SaveTextDatabase(void* handle, char* text_database_path, char *text_label_path);
  

• 形参

  参数名称	描述	输入/输出
  handle	句柄	输入
  text_database_path	文本数据库地址	输入
  text_label_path	文本标签地址	输入

• 返回值

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

• 依赖

  • 头文件：sstar_ovcls_api.h

  • 库文件：libsstaralgo_ovcls.a/libsstaralgo_ovcls.so

2.11. ALGO_OVCLS_SearchTextByImage

• 功能

  以图搜文

• 语法

  MI_S32 ALGO_OVCLS_SearchTextByImage(void* handle, const OvclsAlgo_Input_t *img_input, int language_type, OvclsOutputInfo_t *results);
  

• 形参

  参数名称	描述	输入/输出
  handle	句柄	输入
  img_input	图像输入结构体	输入
  language_type	语种，0表示中文，1表示英文	输入
  results	搜索结果	输出

• 返回值

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

• 依赖

  • 头文件：sstar_ovcls_api.h

  • 库文件：libsstaralgo_ovcls.a/libsstaralgo_ovcls.so

2.12. ALGO_OVCLS_SearchImageByText

• 功能

  以图搜文

• 语法

  MI_S32 ALGO_OVCLS_SearchImageByText(void* handle, const char *promopt_text, int language_type, OvclsOutputInfo_t *results);
  

• 形参

  参数名称	描述	输入/输出
  handle	句柄	输入
  promopt_text	文本	输入
  language_type	语种，0表示中文，1表示英文	输入
  results	结果	输入

• 返回值

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

• 依赖

  • 头文件：sstar_ovcls_api.h

  • 库文件：libsstaralgo_ovcls.a/libsstaralgo_ovcls.so

2.13. ALGO_OVCLS_DeInitHandle

• 功能

  反初始化句柄

• 语法

  MI_S32 ALGO_OVCLS_DeInitHandle (void* handle);
  

• 形参

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

• 返回值

  返回值	描述
  0	成功

• 依赖

  • 头文件：sstar_ovcls_api.h

  • 库文件：libsstaralgo_ovcls.a/libsstaralgo_ovcls.so

2.14. ALGO_OVCLS_ReleaseHandle

• 功能

  删除句柄

• 语法

  MI_S32 ALGO_OVCLS_ReleaseHandle (void* handle);
  

• 形参

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

• 返回值

  返回值	描述
  0	成功

• 依赖

  • 头文件：sstar_ovcls_api.h

  • 库文件：libsstaralgo_ovcls.a/libsstaralgo_ovcls.so

3. 数据类型

Ovcls相关数据类型定义如下：

数据类型	定义
OvclsInputAttr_t	算法输入属性结构体
OvclsOutputInfo_t	算法输出结构体
OvclsInitInfo_t	算法初始化相关结构体
OvclsAlgo_Input_t	算法输入相关结构体

3.1 OvclsInputAttr_t

• 说明

  算法输入属性结构体

• 定义

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

• 成员

  成员名称	描述
  width	模型输入数据的宽
  height	模型输入数据的高
  format	模型输入数据的类型

• 相关数据类型及接口

  ALGO_OVCLS_GetInputAttr

3.2 OvclsOutputInfo_t

• 说明

  算法输出结构体

• 定义

  typedef struct{
      MI_U32    class_id;
      MI_FLOAT  score;
      char string[OVCLS_MAX_STRLEN];
  }OvclsOutputInfo_t;
  

• 成员

  成员名称	描述
  class_id	类别
  score	目标的分值
  string	结果对应标签

• 相关数据类型及接口

  ALGO_OVCLS_SearchTextByImage

  ALGO_OVCLS_SearchImageByText

3.3 OvclsInitInfo_t

• 说明

  算法初始化相关结构体

• 定义

  typedef struct{
      MI_U32 language;
      char ipu_firmware_path[OVCLS_MAX_STRLEN];
      char img_model_path[OVCLS_MAX_STRLEN];
      char text_model_path[OVCLS_MAX_STRLEN];
      char vocab_path[OVCLS_MAX_STRLEN];
  }OvclsInitInfo_t;
  

• 成员

  成员名称	描述
  language	语种
  ipu_firmware_path	ipu_firmware_path路径
  img_model_path	图像模型路径
  text_model_path	文本模型路径
  vocab_path	字典路径

• 相关数据类型及接口

  ALGO_OVCLS_InitHandle

3.4 OvclsAlgo_Input_t

• 说明

  算法输入相关结构体

• 定义

  typedef struct{
      void*  p_vir_addr;
      MI_PHY phy_addr;
      MI_U32 buf_size;
  }OvclsAlgo_Input_t;
  

• 成员

  成员名称	描述
  p_vir_addr	输入buffer的虚拟地址
  phy_addr	输入buffer的物理地址
  buf_size	输入buffer的长度

• 相关数据类型及接口

  ALGO_OVCLS_Run

4. 错误码

错误码	数值	描述
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	无效的算法输出数据维度