16 KiB
NeoTracker SDK
1. 范围
目前对标准跟踪器的解耦方案如下：
本文档描述的NeoTracker SDK为上图蓝色部分，包含对空对地搜索、传统跟踪算法逻辑，并与NPU设备运行的AI识别与AI跟踪算法进行交互。
2.图像
接口中图像使用平台定义的GD_VIDEO_FRAME_S。
#ifndef GD_VIDEO_FRAME_S
#define GD_VIDEO_FRAME_S
typedef enum _gd_pixel_format_e {
GD_PIXEL_FORMAT_NONE = 0,
GD_PIXEL_FORMAT_YUV420P,
GD_PIXEL_FORMAT_YUV422P,
GD_PIXEL_FORMAT_NV12,
GD_PIXEL_FORMAT_NV21,
GD_PIXEL_FORMAT_NV16,
GD_PIXEL_FORMAT_NV61,
GD_PIXEL_FORMAT_RGB_PLANAR,
GD_PIXEL_FORMAT_BGR_PLANAR,
GD_PIXEL_FORMAT_RGB_PACKED,
GD_PIXEL_FORMAT_BGR_PACKED,
GD_PIXEL_FORMAT_GRAY_Y8,
GD_PIXEL_FORMAT_GRAY_Y16,
GD_PIXEL_FORMAT_GRAY_Y16Y8,
GD_PIXEL_FORMAT_BUTT
} GD_PIXEL_FORMAT_E;
typedef struct _gd_video_frame_s {
unsigned int u32Width;
unsigned int u32Height;
GD_PIXEL_FORMAT_E enPixelFormat;
unsigned int u32Stride[3];
unsigned long long u64PhyAddr[3];
unsigned char* u64VirAddr[3];
unsigned int u32TimeRef;
unsigned int u32FrameCnt;
} GD_VIDEO_FRAME_S;
#endif
图像数据结构引用平台室《图像格式要求》，该格式相对于传统算法输入图像格式，特点是内存可以不连续 （1）yuv、RGB不同通道的地址可以不连续 （2）数据带有stride属性，目前海思平台上广泛使用这种数据类型，用于字节对齐加快处理速度。
目前对数据结构的支持如下:
| 模块 | Y16 | Y8 | NV12 | RGB_PACKED | 其他 |
|---|---|---|---|---|---|
| DST | 支持 | x | x | x | x |
| DAT | 支持 | 支持 | x | x | x |
| KCF | 支持 | 支持 | 支持 | 支持 | x |
| TLD | 支持 | 支持 | 支持 | 支持 | x |
| OCC | 支持 | 支持 | 支持 | 支持 | x |
目前算法内部对数据的处理基于连续内存，因此暂不支持stride特性。如图像通道不满足内存连续，算法会直接退出。需要在赋值时将stride赋值为实际占用内存长度，如Y16数据位 w * 2，RGB数据为w * 3
3 主接口与调用时序控制
相对于之前一个主接口打天下的方式，现阶段需要调用的接口增加。
- 接口使用前需要显式调用构造函数和初始化函数，使用完毕后手动析构函数。
- 由于AI识别技术的广泛使用， 参考S727的实现，将传统小面目标检测接口单独暴露出来供调用。目标列表融合部分需要针对每个项目需求编写。检测部分也受到整个算法模块的状态控制，因此也需要在初始化完成后调用，如对空对地模式参数。
框架如何响应外部指令。外部指令发出是瞬时的，在跟踪流程的任意时刻都有可能，但多目标跟踪过程中，批号、算法资源等都严重依赖上下帧关系，不能实时处理指令，从框架设计简易考虑， 需要在每一帧开始前进行统一的指令计算与响应。 因此本框架仍不支持实时响应，需要在下一帧统一处理。
3.4 锁定逻辑
跟踪算法最重要的外部接口是锁定逻辑，本框架中将锁定指令进行如下划分，作不同响应。
接口1：普通锁定
void ARIDLL_LockCommand(ArithHandle hArithSrc, int nLockX, int nLockY, int nLockW, int nLockH)
- LockMode::LOCK_POINT
如果不传大小，则为点锁定，点锁定位置附近若存在目标，则自动锁定该目标，若点锁定附近无目标，则根据需求可执行不同操作，例如对空可进行强制提取，对地可进行固定波门锁定。
- LockMode::LOCK_RECT:
如果传入完整的锁定框，那么仅执行强制面目标锁定。
接口2：引导锁定
void ARIDLL_GuideLockMultiCommand(ArithHandle hArithSrc, TargetGuide* guideList, int num)
给出稳定系角度进行目标锁定，属于某种自动锁定逻辑，要求算法根据先验对视场内的目标进行智能化选择与锁定。同样支持多个目标。
引导锁定在接口形式上与普通锁定的点选比较接近，但一般点选是有人在回路的，锁错代价低，要求快速响应。引导锁定一般是个连续的自动流程，要求一次性锁对，可以延迟多帧处理。
STD_TRACKER_API void ARIDLL_AdjustTrackRect(ArithHandle hArithSrc,int dx,int dy,int dw,int dh);
修改锁定波门接口，可以在目标静止时微调已跟踪的目标框。接口是通过重复下发锁定实现的，因此不适合跟踪运动目标时使用。此外，由于在多目标场景下下发锁定一般会实现为再次初始化新目标， 因此本接口限制为仅单目标跟踪模式下有效。
关于延迟跟踪机制 该机制在跟踪调用端实现，可以降低算法设计的复杂度。 对于无线传输项目，显控端收到的图像往往是延迟的，用户在延迟的数据上下发跟踪，指令传到设备端后已无法确认指令要求的位置和图像。因此针对延迟跟踪项目，需要使用缓存队列+延迟跟踪设计。
正常跟踪时，算法调用者（综控）始终缓存图像帧（含内容与帧编号），显控端下发锁定指令时需附带帧编号，如果帧编号滞后于当前最新帧编号，则在缓存队列中查找用户锁定帧，并将送算法的队列指针指向该帧，同时根据帧差自适应跳帧速度，跟踪到最新帧后，则恢复正常跟踪。
4 状态与模式
本SDK目前定义了如下算法及需求相关的状态/模式，解释如下。
4.1外部系统模式 GLB_SYS_MODE
通常用于响应用户产品模式，如S338用户定义的【战斗】【模靶】等，S731自主定义的【无人值守】【扫描】等，不一定都会影响算法状态和运行，但通常都需将该模式传递给算法便于灵活响应，不同的项目区别较大，可能涉及接口增加。
4.2 算法内部状态 GLB_STATUS
算法根据用户需求，将自身工作状态进行划分。同时会针对不同控制指令自行切换。通常我司的光电设备具有 搜索 - 单目标跟踪 - 周扫 - 扇扫 - 多目标跟踪 - 丢失等状态。 根据下发的锁定指令或引导指令，算法会从不同的搜索状态转为跟踪，同时会输出自身当前状态，需要调用者外部及时接收并配合做出不同的响应（控制伺服、上报等）。
【搜索】 算法执行目标检测，并进行时空域滤波，送出具有固定批号的目标列表，该列表可以在如下结构中体现。
//*****目标检测*****(短时航迹点，用于用户指示)
int nAlarmObjCnts; //当前帧告警目标总个数
ARIDLL_OBJINFO stAlarmObjs[ST_OBJ_NUM]; //检测目标信息数组
【周扫】【扇扫】 与搜索状态基本一致，仅对目标出视场处理有所区别。
【跟踪】 跟踪一般是接收到锁定、引导或自动切换进入，进入跟踪状态后，将在如下结构中体现
//*****目标跟踪*****(长时航迹点，第0个为主目标送伺服跟踪)
int nTrackObjCnts; //跟踪目标个数
ARIDLL_OBJINFO stTrackers[LT_OBJ_NUM]; //跟踪器输出数组
【待命】 一般不执行算法
【丢失】 跟踪状态下的子状态，表明跟踪器暂时无法发现目标，但没有放弃目标跟踪，仍保留了目标批号，此时需要将该状态透传给伺服控制，用于执行记忆跟踪。 一旦重捕目标成功，将从丢失重新回到跟踪状态。
4.3 场景模式 GLB_SCEN_MODE
指对空、对地、对海、实验室等场景的跟踪算法，由于场景不同，算法很难用相同的策略进行跟踪，因此为了保持良好的跟踪能力，在不同的场景下算法区分了实现，需要外部根据需要进行切换。通常项目中都允许进行手动切换或模式保持某种场景模式。
5 版本查询
NeoTacker的版本信息填写在不同模块的Version.h.in 文件中。包含构建时间和版本号。
#pragma once
#include <string>
std::string BUILD_TIME = "BUILD_TIME @build_time@";
std::string VERSION = "BUILD_VERSION 0.9.0";
其中版本号手动填写更新，编译时间自动生成。利用Cmake进行构造时，会自动将Version.h.in文件转为Version.h，其中会将编译时间更换为当前时间。
编译完成后，通过如下指令可获取版本信息和编译时间。
6.API 说明
6.1 构造
STD_TRACKER_API ArithHandle STD_CreatEOArithHandle();
ArithHandle 类型为void*，表示算法实例的指针,需要主动调用构造与析构，以此完成算法实例的生成与资源释放。
6.2 初始化
STD_TRACKER_API void ARIDLL_EOArithInit(ArithHandle hArith,int nWidth, int nHeight, GD_PIXEL_FORMAT_E nPixelType);
STD_TRACKER_API void ARIDLL_EOArithInitWithMode(ArithHandle hArith, int nWidth, int nHeight, GD_PIXEL_FORMAT_E nPixelType,
GLB_SYS_MODE nSysMode,GLB_SCEN_MODE nScenMode);
在调用后续接口前，需要完成初始化，否则后续接口将不能正常工作。可以调用默认初始化以及指定工作模式的初始化。
6.3 检测接口
STD_TRACKER_API TARGET_OBJECT* ARIDLL_SearchFrameTargets(ArithHandle hArithSrc, GD_VIDEO_FRAME_S img, int* nFrmTargetNum);
调用接口获取当前帧图像的传统目标检测队列，返回目标个数，以及目标队列。
传统检测算法与AI识别并行运行完成后，调用者在 此处调用下面的接口可以合并二者输出。【可选】
STD_TRACKER_API int ARIDLL_MergeAITargets(ArithHandle hArithSrc, TARGET_OBJECT* pTargetArray,int num,obj_res* aiDetectArray,int aiNum);
合并后将AI识别与传统目标检测放在统一的数据结构中送入跟踪模块，这里主要是处理字段的拷贝与溢出异常。
由于检测器通常与跟踪器并行，因此可能存在同时读写冲突，算法内部无锁，需调用者自行处理。
6.4 主接口
STD_TRACKER_API int ARIDLL_RunController(ArithHandle hArithSrc, GD_VIDEO_FRAME_S img, ARIDLL_INPUTPARA stInputPara, ARIDLL_OUTPUT* pstOutput);
#ifndef _ARIDLL_INPUTPARA_
#define _ARIDLL_INPUTPARA_
//输入【系统参数】结构体
typedef struct tagARIDLL_INPUTPARA
{
int nTimeStamp; //当前帧采集时刻时间戳，单位毫秒
int unFrmId; //当前帧图像帧编号
ServoInfo stServoInfo; //传感器伺服信息
CamInfo stCameraInfo; //相机信息
AirCraftInfo stAirCraftInfo; //载体信息
GuideInfo stGuideInfo; //外部引导信息
// 外部目标列表
int nInputTargetNum;
TARGET_OBJECT stInputTarget[INPUT_OBJ_NUM]; // 外部输入目标列表，包含AI识别结果
// AI跟踪器结果
AIT_OUTPUT stAITrackerInfo;
}ARIDLL_INPUTPARA;
#endif
输入参数基本不需要介绍。
#ifndef _ARIDLL_OUTPUT_
#define _ARIDLL_OUTPUT_
//跟踪目标输出结构体
typedef struct tagARIDLL_OUTPUT
{
int nTimeStamp;//当前帧时间戳(透传)，单位：毫秒
// 系统工作模式(透传)// by wcw04046 @ 2021/12/06
int nSysMode;
int nFrmNum;//处理帧计数
//*****工作状态*****
int nStatus; //待命/检测/跟踪/丢失状态信息等
//*****目标检测*****(短时航迹点，用于用户指示)
int nAlarmObjCnts; //当前帧告警目标总个数
ARIDLL_OBJINFO stAlarmObjs[ST_OBJ_NUM]; //检测目标信息数组
//*****目标跟踪*****(长时航迹点，第0个为主目标送伺服跟踪)
int nTrackObjCnts; //跟踪目标个数
ARIDLL_OBJINFO stTrackers[LT_OBJ_NUM]; //跟踪器输出数组
// 以下为调试内容
// 事件处理信息
TRACK_EVENT stEventInfo;
// 算法控制指令计算透传（来自API调用）
GLB_PCCOMMAND stCommand;
// AI跟踪器协同控制指令输出,用于控制端侧NPU程序
AIT_Command stAI_TkCmd;
// 自定义输出---------
ARIDLL_DEBUG_OUTPUT stDebugInfo;
}ARIDLL_OUTPUT;
#endif
注意主接口返回的nSysMode表示的是凝视/扫描/自主工作等系统模式，nStatus表示算法内部的搜索/跟踪/多目标跟踪等状态。
6.5 切换扫描/凝视/等系统模式
STD_TRACKER_API void ARIDLL_SetSysMode(ArithHandle hArithSrc, GLB_SYS_MODE nSysMode);
将算法在凝视/扇描/周扫等模式进行切换，算法行为有一定差异。
6.6 对空/对地场景模式切换
STD_TRACKER_API void ARIDLL_SetScenMode(ArithHandle hArithSrc, GLB_SCEN_MODE nScenMode);
算法切换为对空/对地/对海等场景模式，切换后原跟踪目标自动解锁，算法自动切入SEARCH状态。
6.7 锁定接口
STD_TRACKER_API void ARIDLL_LockCommand(ArithHandle hArithSrc, int nLockX,int nLockY,int nLockW,int nLockH);
调用后算法将从凝视尝试切换为跟踪状态，并输出锁定目标的位置。通过传参宽高可以选择点选或者框选，分别按照不同的项目需求进行锁定逻辑实现。
STD_TRACKER_API ARIDLL_OBJINFO ARIDLL_LockTarget(ArithHandle hArithSrc, GD_VIDEO_FRAME_S img, int nLockX, int nLockY, int nLockW, int nLockH);
该接口功能与ARIDLL_LockCommand 一致，区别在于算法在当前帧完成锁定，并将锁定目标传出来。传该目标的原因在锁定波门一般与用户设置或者识别结果相关，传统跟踪器有最全面的参数和用户信息，这样传统锁定结果可以供AI跟踪使用，避免同时向AI跟踪传递重复的识别列表或者自定义波门等信息。
用该接口比上一个快1帧完成锁定，适合目标快速运动场景捕获目标。
STD_TRACKER_API void ARIDLL_GuideLockMultiCommand(ArithHandle hArithSrc, TargetGuide* guideList,int num);
外引导转跟踪，可支持多批次的引导目标自动锁定。调用接口后算法等待目标进入视场（自动判断），并按照目标先验自动选择最佳目标进行跟踪。外部需监控算法状态，进入跟踪后即表明已锁定目标。
6.8 解除锁定
STD_TRACKER_API void ARIDLL_unLockCommand(ArithHandle hArithSrc);
调用后主接口返回的状态将变为搜索，跟踪器解锁。
6.9 算法参数设置
STD_TRACKER_API bool ARIDLL_SetRunTimeParam(ArithHandle hArithSrc, ARIDLL_PARMA config);
STD_TRACKER_API bool ARIDLL_GetRunTimeParam(ArithHandle hArithSrc, ARIDLL_PARMA* pConfig);
STD_TRACKER_API bool ARIDLL_ReadSetParamFile(ArithHandle hArithSrc, const char* configFilePath);
STD_TRACKER_API bool ARIDLL_ReadSetParamStream(ArithHandle hArithSrc,const char* configsstream);
算法参数获取与设置接口，支持json配置文件（文件路径或字符流）下发以及结构体下发。
6.10 运行TLD接口
TLD在算法中通常占用了较长时间，在某些帧频较高的系统中，需要将TLD与主接口并行，提高跟踪频率，这样处理的代价是TLD的结果要在下一帧才能传递给主跟踪，可能引起细微跟踪效果下降。标准基线中本接口是不调用的，算法自行在内部运行了TLD。 一旦在外部调用该接口，需要关闭算法内部的TLD运行，因此调用该接口时需将输入的flag标记置为true以关闭内部调用。
STD_TRACKER_API void ARIDLL_RunTLDTracker(ArithHandle hArithSrc,GD_VIDEO_FRAME_S img);
6.11 析构
STD_TRACKER_API void STD_DeleteEOArithHandle(ArithHandle hArith);