3、检测结果数据结构：NvDsObjectMeta、NvDsFrameMeta、NvDsClassifierMeta等关键结构体解析

在DeepStream事件告警系统中，检测结果的数据结构是整个业务规则编写的地基。无论是目标过滤、区域入侵判断、还是分类结果聚合，最终都要落到对NvDsFrameMeta、NvDsObjectMeta、NvDsClassifierMeta等结构体的字段读取与逻辑组合上。很多开发者初次接触DeepStream时，往往被复杂的嵌套指针和批量内存管理搞得晕头转向——明明检测框坐标已经拿到了，却不知道如何关联到帧号；明明分类器输出了多个标签，却不清楚该从哪个字段取置信度。本章将系统拆解这些核心结构体的内存布局、字段含义、遍历方法，并结合事件告警场景给出可落地的操作范式。

上图展示了DeepStream元数据体系的核心关系。可以看到，NvDsFrameMeta是每一帧的“总目录”，它通过obj_meta_list挂载了该帧所有检测到的目标；每个NvDsObjectMeta代表一个具体目标（人、车、物品等），内部又通过classifier_meta_list关联了多个分类器输出；而NvDsClassifierMeta则进一步通过label_info_list展开为具体的标签信息。理解这条“帧→目标→分类器→标签”的嵌套链路，是编写事件告警规则的前提。

3.1 核心结构体字段精讲

3.1.1 NvDsFrameMeta：帧级元数据

NvDsFrameMeta是DeepStream批处理中每一帧的元数据容器，它描述了一个视频帧的整体属性。在事件告警场景中，我们最常关注以下字段：

• frame_num：帧序号，从0开始递增，用于标识视频流中的具体帧。在跨帧跟踪或事件时间线回溯时非常关键。
• source_id：视频源ID，当多路视频流同时输入时，用于区分不同摄像头。告警规则中常需要按source_id过滤特定区域的检测结果。
• batch_id：批处理ID，表示当前帧属于哪个batch。在批处理模式下，一个batch可能包含多路视频帧。
• num_obj_meta：当前帧中检测到的目标总数。这个字段可以快速判断帧内是否有目标，避免遍历链表。
• obj_meta_list：指向NvDsObjectMeta链表的头指针。这是访问具体目标信息的入口。
• video_meta：指向NvDsVideoMeta的指针，包含视频流的宽、高、帧率等信息。在计算坐标比例或判断ROI区域时需要用到。

在实际开发中，我们通常通过batch_meta的frame_meta_list来遍历所有帧。以下是一个典型的遍历框架：

NvDsBatchMeta *batch_meta = &batch_meta;
NvDsFrameMeta *frame_meta = NULL;
for (frame_meta = batch_meta->frame_meta_list; frame_meta != NULL; frame_meta = frame_meta->next) {
    // 处理每一帧
    g_print("Frame %d, Source %d, Objects: %d\n", 
            frame_meta->frame_num, frame_meta->source_id, frame_meta->num_obj_meta);
}

3.1.2 NvDsObjectMeta：目标级元数据

NvDsObjectMeta是告警规则中最常打交道的结构体，它代表一个被检测到的具体目标。关键字段包括：

其中rect_params是坐标信息的核心，它包含left、top、width、height四个字段，分别表示检测框左上角的x坐标、y坐标、宽度和高度。需要注意的是，这些坐标是相对于视频帧原始分辨率的像素值，而不是归一化坐标。在编写ROI区域判断时，需要将ROI坐标与检测框坐标统一到同一坐标系下。

3.1.3 NvDsClassifierMeta与NvDsLabelInfo：分类结果详解

当检测模型之后接有分类器（如车辆颜色识别、行人属性分析）时，分类结果会存储在NvDsClassifierMeta中。其核心字段包括：

• classifier_id：分类器ID，当有多个分类器时用于区分。
• num_labels：该分类器输出的标签数量。
• label_info_list：指向NvDsLabelInfo链表的头指针。
• result_text：分类结果的文本描述，如“红色轿车”。
• result_prob：分类结果的综合概率。

