Re-Identification Algorithm Description

---

REVISION HISTORY

Revision No.	Description	Date
3.0	First version	05/14/2024

---

1. Overview

1.1. Algorithm Description

The Re-Identification algorithm (ReID) includes the following functionalities: pedestrian re-identification and vehicle re-identification.

The main algorithm models are described as follows:

Model	Function	Input Dimensions (w*h)	Input Format
reid_person_12y.img	Pedestrian Re-identification Model	256*128	yuvsp420_nv12
reid_vehicle_22y.img	Vehicle Re-identification Model	256*256	yuvsp420_nv12

2. API Reference

This module provides the following APIs:

API Name	Function
ALGO_REID_CreateHandle	Create Handle
ALGO_REID_InitHandle	Initialize Handle
ALGO_REID_GetInputAttr	Get Model Attribute Info
ALGO_REID_GetFeatureDimension	Get Feature Dimensions
ALGO_REID_SetParams	Set Configurable Algorithm Parameters
ALGO_REID_FeatureExtract	Extract Target Features
ALGO_REID_FeatureCompare	Compare Target Features
ALGO_REID_DeInitHandle	De-initialize Handle
ALGO_REID_ReleaseHandle	Release Handle
ALGO_REID_PersonQuality	Pedestrian Quality Detection
ALGO_REID_CalculateSimilarity	Feature Similarity Detection

2.1. ALGO_REID_CreateHandle

• Function

  Create a Handle

• Syntax

  MI_S32 ALGO_REID_CreateHandle(void **handle);
  

• Parameters

  Parameter Name	Description	Input/Output
  handle	Handle	Input

• Return Value

  Return Value	Description
  0	Success
  Others	Error Codes

• Dependencies

  • Header File: sgs_reid_api.h

  • Library File: libssgsalgo_reid.a/libssgsalgo_reid.so

2.2. ALGO_REID_InitHandle

• Function

  Initialize Handle

• Syntax

  MI_S32 ALGO_REID_InitHandle(void *handle, const ReIdInit_t *init_info);
  

• Parameters

  Parameter Name	Description	Input/Output
  handle	Handle	Input
  init_info	Configuration path for ipu_firmware_path, model directory, etc.	Input

• Return Value

  Return Value	Description
  0	Success
  Others	Error Codes

• Dependencies

  • Header File: sgs_reid_api.h

  • Library File: libssgsalgo_reid.a/libssgsalgo_reid.so

2.3. ALGO_REID_GetInputAttr

• Function

  Get model attribute information, including input resolution and data type

• Syntax

  MI_S32 ALGO_REID_GetInputAttr(void *handle, ReIdInputAttr_t *input_attr);
  

• Parameters

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

• Return Value

  Return Value	Description
  0	Success
  Others	Error Codes

• Dependencies

  • Header File: sgs_reid_api.h

  • Library File: libssgsalgo_reid.a/libssgsalgo_reid.so

2.4. ALGO_REID_GetFeatureDimension

• Function

  Get Feature Dimensions

• Syntax

  MI_S32 ALGO_REID_GetFeatureDimension(void *handle, MI_S32 *feat_dim);
  

• Parameters

  Parameter Name	Description	Input/Output
  handle	Handle	Input
  feat_dim	Feature Dimension	Output

• Return Value

  Return Value	Description
  0	Success
  Others	Error Codes

• Dependencies

  • Header File: sgs_reid_api.h

  • Library File: libssgsalgo_reid.a/libssgsalgo_reid.so

2.5. ALGO_REID_SetParams

• Function

  Set Configurable Parameters for the Algorithm

• Syntax

  MI_S32 ALGO_REID_SetParams(void *handle, const ReIdParams_t *params);
  

• Parameters

  Parameter Name	Description	Input/Output
  handle	Handle	Input
  ReIdParams_t	Parameter Structure	Input

• Return Value

  Return Value	Description
  0	Success
  Others	Error Codes

