HALCON算子deserialize_metrology_model全解析
一、算子核心定位
deserialize_metrology_model是HALCON 2D计量（2D Metrology）模块的序列化/反序列化核心算子，核心功能是将通过serialize_metrology_model序列化后的计量模型（以序列化项句柄标识）进行反序列化还原，自动重建出与原模型配置完全一致的2D计量模型，并返回新的模型句柄。该算子适用于需要复用预配置计量模型的场景（如固定检测工位的参数化模型复用、批量检测任务的模型快速加载），或跨进程/跨线程/跨设备传输计量模型的场景（如工业检测系统中模型的远程部署、分布式检测节点的模型同步）。
二、算法核心原理
deserialize_metrology_model本质是序列化数据的解析与模型重建，核心逻辑如下：
- 读取输入的
SerializedItemHandle（序列化项句柄），解析其中存储的计量模型完整数据（包括图像尺寸配置、已添加的所有计量对象、测量参数（Sigma/振幅阈值）、模糊规则等）； - 基于解析出的完整数据，自动创建一个新的2D计量模型实例，1:1还原原模型的所有配置和状态；
- 生成新的计量模型句柄
MetrologyHandle，该句柄对应的模型可直接用于测量操作，无需重复配置参数。
三、参数全详解
（一）输入参数（Input Parameters）
| 参数名 | 类型 | 功能说明 | 默认值 | 关键取值规则 | 注意事项 |
|---|---|---|---|---|---|
| SerializedItemHandle | 序列化项句柄（serialized_item → handle） | 存储了序列化后计量模型数据的句柄 | - | 必须是由serialize_metrology_model生成的合法序列化项句柄 | 若句柄无效（如非计量模型序列化项、已释放的句柄），会直接抛出异常 |
（二）输出参数（Output Parameters）
| 参数名 | 类型 | 功能说明 | 关联说明 |
|---|---|---|---|
| MetrologyHandle | 计量模型句柄（metrology_model → handle） | 反序列化后重建的2D计量模型句柄 | 1. 该句柄对应的模型与序列化前的原模型配置完全一致（含图像尺寸、计量对象、测量参数等） 2. 可直接调用 apply_metrology_model执行测量，无需额外配置3. 使用完毕需调用 close_metrology_model释放内存 |
四、使用关键注意事项
- 序列化项合法性：输入的
SerializedItemHandle必须是由serialize_metrology_model生成的计量模型序列化项，若传入其他类型的序列化项（如图像、测量对象的序列化项），会触发参数异常； - 多线程特性：
- 多线程类型：可重入（可与非排他算子并行运行）；
- 多线程范围：全局（可从任意线程调用）；
- 无并行处理优化（单线程解析与重建）；
- 句柄资源管理：反序列化生成的
MetrologyHandle不会自动释放，所有测量操作完成后，必须调用close_metrology_model销毁句柄，避免内存泄漏； - 模型完整性：反序列化后的模型包含原模型的所有配置（图像尺寸、计量对象、Sigma/振幅阈值、模糊规则等），可直接调用
apply_metrology_model执行测量，无需重复调用set_metrology_model_image_size、add_metrology_object_*等配置算子； - 返回值规则：参数合法时返回
2 (H_MSG_TRUE)，参数非法（如无效序列化句柄、内存不足）时抛出异常。
五、算子调用链路
（一）前置算子（Possible Predecessors）
| 算子名称 | 核心作用 | 应用场景 |
|---|---|---|
serialize_metrology_model | 将配置好的计量模型序列化为序列化项句柄 | 本地模型复用（先序列化保存，再反序列化加载） |
fread_serialized_item | 从文件读取序列化项句柄 | 从本地文件加载预序列化的计量模型 |
receive_serialized_item | 从网络/进程间通信接收序列化项句柄 | 分布式检测系统中远程加载计量模型 |
（二）后置算子（Possible Successors）
| 算子名称 | 核心作用 | 应用场景 |
|---|---|---|
get_metrology_object_param | 获取反序列化模型中计量对象的参数 | 验证模型配置是否正确还原 |
get_metrology_object_fuzzy_param | 获取反序列化模型中计量对象的模糊参数 | 模糊测量场景下的参数验证 |
apply_metrology_model | 执行2D计量测量 | 基于还原的模型完成实际检测任务 |
close_metrology_model | 释放计量模型句柄 | 测量完成后回收内存资源 |
六、与相似算子的核心差异
| 算子名称 | 核心区别 | 适用场景 |
|---|---|---|
deserialize_metrology_model | 反序列化，将序列化项还原为完整配置的计量模型 | 加载/复用预配置的计量模型 |
serialize_metrology_model | 序列化，将配置好的计量模型转为序列化项句柄 | 保存/传输计量模型配置 |
create_metrology_model | 创建空的计量模型（无任何配置） | 从零开始配置新的计量模型 |
七、典型应用示例（HDevelop 代码）
八、总结
关键点回顾
deserialize_metrology_model是计量模型的反序列化算子，可将序列化后的模型还原为完整可用的2D计量模型；- 输入的
SerializedItemHandle必须是serialize_metrology_model生成的合法计量模型序列化项，否则会触发异常； - 反序列化生成的模型句柄需手动调用
close_metrology_model释放，且序列化项句柄也需调用close_serialized_item回收。