而NvDsLabelInfo则更细粒度地描述了每个标签的信息：

typedef struct {
    gchar *result_label;      // 标签名，如"red"
    gint result_class_id;     // 标签对应的类别ID
    gfloat result_prob;       // 该标签的概率
} NvDsLabelInfo;

在事件告警中，我们经常需要遍历label_info_list来找到概率最高的标签，或者判断某个特定属性是否存在。例如，在“检测到红色车辆进入禁行区域”的告警规则中，就需要先通过class_id判断目标是车辆，再遍历classifier_meta_list找到颜色分类器，最后在label_info_list中查找“red”标签。

3.2 结构体遍历与内存管理实战

3.2.1 完整遍历流程

在实际的DeepStream插件开发中，我们通常会在buffer_probe或自定义插件中执行以下遍历流程：

1. 从GstBuffer中获取NvDsBatchMeta。
2. 遍历batch_meta->frame_meta_list，获取每一帧的NvDsFrameMeta。
3. 遍历frame_meta->obj_meta_list，获取每个目标的NvDsObjectMeta。
4. 对于需要分类信息的目标，遍历obj_meta->classifier_meta_list。
5. 在分类器元数据中，遍历classifier_meta->label_info_list获取具体标签。

以下是一个完整的代码示例，展示了如何提取所有目标的坐标和分类信息：

static void process_frame(NvDsFrameMeta *frame_meta) {
    NvDsObjectMeta *obj_meta = NULL;
    for (obj_meta = frame_meta->obj_meta_list; obj_meta != NULL; obj_meta = obj_meta->next) {
        // 获取检测框坐标
        float left = obj_meta->rect_params.left;
        float top = obj_meta->rect_params.top;
        float width = obj_meta->rect_params.width;
        float height = obj_meta->rect_params.height;
        
        // 打印目标基本信息
        g_print("Object: %s, conf=%.2f, box=(%.0f,%.0f,%.0f,%.0f)\n",
                obj_meta->obj_label, obj_meta->confidence,
                left, top, width, height);
        
        // 遍历分类器
        NvDsClassifierMeta *cls_meta = NULL;
        for (cls_meta = obj_meta->classifier_meta_list; cls_meta != NULL; cls_meta = cls_meta->next) {
            NvDsLabelInfo *label_info = NULL;
            for (label_info = cls_meta->label_info_list; label_info != NULL; label_info = label_info->next) {
                g_print("  Classifier %d: %s = %.2f\n",
                        cls_meta->classifier_id,
                        label_info->result_label,
                        label_info->result_prob);
            }
        }
    }
}

3.2.2 坐标转换与ROI判断

在事件告警中，ROI区域判断是最常见的业务规则之一。假设我们需要判断目标是否进入“禁行区域”，ROI定义为矩形(x1, y1, x2, y2)，判断逻辑如下：

gboolean is_in_roi(NvDsObjectMeta *obj_meta, float roi_x1, float roi_y1, float roi_x2, float roi_y2) {
    float obj_x1 = obj_meta->rect_params.left;
    float obj_y1 = obj_meta->rect_params.top;
    float obj_x2 = obj_x1 + obj_meta->rect_params.width;
    float obj_y2 = obj_y1 + obj_meta->rect_params.height;
    
    // 判断目标中心点是否在ROI内
    float center_x = (obj_x1 + obj_x2) / 2;
    float center_y = (obj_y1 + obj_y2) / 2;
    
    return (center_x >= roi_x1 && center_x <= roi_x2 &&
            center_y >= roi_y1 && center_y <= roi_y2);
}

这里使用目标中心点作为判断依据，可以避免目标部分进入ROI时产生误报。如果需要更严格的“完全进入”判断，则需要比较整个检测框是否都在ROI内。

3.3 实战案例：车辆违停检测中的数据结构应用

下面通过一个完整的车辆违停检测案例，展示如何综合运用上述结构体。假设场景是某园区停车场，需要检测“车辆在禁停区域停留超过5秒”的事件。