• Dependencies

  • Header File: sgs_reid_api.h

  • Library File: libssgsalgo_reid.a/libssgsalgo_reid.so

2.6. ALGO_REID_FeatureExtract

• Function

  Target Feature Extraction

• Syntax

  MI_S32 ALGO_REID_FeatureExtract(void *handle, ReIdInput_t *algo_input, MI_FLOAT *feature);
  

• Parameters

  Parameter Name	Description	Input/Output
  handle	Handle	Input
  algo_input	Input Buffer	Input
  feature	Pointer to Output Target Feature Array (array length must match feature dimension)	Output

• Return Value

  Return Value	Description
  0	Success
  Others	Error Codes

• Dependencies

  • Header File: sgs_reid_api.h

  • Library File: libssgsalgo_reid.a/libssgsalgo_reid.so

2.7. ALGO_REID_FeatureCompare

• Function

  Target Feature Comparison

• Syntax

  MI_S32 ALGO_REID_FeatureCompare(void *handle, MI_FLOAT *g_features, MI_FLOAT *q_features, MI_S32 batch, ReIdRes_t results[REID_RESULT_TOP_K], MI_S32 *num_results);
  

• Parameters

  Parameter Name	Description	Input/Output
  handle	Handle	Input
  g_features	Target Features	Input
  q_features	Feature Database	Input
  batch	Number of Database Entries	Input
  results	Comparison Results (sorted by similarity in descending order)	Output
  num_results	Length of Output Comparison Results	Output

• Return Value

  Return Value	Description
  0	Success
  Others	Error Codes

• Dependencies

  • Header File: sgs_reid_api.h

  • Library File: libssgsalgo_reid.a/libssgsalgo_reid.so

2.8. ALGO_REID_DeInitHandle

• Function

  De-initialize Handle

• Syntax

  MI_S32 ALGO_REID_DeInitHandle (void* handle);
  

• Parameters

  Parameter Name	Description	Input/Output
  handle	Handle	Input

• Return Value

  Return Value	Description
  0	Success

• Dependencies

  • Header File: sgs_reid_api.h

  • Library File: libssgsalgo_reid.a/libssgsalgo_reid.so

2.9. ALGO_REID_ReleaseHandle

• Function

  Release Handle

• Syntax

  MI_S32 ALGO_REID_ReleaseHandle (void* handle);
  

• Parameters

  Parameter Name	Description	Input/Output
  handle	Handle	Input

• Return Value

  Return Value	Description
  0	Success

• Dependencies

  • Header File: sgs_reid_api.h

  • Library File: libssgsalgo_reid.a/libssgsalgo_reid.so

2.10. ALGO_REID_PersonQuality

• Function

  Pedestrian Quality Detection

• Syntax

  MI_S32 ALGO_REID_PersonQuality(void *handle, ReIdInput_t *algo_input, PersonQualityOut_t *person_quality_out);
  

• Parameters

  Parameter Name	Description	Input/Output
  handle	Handle	Input
  algo_input	Input Buffer	Input
  person_quality_out	Pedestrian Quality Output Structure	Output

• Return Value

  Return Value	Description
  0	Success

• Dependencies

  • Header File: sgs_reid_api.h

  • Library File: libssgsalgo_reid.a/libssgsalgo_reid.so

2.11. ALGO_REID_CalculateSimilarity

• Function

  Feature Similarity Detection

• Syntax

  MI_S32 ALGO_REID_CalculateSimilarity(void *handle, MI_FLOAT *g_features, MI_FLOAT *q_features, MI_S32 feat_dim, MI_FLOAT *similarity);
  

• Parameters

  Parameter Name	Description	Input/Output
  handle	Handle	Input
  g_features	Features	Input
  q_features	Features	Input
  feat_dim	Feature Dimension	Input
  similarity	Feature Similarity	Output

• Return Value

  Return Value	Description
  0	Success

