HALCON算子get_metrology_object_indices全解析
一、算子核心定位
get_metrology_object_indices是HALCON 2D计量（2D Metrology）模块的基础核心算子，核心功能是获取指定2D计量模型中所有计量对象的索引列表，是访问计量对象参数（如尺寸、位置、模糊规则、检测实例数等）的前置关键步骤，为后续精准读取/修改特定计量对象属性提供唯一的索引依据，是2D计量模块中“定位-操作”计量对象的基础桥梁。
二、算法核心原理
- 句柄解析：根据输入的计量模型句柄（MetrologyHandle），验证句柄有效性并定位到对应的2D计量模型内存空间；
- 索引遍历：遍历该计量模型内已创建/加载的所有计量对象（如圆、矩形、线等计量对象）；
- 索引返回：将所有计量对象的唯一整数索引以数组形式输出到
Indices参数； - 无修改逻辑：仅执行索引的读取和返回操作，不改变计量模型或计量对象的任何属性、状态。
三、参数全详解
（一）输入参数（Input Parameters）
| 参数名 | 类型 | 功能说明 | 默认值 | 关键取值规则 | 注意事项 |
|---|---|---|---|---|---|
| MetrologyHandle | metrology_model → (handle) | 指定要查询的2D计量模型句柄 | - | 必须为已有效创建/加载的计量模型句柄 | 1. 句柄需通过create_metrology_model/read_metrology_model生成，且未被clear_metrology_model释放；2. 无效句柄会直接触发“句柄无效”异常 |
（二）输出参数（Output Parameters）
| 参数名 | 类型 | 功能说明 | 关联说明 |
|---|---|---|---|
| Indices | integer(-array) → (integer) | 返回计量模型中所有计量对象的索引列表 | 1. 每个索引对应模型内一个唯一的计量对象； 2. 可作为 get_metrology_object_param/set_metrology_object_param等算子的输入，用于定位具体计量对象；3. 若模型无计量对象，返回空数组 |
四、使用关键注意事项
- 句柄有效性约束：必须确保
MetrologyHandle是已初始化的有效句柄，未被释放或未创建的句柄会抛出异常，而非返回错误码； - 多线程特性：
- 多线程类型：可重入（能与非排他算子并行运行）；
- 多线程范围：全局（可从任意线程调用）；
- 无并行优化：仅单线程读取索引，无性能加速逻辑；
- 索引特性：返回的索引通常从0开始，按计量对象的创建/加载顺序递增（如第一个添加的计量对象索引为0，第二个为1）；
- 空模型处理：若计量模型内无任何计量对象（如刚创建的空模型），
Indices返回空数组，不会触发异常，需在后续逻辑中处理空数组场景； - 返回值规则：算子执行成功返回
2（H_MSG_TRUE），参数无效（如句柄错误）时直接抛出异常。
五、算子调用链路
（一）前置算子（Possible Predecessors）
create_metrology_model：创建空的2D计量模型（基础前置）；read_metrology_model：从文件加载预定义的计量模型（最常用前置）；add_metrology_object_*（如add_metrology_object_circle_measure/add_metrology_object_rectangle2_measure）：向计量模型添加计量对象后，调用本算子获取新增对象索引。
（二）后置算子（Possible Successors）
get_metrology_object_param：根据索引读取指定计量对象的常规参数（如圆心坐标、矩形角度、测量长度）；get_metrology_object_fuzzy_param：根据索引读取指定计量对象的模糊规则参数；set_metrology_object_param：根据索引修改指定计量对象的参数；get_metrology_object_num_instances：根据索引获取指定计量对象的检测实例数量。
六、与相似算子的核心差异
| 算子名称 | 核心区别 | 适用场景 |
|---|---|---|
get_metrology_object_indices | 返回所有计量对象的索引列表 | 批量遍历处理模型内所有计量对象（如批量读取所有对象参数） |
get_metrology_object_num_instances | 返回单个指定计量对象的检测实例数 | 查询某一计量对象实际检测到的目标数量（如圆计量对象检测到3个圆） |
get_metrology_model_param | 返回计量模型的全局参数（如单位、投影方式） | 读取模型层面的属性，而非单个计量对象属性 |
八、总结
关键点回顾
get_metrology_object_indices核心作用是读取2D计量模型中所有计量对象的索引列表，是访问单个计量对象属性的前置必要步骤；- 该算子仅做索引读取，无修改操作，返回的索引是后续精准操作计量对象的唯一标识；
- 使用时需确保计量模型句柄有效，空模型会返回空索引数组，需做好空值场景的逻辑处理。