背景与约束：摄像头分辨率为1920×1080，帧率25fps。禁停区域为画面右下角的矩形区域，坐标为(1200, 600)到(1800, 900)。检测模型可以识别车辆（class_id=2），跟踪器已启用。

初始现象：系统频繁产生误报，原因是部分行人（class_id=0）被误判为车辆，且一些车辆只是短暂经过禁停区域边缘。

分析判断过程：

1. 首先检查class_id，只处理class_id==2的目标，排除行人干扰。
2. 使用rect_params计算目标中心点，判断是否完全位于禁停区域内（中心点坐标在ROI范围内）。
3. 利用object_id进行跨帧跟踪，记录同一车辆首次进入ROI的时间戳。
4. 当车辆持续在ROI内超过5秒（125帧），触发告警。

关键代码实现：

typedef struct {
    guint64 object_id;
    guint64 first_frame_in_roi;
    gboolean is_in_roi;
} VehicleTrackInfo;

static GHashTable *vehicle_tracks = NULL;

void check_parking_violation(NvDsFrameMeta *frame_meta) {
    NvDsObjectMeta *obj_meta = NULL;
    for (obj_meta = frame_meta->obj_meta_list; obj_meta != NULL; obj_meta = obj_meta->next) {
        if (obj_meta->class_id != 2) continue;  // 只处理车辆
        
        gboolean in_roi = is_in_roi(obj_meta, 1200, 600, 1800, 900);
        VehicleTrackInfo *track = g_hash_table_lookup(vehicle_tracks, &obj_meta->object_id);
        
        if (in_roi) {
            if (track == NULL) {
                // 新进入ROI的车辆
                track = g_new0(VehicleTrackInfo, 1);
                track->object_id = obj_meta->object_id;
                track->first_frame_in_roi = frame_meta->frame_num;
                g_hash_table_insert(vehicle_tracks, &obj_meta->object_id, track);
            } else {
                // 检查是否超时
                guint64 elapsed_frames = frame_meta->frame_num - track->first_frame_in_roi;
                if (elapsed_frames > 125) {  // 5秒 * 25fps
                    g_print("ALERT: Vehicle %lu parked in no-parking zone for %.1f seconds\n",
                            obj_meta->object_id, elapsed_frames / 25.0);
                }
            }
        } else {
            // 车辆离开ROI，清除记录
            if (track != NULL) {
                g_hash_table_remove(vehicle_tracks, &obj_meta->object_id);
            }
        }
    }
}

结果对比：加入class_id过滤后，行人误报完全消除；使用中心点判断后，边缘经过的车辆不再触发告警；通过object_id跟踪，实现了精确的停留时间计算。最终告警准确率从68%提升到94%。

风险与代价：使用GHashTable存储跟踪信息会占用一定内存，在长时间运行后需要定期清理超时的记录。另外，如果跟踪器发生ID切换（track_id reassignment），可能导致同一车辆被误判为两辆车，需要在业务逻辑中增加容错处理。

3.4 常见误区与性能优化建议

3.4.1 常见误区

• 误区一：混淆left/top与x/y。在NvDsRectParams中，left和top就是检测框左上角的坐标，不要额外加上width/2来“修正”。
• 误区二：直接修改元数据字段。某些字段（如object_id）由跟踪器管理，手动修改可能导致跟踪异常。如需修改，应通过DeepStream提供的API。
• 误区三：忽略链表遍历的NULL检查。在遍历obj_meta_list或classifier_meta_list时，必须检查当前节点是否为NULL，否则在空链表上访问->next会崩溃。
• 误区四：在回调中保存指针。元数据内存在buffer处理完成后可能被释放，保存指针会导致悬垂引用。应保存数据的副本。

3.4.2 性能优化建议

在实际项目中，建议在开发初期就建立一套元数据访问的封装层，将常用的“获取目标坐标”、“判断ROI”、“读取分类结果”等操作封装为独立函数。这样不仅代码更清晰，也便于后续维护和规则扩展。DeepStream的元数据体系虽然初看复杂，但只要掌握了“帧→目标→分类器”这条主线，再结合具体的业务规则，就能灵活地构建出强大的事件告警系统。