HALCON算子get_metrology_object_param全解析
一、算子核心定位
get_metrology_object_param是HALCON 2D计量（2D Metrology）模块的参数读取核心算子，核心功能是按需获取计量模型中指定计量对象的任意可配置参数——涵盖几何参数（如圆的圆心/半径、矩形的尺寸/角度）、测量区域参数（如Sigma、阈值、测量条长度）、检测规则参数（如实例数、最小分数）等全维度参数，是验证计量对象配置、调试测量逻辑、读取几何基准值的核心工具，支持批量读取多个参数、多个计量对象的参数值。
二、算法核心原理
- 句柄与索引校验：验证计量模型句柄（MetrologyHandle）有效性，解析
Index参数确定要查询的计量对象范围（all遍历所有，指定索引则仅处理对应对象）； - 参数名解析：校验输入的
GenParamName参数名是否合法（是否为该计量对象支持的参数），排除无效参数名； - 参数值读取：针对每个指定的计量对象，按
GenParamName的顺序依次读取对应参数的当前值； - 结果封装：将读取的参数值按“计量对象索引顺序 + 参数名顺序”封装为数组，输出到
GenParamValue； - 无修改逻辑：仅读取参数值，不改变计量模型/对象的任何配置或状态。
三、参数全详解
（一）输入参数（Input Parameters）
| 参数名 | 类型 | 功能说明 | 默认值 | 关键取值规则 | 注意事项 |
|---|---|---|---|---|---|
| MetrologyHandle | metrology_model → (handle) | 指定要查询的2D计量模型句柄 | - | 必须为已有效创建/加载的计量模型句柄 | 1. 需通过create_metrology_model/read_metrology_model生成，且未被释放；2. 无效句柄直接触发“句柄无效”异常 |
| Index | integer(-array) → (string / integer) | 指定要查询的计量对象索引 | ‘all’ | 可选值： ▪ ‘all’：查询模型内所有计量对象的参数； ▪ 整数/整数数组：查询指定索引的计量对象（如0、[0,1]） | 整数索引必须是get_metrology_object_indices返回的有效索引，否则抛异常 |
| GenParamName | attribute.name-array → (string) | 要读取的参数名数组 | ‘num_measures’ | 支持的参数分为3类： 1. 通用参数（所有计量对象）： min_score、num_instances、measure_sigma、measure_threshold等；2. 几何类型参数（专属）： ▪ 圆： row、column、radius；▪ 矩形： row、column、phi、length1、length2；▪ 线： row_begin、column_begin、row_end、column_end；▪ 椭圆： row、column、phi、radius1、radius2；3. 元参数： object_type（几何类型）、object_params（所有几何参数集合） | 1. 若参数名对当前计量对象无效（如给线对象读radius），直接抛异常；2. 支持批量传入多个参数名（如[‘object_type’,‘measure_sigma’,‘num_instances’]） |
（二）输出参数（Output Parameters）
| 参数名 | 类型 | 功能说明 | 关联说明 |
|---|---|---|---|
| GenParamValue | attribute.value-array → (string / real / integer) | 返回参数值数组 | 1. 顺序严格匹配GenParamName（如GenParamName为[‘a’,‘b’]，则GenParamValue为[val_a, val_b]）；2. 若 Index为数组/all，则按“计量对象1的参数1→计量对象1的参数2→计量对象2的参数1→计量对象2的参数2”排列；3. 类型匹配参数（如 object_type返回字符串，measure_sigma返回实数，num_instances返回整数） |
四、使用关键注意事项
- 参数名与计量对象类型匹配：
- 专属几何参数仅适用于对应类型的计量对象（如
radius仅圆对象有效，length1仅矩形对象有效），跨类型读取会抛异常； - 通用参数（如
measure_sigma、num_instances）适用于所有类型计量对象；
- 专属几何参数仅适用于对应类型的计量对象（如
- 参数值顺序约束：
GenParamValue的顺序完全由GenParamName和Index决定，批量读取时需严格对应顺序解析； - 几何参数的特殊性：
- 计量对象的几何参数（如圆的
row/column/radius、矩形的length1/length2）仅能通过add_metrology_object_*算子设置，无法通过set_metrology_object_param修改，get_metrology_object_param仅可读取； object_params会返回该计量对象所有几何参数的集合（如矩形返回[row, column, phi, length1, length2]）；
- 计量对象的几何参数（如圆的
- 多线程特性：
- 多线程类型：可重入（能与非排他算子并行运行）；
- 多线程范围：全局（可从任意线程调用）；
- 无并行优化：仅单线程读取参数，无性能加速；
- 返回值规则：执行成功返回
2（H_MSG_TRUE），参数无效（如参数名错误、索引错误）时直接抛出异常。
五、算子调用链路
（一）前置算子（Possible Predecessors）
create_metrology_model：创建空的2D计量模型（基础前置）；add_metrology_object_*（如add_metrology_object_rectangle2_measure）：向模型添加计量对象（生成基础参数）；set_metrology_object_param：（可选）修改计量对象参数后，读取验证修改结果；get_metrology_object_indices：获取有效计量对象索引（用于精准指定Index）。
（二）后置算子（Possible Successors）
set_metrology_object_param：根据读取的参数值调整配置（如动态修改num_instances）；get_metrology_object_num_instances：结合参数值统计检测实例数；dev_print_var：打印参数值，用于调试或日志输出；clear_metrology_model：释放计量模型句柄（收尾操作）。
六、与相似算子的核心差异
| 算子名称 | 核心区别 | 适用场景 |
|---|---|---|
get_metrology_object_param | 读取计量对象的所有类型参数（几何、测量、规则），支持批量读取 | 验证配置、调试参数、读取基准几何值 |
get_metrology_object_fuzzy_param | 仅读取计量对象的模糊规则参数（如模糊分数阈值） | 调试模糊检测规则 |
get_metrology_object_num_instances | 仅读取计量对象的检测实例数量 | 统计检测到的目标数量 |
get_metrology_object_measures | 仅读取计量对象的测量区域轮廓+边缘原始坐标 | 可视化测量区域、验证边缘检测原始结果 |
八、总结
关键点回顾
get_metrology_object_param是2D计量模块的全维度参数读取工具，支持读取计量对象的几何、测量、检测规则类所有参数；- 参数值顺序严格匹配
GenParamName，且专属几何参数仅适用于对应类型的计量对象，跨类型读取会抛异常； - 计量对象的几何参数（如
row/column/radius）仅能通过add算子设置，无法通过set修改，get仅可读取基准值。