• Dependencies

  • Header File: sgs_reid_api.h

  • Library File: libssgsalgo_reid.a/libssgsalgo_reid.so

3. Structure Definition

The definitions of REID-related data types are as follows:

Data Type	Definition
ReIdInit_t	Algorithm Initialization Structure
ReIdParams_t	Algorithm Configurable Parameters Structure
ReIdInputAttr_t	Algorithm Input Attributes Structure
AlgoReID_Input_t	Algorithm Input Structure
ReIdRes_t	Algorithm Result Structure
PersonQualityOut_t	Pedestrian Quality Structure

3.1 ReIdInit_t

• Description

  Algorithm Initialization Structure

• Definition

  typedef struct
  {
      char ipu_firmware_path[MAX_REID_STRLEN];
      char model_path[MAX_REID_STRLEN];
      MI_BOOL create_device;
      MI_BOOL destroy_device;
  } ReIdInit_t;
  

• Members

  Member Name	Description
  ipu_firmware_bin	Path to ipu_firmware_path
  model_path	Path to reid Model
  create_device	Set whether to create IPU_Device within the algorithm library, default is false
  destroy_device	Set whether to destroy IPU_Device within the algorithm library, default is false

• Related Data Types and Interfaces

  ALGO_REID_InitHandle

3.2 ReIdParams_t

• Description

  Algorithm Configurable Parameters Structure

• Definition

  typedef struct
  {
      MI_FLOAT threshold;
  } ReIdParams_t;
  

• Members

  Member Name	Description
  threshold	Feature Comparison Threshold (0.0~1.0), default is 0.5

• Related Data Types and Interfaces

  ALGO_REID_SetParams

3.3 ReIdInputAttr_t

• Description

  Algorithm Input Structure

• Definition

  typedef struct ReIdInputAttr_
  {
      MI_U32 width;
      MI_U32 height;
      MI_IPU_ELEMENT_FORMAT format;
  }ReIdInputAttr_t;
  

• Members

  Member Name	Description
  width	Width of Model Input
  height	Height of Model Input
  format	Format of Model Input Image

• Related Data Types and Interfaces

  ALGO_REID_GetInputAttr

3.4 ReIdInput_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;
  } ReIdInput_t;
  

• Members

  Member Name	Description
  p_vir_addr	Virtual Address of Input Buffer
  phy_addr	Physical Address of Input Buffer
  buf_size	Length of Input Buffer
  pts	Timestamp of Input Buffer
  width	Frame Width of Input Buffer
  height	Frame Height of Input Buffer

• Related Data Types and Interfaces

  ALGO_REID_FeatureExtract

3.5 ReIdRes_t

• Description

  Algorithm Result Structure

• Definition

  typedef struct ReIdRes_{
      MI_FLOAT conf;
      MI_U32 id;
  }ReIdRes_t;
  

• Members

  Member Name	Description
  conf	Matching Target Similarity
  id	Matching ID

• Related Data Types and Interfaces

  ALGO_REID_FeatureCompare

3.6 PersonQualityOut_t

• Description

  Pedestrian Quality Structure

• Definition

  typedef struct
  {
      MI_FLOAT quality_score;
      MI_U32 cls;
      MI_FLOAT cls_score;
  } PersonQualityOut_t;
  

• Members

  Member Name	Description
  quality_score	Pedestrian Quality Score
  cls	Pedestrian Posture Category, 0 means standing, 1 means sitting, 2 means others
  cls_score	Pedestrian Posture Category Score

• Related Data Types and Interfaces

  ALGO_REID_FeatureCompare

4. Error Codes

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	Model Loading Failed
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 Dimensions
E_ALGO_INVALID_LICENSE	9	Invalid License
E_ALGO_MEMORY_OUT	10	Insufficient Memory
E_ALGO_FILEIO_ERROR	11	File Read/Write Operation Error
E_ALGO_INVALID_OUTPUT_SIZE	12	Invalid Algorithm Output Dimensions