HALCON算子get_metrology_object_num_instances全解析
一、算子核心定位
get_metrology_object_num_instances是HALCON 2D计量（2D Metrology）模块的结果统计类核心算子，核心功能是获取指定计量对象经apply_metrology_model检测后实际得到的“实例数量”（即检测到的目标数量）。它是统计2D计量模型检测结果数量的关键工具，默认情况下每个计量对象最多仅返回1个实例（需提前配置参数才能检测多个），常用于判断目标是否被检测到、或统计同类型目标的数量。
二、算法核心原理
- 句柄与索引校验：验证输入的计量模型句柄（MetrologyHandle）有效性，并解析
Index参数确定要查询的计量对象范围（all遍历所有，指定索引则仅处理对应对象）； - 实例数读取：针对每个指定的计量对象，读取其经
apply_metrology_model检测后实际生成的实例数量（未执行检测则为0）； - 结果返回：将每个计量对象的实例数按
Index的顺序封装为数组，输出到NumInstances参数； - 无修改逻辑：仅读取实例数统计结果，不改变计量模型/对象的任何属性或检测结果。
三、参数全详解
（一）输入参数（Input Parameters）
| 参数名 | 类型 | 功能说明 | 默认值 | 关键取值规则 | 注意事项 |
|---|---|---|---|---|---|
| MetrologyHandle | metrology_model → (handle) | 指定要查询的2D计量模型句柄 | - | 必须为已有效创建/加载的计量模型句柄 | 1. 需通过create_metrology_model/read_metrology_model生成，且未被clear_metrology_model释放；2. 无效句柄直接触发“句柄无效”异常 |
| Index | integer(-array) → (integer / string) | 指定要查询的计量对象索引 | 0 | 可选值： ▪ ‘all’：查询模型内所有计量对象的实例数； ▪ 整数/整数数组：查询指定索引的计量对象（如0、[0,1]） | 1. 整数索引必须是get_metrology_object_indices返回的有效索引；2. 若 Index为数组，NumInstances会按相同顺序返回对应实例数 |
（二）输出参数（Output Parameters）
| 参数名 | 类型 | 功能说明 | 关联说明 |
|---|---|---|---|
| NumInstances | integer(-array) → (real / integer) | 返回指定计量对象的实例数量数组 | 1. 顺序与Index完全对应（Index为all时，顺序与get_metrology_object_indices返回的索引一致）；2. 未执行 apply_metrology_model时返回0；3. 默认最大值为1（需提前设置 num_instances参数才能返回更大值） |
四、使用关键注意事项
- 执行时序约束：必须在调用
apply_metrology_model（执行检测）后调用本算子，否则NumInstances返回0；若检测未找到目标，也会返回0； - 默认实例数限制：
- 每个计量对象默认参数
num_instances=1，因此默认情况下NumInstances最大为1； - 若需检测多个同类型目标（如图像中有3个圆），需提前通过
set_metrology_object_param将该计量对象的num_instances设为更大值（如5）或'all'；
- 每个计量对象默认参数
- 多线程特性：
- 多线程类型：可重入（能与非排他算子并行运行）；
- 多线程范围：全局（可从任意线程调用）；
- 无并行优化：仅单线程读取数据，无性能加速；
- Index与NumInstances的对应性：
- 若
Index为单个整数（如0），NumInstances为单个数值； - 若
Index为数组（如[0,1]）或'all'，NumInstances为同长度数组，顺序严格匹配；
- 若
- 返回值规则：执行成功返回
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：打印实例数，用于结果校验或日志输出。
六、与相似算子的核心差异
| 算子名称 | 核心区别 | 适用场景 |
|---|---|---|
get_metrology_object_num_instances | 返回计量对象的检测实例数量（目标个数） | 统计检测到的目标数量、判断目标是否存在 |
get_metrology_object_indices | 返回计量模型中计量对象的索引列表 | 定位要操作的计量对象 |
get_metrology_object_measures | 返回计量对象的测量区域轮廓+边缘原始坐标 | 调试测量区域、验证边缘检测原始结果 |
get_metrology_object_result | 返回每个实例的几何拟合结果（如圆心、尺寸） | 获取目标的具体测量参数 |
八、总结
关键点回顾
get_metrology_object_num_instances核心作用是统计计量对象经apply_metrology_model检测后的实例数量，未检测/未执行检测时返回0；- 默认每个计量对象最多返回1个实例，需提前用
set_metrology_object_param设置num_instances为更大值或'all'才能统计多目标； NumInstances的顺序与Index严格对应，可据此精准读取每个计量对象的检测结果数量。
