HALCON算子get_metrology_model_param全解析
一、算子核心定位
get_metrology_model_param是HALCON 2D计量（2D Metrology）模块中读取计量模型全局参数的核心算子，其作用是查询作用于整个计量模型的通用配置参数（区别于针对单个计量对象的get_metrology_object_param），比如相机内参、测量平面3D位姿、参考坐标系、测量结果缩放因子等。该算子常用于验证计量模型的全局配置是否正确，或在测量后读取全局参数以辅助结果解析（如将像素单位的测量结果转换为物理单位）。
二、算法核心原理
get_metrology_model_param的核心逻辑是基于句柄定位模型 + 参数名匹配配置项：
- 通过输入的
MetrologyHandle（计量模型句柄）定位到目标计量模型的全局配置数据区； - 根据
GenParamName（参数名）匹配对应配置项的存储位置； - 读取该配置项的数值/数据，并通过
GenParamValue返回（返回值类型随参数名不同而变化）。
整个过程仅读取参数不修改模型状态，且支持多线程安全调用。
三、参数全详解
（一）输入参数（Input Parameters）
| 参数名 | 类型 | 功能说明 | 默认值 | 合法取值 | 注意事项 |
|---|---|---|---|---|---|
| MetrologyHandle | 计量模型句柄（metrology_model → handle） | 要查询参数的目标计量模型句柄 | - | 合法且未释放的计量模型句柄 | 句柄无效（如已关闭、空句柄）会直接抛出异常 |
| GenParamName | 通用参数名（attribute.name → string） | 要查询的全局参数名称 | 'camera_param' | 'camera_param'、'plane_pose'、'reference_system'、'scale' | 仅支持指定的4个参数名，传入其他值会触发参数异常 |
（二）输出参数（Output Parameters）
| 参数名 | 类型 | 功能说明 | 各参数名对应的返回值详情 |
|---|---|---|---|
| GenParamValue | 参数值（attribute.value(-array) → string/real/integer） | 对应GenParamName的参数值，类型随参数名变化 | 1.'camera_param'：字符串类型，返回相机内参（如"area_scan_division 0 0 0 0 0 0 1 1 0 0 0 0"）2. 'plane_pose'：实数数组，返回测量平面的3D位姿（格式为[tx, ty, tz, rx, ry, rz]，相机坐标系下）3. 'reference_system'：实数数组，返回参考坐标系相对图像坐标系的变换（格式为[row, column, angle]，分别对应参考系原点行坐标、列坐标、旋转角度）4. 'scale'：实数，返回测量结果的缩放因子（用于将像素单位转换为物理单位，如mm） |
四、使用关键注意事项
- 参数名合法性：
GenParamName仅支持'camera_param'/'plane_pose'/'reference_system'/'scale'四个值，需严格匹配字符串（大小写敏感）； - 返回值类型适配：需根据查询的参数名对应处理
GenParamValue的类型：'camera_param'是字符串，需用字符串解析函数处理；- 其余三个参数均为实数数组/单实数，需用数值类型接收；
- 多线程特性：
- 多线程类型：可重入（与非排他算子并行运行）；
- 多线程范围：全局（可从任意线程调用）；
- 无并行处理（单线程读取参数）；
- 参数存在性：若查询的参数未通过
set_metrology_model_param设置过，会返回该参数的默认值（如'scale'默认值为1.0）； - 返回值规则：参数合法时返回
2 (H_MSG_TRUE)，参数非法（如无效句柄、错误参数名）会抛出异常。
五、算子调用链路
（一）前置算子（Possible Predecessors）
| 算子名称 | 核心作用 | 关联场景 |
|---|---|---|
set_metrology_model_param | 为计量模型设置全局参数 | 先设置参数，再调用本算子验证设置是否生效 |
get_metrology_object_indices | 获取计量模型中计量对象的索引 | 先确认模型内对象，再查询全局参数辅助结果解析 |
（二）后置算子（Possible Successors）
| 算子名称 | 核心作用 | 关联场景 |
|---|---|---|
get_metrology_object_param | 获取单个计量对象的参数 | 先读取模型全局配置，再读取单个对象参数，完整解析模型配置 |
六、与相似算子的核心差异
| 算子名称 | 核心区别 | 适用场景 |
|---|---|---|
get_metrology_model_param | 查询整个计量模型的全局通用参数 | 验证模型的相机参数、参考坐标系、缩放因子等全局配置 |
get_metrology_object_param | 查询单个计量对象的参数（如矩形尺寸、圆半径、测量Sigma值等） | 验证单个测量对象的配置，或解析单个对象的测量结果 |
七、总结
关键点回顾
get_metrology_model_param用于读取计量模型级全局参数，仅支持查询camera_param/plane_pose/reference_system/scale四个参数；- 输出参数
GenParamValue的类型随查询的参数名变化，需针对性处理（字符串/实数数组/单实数）； - 该算子是只读操作，不修改模型状态，且支持多线程安全调用，常与
set_metrology_model_param配合完成计量模型全局参数的“设置-验证”流程。
