HALCON算子read_metrology_model全解析
一、算子核心定位
read_metrology_model是HALCON 2D计量（2D Metrology）模块的文件IO类核心算子，核心功能是从指定文件（默认后缀.mtr）中读取经write_metrology_model保存的完整计量模型，生成可直接使用的计量模型句柄。它实现了2D计量模型的“持久化复用”——无需重复手动创建计量对象、配置测量参数，直接加载预定义的模型即可开展检测，大幅提升项目开发效率和模型复用性。
二、算法核心原理
- 文件有效性校验：检查输入的
FileName对应的文件是否存在、文件格式是否为HALCON计量模型专属的.mtr格式，且文件内容未损坏/篡改； - 模型数据解析：读取文件中存储的所有计量模型信息，包括：
- 计量模型全局参数（如相机参数、测量单位、投影方式）；
- 所有计量对象的配置（如对象类型：圆/矩形/线、初始位置、测量长度、Sigma、振幅阈值等）；
- 模糊规则参数（若有配置）；
- 内存实例化：在内存中创建新的计量模型实例，将解析后的所有参数加载到该实例中；
- 句柄生成：为内存中的计量模型实例分配唯一的
MetrologyHandle句柄，作为后续操作该模型的唯一标识； - 状态初始化：确保加载后的模型处于“就绪状态”，可直接调用
apply_metrology_model、get_metrology_object_indices等算子，无需额外初始化。
三、参数全详解
（一）输入参数（Input Parameters）
| 参数名 | 类型 | 功能说明 | 默认值 | 关键取值规则 | 注意事项 |
|---|---|---|---|---|---|
| FileName | filename.read → (string) | 要读取的计量模型文件名（含路径） | - | 取值规则： ▪ 支持相对路径（如 'model/circle_model.mtr'）或绝对路径（如'D:/halcon_model/circle_model.mtr'）；▪ 文件后缀必须为 .mtr（HALCON计量模型专属格式） | 1. 路径错误、文件不存在会抛出“文件未找到”异常； 2. 非 .mtr格式文件（如.txt/.dat）会抛出“文件格式无效”异常；3. 若仅传文件名（如 'circle_model.mtr'），则从当前工作目录读取 |
（二）输出参数（Output Parameters）
| 参数名 | 类型 | 功能说明 | 关联说明 |
|---|---|---|---|
| MetrologyHandle | metrology_model → (handle) | 加载后的计量模型句柄 | 1. 是后续所有2D计量算子（如apply_metrology_model/get_metrology_object_result）的核心输入；2. 每个 read_metrology_model调用生成独立的句柄，修改该模型不会影响原.mtr文件；3. 使用完毕需调用 clear_metrology_model释放，避免内存泄漏 |
四、使用关键注意事项
- 文件格式约束：仅能读取由
write_metrology_model保存的.mtr文件，其他格式（如手动修改的.mtr、重命名的.txt）会触发格式异常，无法加载； - 路径规则：
- 相对路径：相对于HALCON程序的“当前工作目录”（可通过
get_system('working_directory')查看）； - 绝对路径：建议在项目中使用绝对路径，避免因工作目录变化导致文件找不到；
- 相对路径：相对于HALCON程序的“当前工作目录”（可通过
- 句柄特性：
- 算子返回的句柄是独立的内存实例，对该模型的修改（如
set_metrology_object_param）仅作用于内存，不会同步到原.mtr文件； - 即使句柄作为输入参数，
set_metrology_object_param等算子仍可修改其内部状态；
- 算子返回的句柄是独立的内存实例，对该模型的修改（如
- 多线程特性：
- 多线程类型：可重入（能与非排他算子并行运行）；
- 多线程范围：全局（可从任意线程调用）；
- 无并行优化：单线程读取文件并加载模型，大模型（含多个计量对象）加载可能耗时稍长；
- 内存管理：加载后的模型句柄会占用内存，必须在使用完毕后调用
clear_metrology_model释放，否则会导致内存泄漏； - 返回值规则：执行成功返回
2（H_MSG_TRUE），文件不存在/格式错误/权限不足时直接抛出异常（而非返回错误码）。
五、算子调用链路
（一）前置算子（Possible Predecessors）
write_metrology_model：将配置好的计量模型保存为.mtr文件（read_metrology_model的必要前提，无此算子则无可用的.mtr文件）；
（二）后置算子（Possible Successors）
get_metrology_object_indices：获取加载模型中的计量对象索引；apply_metrology_model：使用加载的模型执行边缘检测与拟合；get_metrology_object_num_instances：统计检测到的实例数量；get_metrology_object_result：读取拟合后的测量结果；clear_metrology_model：释放计量模型句柄（收尾必备）。
六、与相似算子的核心差异
| 算子名称 | 核心区别 | 适用场景 |
|---|---|---|
read_metrology_model | 从.mtr文件加载已配置完成的计量模型，直接可用 | 量产项目、需复用模型的场景（避免重复配置参数） |
create_metrology_model | 创建空的计量模型，需手动调用add_metrology_object_*添加对象/配置参数 | 快速验证、临时创建模型的场景 |
write_metrology_model | 将内存中的计量模型保存为.mtr文件，实现持久化 | 配置好模型后，保存为文件供后续复用 |
八、总结
关键点回顾
read_metrology_model核心作用是读取.mtr格式的预保存计量模型，生成可直接使用的模型句柄，实现模型复用；- 仅支持读取
write_metrology_model保存的.mtr文件，路径错误/格式不符会触发异常； - 加载后的模型句柄需在使用完毕后调用
clear_metrology_model释放，避免内存泄漏。
