【Halcon-2D测量】read_metrology_model 函数功能（用于从指定文件中读取经模型）

HALCON算子read_metrology_model全解析

一、算子核心定位

read_metrology_model是HALCON 2D计量（2D Metrology）模块的文件IO类核心算子，核心功能是从指定文件（默认后缀.mtr）中读取经write_metrology_model保存的完整计量模型，生成可直接使用的计量模型句柄。它实现了2D计量模型的“持久化复用”——无需重复手动创建计量对象、配置测量参数，直接加载预定义的模型即可开展检测，大幅提升项目开发效率和模型复用性。

二、算法核心原理

1. 文件有效性校验：检查输入的FileName对应的文件是否存在、文件格式是否为HALCON计量模型专属的.mtr格式，且文件内容未损坏/篡改；
2. 模型数据解析：读取文件中存储的所有计量模型信息，包括：
   • 计量模型全局参数（如相机参数、测量单位、投影方式）；
   • 所有计量对象的配置（如对象类型：圆/矩形/线、初始位置、测量长度、Sigma、振幅阈值等）；
   • 模糊规则参数（若有配置）；
3. 内存实例化：在内存中创建新的计量模型实例，将解析后的所有参数加载到该实例中；
4. 句柄生成：为内存中的计量模型实例分配唯一的MetrologyHandle句柄，作为后续操作该模型的唯一标识；
5. 状态初始化：确保加载后的模型处于“就绪状态”，可直接调用apply_metrology_model、get_metrology_object_indices等算子，无需额外初始化。

三、参数全详解

（一）输入参数（Input Parameters）

（二）输出参数（Output Parameters）

四、使用关键注意事项

1. 文件格式约束：仅能读取由write_metrology_model保存的.mtr文件，其他格式（如手动修改的.mtr、重命名的.txt）会触发格式异常，无法加载；
2. 路径规则：
   • 相对路径：相对于HALCON程序的“当前工作目录”（可通过get_system('working_directory')查看）；
   • 绝对路径：建议在项目中使用绝对路径，避免因工作目录变化导致文件找不到；
3. 句柄特性：
   • 算子返回的句柄是独立的内存实例，对该模型的修改（如set_metrology_object_param）仅作用于内存，不会同步到原.mtr文件；
   • 即使句柄作为输入参数，set_metrology_object_param等算子仍可修改其内部状态；
4. 多线程特性：
   • 多线程类型：可重入（能与非排他算子并行运行）；
   • 多线程范围：全局（可从任意线程调用）；
   • 无并行优化：单线程读取文件并加载模型，大模型（含多个计量对象）加载可能耗时稍长；
5. 内存管理：加载后的模型句柄会占用内存，必须在使用完毕后调用clear_metrology_model释放，否则会导致内存泄漏；
6. 返回值规则：执行成功返回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：释放计量模型句柄（收尾必备）。

六、与相似算子的核心差异

八、总结

关键点回顾

1. read_metrology_model核心作用是读取.mtr格式的预保存计量模型，生成可直接使用的模型句柄，实现模型复用；
2. 仅支持读取write_metrology_model保存的.mtr文件，路径错误/格式不符会触发异常；
3. 加载后的模型句柄需在使用完毕后调用clear_metrology_model释放，避免内存泄漏。