企业官网建设流程全解析

HALCON算子get_metrology_object_num_instances全解析

一、算子核心定位

get_metrology_object_num_instances是HALCON 2D计量（2D Metrology）模块的结果统计类核心算子，核心功能是获取指定计量对象经apply_metrology_model检测后实际得到的“实例数量”（即检测到的目标数量）。它是统计2D计量模型检测结果数量的关键工具，默认情况下每个计量对象最多仅返回1个实例（需提前配置参数才能检测多个），常用于判断目标是否被检测到、或统计同类型目标的数量。

二、算法核心原理

1. 句柄与索引校验：验证输入的计量模型句柄（MetrologyHandle）有效性，并解析Index参数确定要查询的计量对象范围（all遍历所有，指定索引则仅处理对应对象）；
2. 实例数读取：针对每个指定的计量对象，读取其经apply_metrology_model检测后实际生成的实例数量（未执行检测则为0）；
3. 结果返回：将每个计量对象的实例数按Index的顺序封装为数组，输出到NumInstances参数；
4. 无修改逻辑：仅读取实例数统计结果，不改变计量模型/对象的任何属性或检测结果。

三、参数全详解

（一）输入参数（Input Parameters）

（二）输出参数（Output Parameters）

四、使用关键注意事项

1. 执行时序约束：必须在调用apply_metrology_model（执行检测）后调用本算子，否则NumInstances返回0；若检测未找到目标，也会返回0；
2. 默认实例数限制：
   • 每个计量对象默认参数num_instances=1，因此默认情况下NumInstances最大为1；
   • 若需检测多个同类型目标（如图像中有3个圆），需提前通过set_metrology_object_param将该计量对象的num_instances设为更大值（如5）或'all'；
3. 多线程特性：
   • 多线程类型：可重入（能与非排他算子并行运行）；
   • 多线程范围：全局（可从任意线程调用）；
   • 无并行优化：仅单线程读取数据，无性能加速；
4. Index与NumInstances的对应性：
   • 若Index为单个整数（如0），NumInstances为单个数值；
   • 若Index为数组（如[0,1]）或'all'，NumInstances为同长度数组，顺序严格匹配；
5. 返回值规则：执行成功返回2（H_MSG_TRUE），参数无效（如索引错误、句柄无效）时直接抛出异常。

五、算子调用链路

（一）前置算子（Possible Predecessors）

• create_metrology_model：创建空的2D计量模型（基础前置）；
• add_metrology_object_*（如add_metrology_object_circle_measure）：向模型添加计量对象；
• set_metrology_object_param：（可选）设置计量对象的num_instances参数（如需检测多个实例）；
• apply_metrology_model：执行边缘检测与实例拟合（获取实例数的必要前置）；
• get_metrology_object_indices：获取有效计量对象索引（可选，用于精准指定Index）。

（二）后置算子（Possible Successors）

• get_metrology_object_result：根据实例数读取每个实例的几何参数（如圆的圆心、半径）；
• clear_metrology_model：释放计量模型句柄（收尾操作）；
• dev_print_var：打印实例数，用于结果校验或日志输出。

六、与相似算子的核心差异

八、总结

关键点回顾

1. get_metrology_object_num_instances核心作用是统计计量对象经apply_metrology_model检测后的实例数量，未检测/未执行检测时返回0；
2. 默认每个计量对象最多返回1个实例，需提前用set_metrology_object_param设置num_instances为更大值或'all'才能统计多目标；
3. NumInstances的顺序与Index严格对应，可据此精准读取每个计量对象的检测结果数量。