一天一个halcon案例（2）

一、运行效果

输出效果。输出了几个参数。

二、代码详解

* *************************************************************** *
* ***** Halcon serialized data en/decryption workflow ***** *
* *************************************************************** *
*
* This example shows HALCON's data protection by encryption and
* decryption of serialized data. To this end, HALCON provides
* operators to encrypt and decrypt data contained in a
* serialized item.
*
* *************************************************************** *
*
dev_update_off ()
dev_close_window ()
*
* ******************************** *
* *** Password management *** *
* ******************************** *
*
* HALCON's encryption and decryption functionality is based on
* symmetric algorithms that use a password string. For security
* reasons, the password must not be stored directly within the
* hdev script. Safer alternatives are the usage of Hardware
* security modules, the system key chain on Linux, or reading it
* from the environment. We use the latter option in this
* example. Note that this will be an empty string if you do not
* set the environment variable before starting HDevelop.
tuple_environment ('HALCON_PASSWORD', Password)
*
* The password must be stored in a dictionary acting as secret.
Secret := dict{password: Password}
*
* ******************************** *
* *** Encryption DL model *** *
* ******************************** *
*
* A deep learning model must be serialized before it can be
* encrypted.
read_dl_model ('pretrained_dl_classifier_compact.hdl', DLModelHandle)
serialize_dl_model (DLModelHandle, SerializedItemHandle)
*
* Encrypt the serialized deep learning model and write to disk
* in encrypted form. The default file extension for encrypted
* data is 'henc'.
encrypt_serialized_item (SerializedItemHandle, Secret, EncryptedItemHandle)
write_encrypted_item (EncryptedItemHandle, 'dl_model.henc')
*
* ******************************** *
* *** Decryption DL model *** *
* ******************************** *
*
* Decrypt the encrypted deep learning model after reading it
* from disk.
read_encrypted_item ('dl_model.henc', EncryptedItemHandle1)
decrypt_serialized_item (EncryptedItemHandle1, Secret, SerializedItemHandle1)
*
* The deep learning model can be used after deserialization.
deserialize_dl_model (SerializedItemHandle1, DLModelHandle1)
*
* ************************ *
* *** Other types *** *
* ************************ *
*
* Note that the encryption and decryption work with any HALCON
* type that can be serialized, e.g., a tuple.
Tuple := ['some', 'information', 'in', 'text', 'form']
*
serialize_tuple (Tuple, SerializedItemHandle2)
encrypt_serialized_item (SerializedItemHandle2, Secret, EncryptedItemHandle2)
write_encrypted_item (EncryptedItemHandle2, 'tuple.henc')
*
read_encrypted_item ('tuple.henc', EncryptedItemHandle3)
decrypt_serialized_item (EncryptedItemHandle3, Secret, SerializedItemHandle3)
deserialize_tuple (SerializedItemHandle3, Tuple1)

英文翻译+代码解释：

* 关闭 Halcon 实时图形更新（图像、区域、轮廓自动刷新）。

为什么要用？

• 默认情况下，HDevelop 会每执行一行算子就刷新一次窗口，实时显示图像、ROI、轮廓等结果；
• 复杂程序（比如检测、匹配、循环）会因为频繁刷新变得非常卡顿；
• 加上dev_update_off()后，程序只在你主动刷新时才显示画面，速度大幅提升。

dev_update_off ()

* 关闭当前打开的 Halcon 图形窗口。

* 作用：清理窗口，避免运行时窗口堆积混乱。
dev_close_window ()

* 两个都是开发调试用，导出正式代码后会自动移除，不影响工业运行。

* 输入：环境变量名（字符串，如'HALCON_PASSWORD'）

* 输出：环境变量值（存入Password变量）

* 注意·：若环境变量不存在，Password为空元组

* tuple_environment读取操作系统环境变量，从系统中读取名为HALCON_PASSWORD的环境变量的值，存入变量Password，作为密码，好处：

• 代码中不硬编码密码，通过环境变量传递；
• 批量加密 / 解密 HALCON 程序、模型、训练数据；
• 多环境部署时，统一管理密码配置。

tuple_environment ('HALCON_PASSWORD', Password)

* dict字典：

• dict{ }创建一个空字典，准备存放数据。

• 'password'（左边）叫键（Key）= 给数据起的名字这里名字就叫：password。

• Password（右边）叫值（Value）= 真正存储的数据。

• 它为什么要这么写？

• 因为 HALCON 的加密算子encrypt_byte强制要求传入一个字典，并且里面必须包含 'password' 这个键。

Secret := dict{password: Password}

加密深度学习模型

* 输入：要读取的深度学习模型文件的路径和名称，文件扩展名通常是.hdl。（pretrained_dl_classifier_compact.hdl是一个用于图像分类的轻量级预训练模型）

* 输出：一个指向内存中深度学习模型的引用，后续所有对该模型的操作都需要通过这个句柄来进行。

* 作用：连接存储模型与HALCON应用的关键桥梁。

* 工作原理：1. 算子首先解析指定的模型文件，判断其是 HALCON 的原生格式 (.hdl) 还是 ONNX 格式。

2. 解析后，halocn会在内存中重建整个深度神经网络，包括其网络架构（如各层类型、连接方式）和训练好的权重参数。

3. 如果加载的是ONNX模型，halcon会执行一系列自动转换和优化，以提高模型在halcon环境中的性能和兼容性。

read_dl_model ('pretrained_dl_classifier_compact.hdl', DLModelHandle)

* 输入：待序列化的深度学习模型的句柄。

* 输出：序列化的句柄。它包含了模型的所有信息（网络结构、权重等），但以二进制数据流的形式性存在，可用于后续的存储或网络传输。

* 作用：将复杂的深度学习模型对象（包含网络结构、权重参数、训练状态等）“扁平化”转换为一个纯内存二进制数据块（序列化项），起到“打包”的作用。

* 注意：该算子只写到内存，并不会直接生成 .hdl或 .onnx等磁盘文件。
serialize_dl_model (DLModelHandle, SerializedItemHandle)

* 输入：SerializedItemHandle：待加密的“原始序列化项”句柄；Secret：加密秘钥（通常为string类型）。这是对加密的“密码”，解密时必须使用完全相同的字符串。

* 输出：加密后的序列化项句柄。这是一个加密二进制数据容器，原始数据已被算法打乱，无法直接读取。

* 作用：对内存中的序列化二进制数据进行对称加密，生成受密码保护的密文数据。它保护的是“二进制字节流”，而非文件。它不产生硬盘文件，仅将内存中的句柄内容进行密码学转换。Halcon内部通常采用强对称加密算法（如AES-256），确保即使密文被第三方获取，在没有Secret的情况下也无法还原模型内容。

* 特别提醒与安全建议：密钥管理----Secret直接写在代码里（硬编码）是不安全的。工业应用中建议从环境变量、加密配置文件或硬件加密狗中动态读取Secret。

encrypt_serialized_item (SerializedItemHandle, Secret, EncryptedItemHandle)

* 输入：待写入的“加密序列化项”句柄。

* 输出：该算子仅执行磁盘写入操作，不返回任何句柄或数值。

* 核心作用：将内存中加密过的二进制数据持久化保存到操作系统磁盘文件中。它将句柄指向的密文数据“落地”为一个实实在在的文件。写入完成后，该文件是自包含的、加密的二进制文件，无法用文本编辑器查看，也无法被未授权方直接反序列化。

* 文件扩展名细节：Halcon官方文档推荐使用 .henc来区分普通序列化文件和加密文件。这便于后续维护人员一目了然知道该文件需要秘钥。
write_encrypted_item (EncryptedItemHandle, 'dl_model.henc')

解密深度学习模型

* 输入：要读取硬盘上的加密模型文件。

* 输出：新创建的加密项句柄。

* 主要作用：打开硬盘文件，读取其二进制头信息，校验文件是否为合法的 Halcon 加密项，将文件中的全部密文数据原封不动地载入内存，并与一个句柄 ID 绑定。

* 重要结论：此时的EncryptedItemHandle1仍然是完全加密的密文状态。它不是模型，不是可读数据，仅仅是一个装载了加密二进制数据的容器句柄。

read_encrypted_item ('dl_model.henc', EncryptedItemHandle1)

* 输入：EncryptedItemHandle1：待解密的加密项句柄；Secret：包含解密参数（如密码）的字典，密码需存储在键'password'下，密钥必须与加密时输入的字符串完全一致。

* 输出：SerializedItemHandle1解密后生成的序列化项句柄，该句柄指向内存中还原出的原始二进制数据，可直接用于后续的反序列化操作。

* 主要作用：将内存中的加密密文句柄还原为原始明文序列化数据。该算子执行 AES 对称解密算法，将受密码保护的二进制字节流恢复为 Halcon 可识别的序列化格式。

*注意：该算子不修改输入的原始密文句柄 (EncryptedItemHandle1)，仅生成一个新的明文句柄输出。
decrypt_serialized_item (EncryptedItemHandle1, Secret, SerializedItemHandle1)

* 输入：代表内存中待反序列化的模型数据。

* 输出：深度学习模型句柄，这是算子执行成功后生成的、可在Halcon中直接使用的模型实例。

* 核心作用：将内存中“序列化项”句柄反序列化为一个可用的深度学习模型。其功能与read_dl_model了类似，区别在于后者从文件读取模型，而此算子从序列化句柄读取。

deserialize_dl_model (SerializedItemHandle1, DLModelHandle1)

* 右侧：由5个字符串常量组成的字面量列表，在赋值时作为数据源输入。

* 左侧：赋值完成后被创建或更新的Halcon变量，其值为包含5个字符串元素的元组。

* 核心作用：在Halcon中创建一个一维字符串元组（即字符串数组）。Halcon的元组是动态类型的，支持字符串、整数、浮点数或混合类型。该语句将5个独立的文本片段打包成一个有序集合，以便后续通过索引批量访问或作为参数传递给其他算子。

* 字面量列表：意思是，这个列表里的每一个元素，都是你直接在代码里手写出来的具体值（5 个字符串字面量）。计算机不需要去别的地方读取文件、不需要调用函数、不需要做运算，直接就能拿到这 5 个字符串。

Tuple := ['some', 'information', 'in', 'text', 'form']

* 输入：之前定义的字符串元组。

* 输出：一个序列化句柄，代表内存中转化后的二进制字节流。

* 核心作用：将Halcon的高级数据类型“扁平化”为底层二进制数据。这是为了给后续的加密文件和文件写入提供统一的数据格式。

* 注意：此阶段数据完全明文，任何内存分析工具均可读取其内容。

serialize_tuple (Tuple, SerializedItemHandle2)

* 输入：SerializedItemHandle2（明文二进制句柄）+Secret（加密密钥字符串）

* 输出：一个加密序列化项句柄，内容已被AES对称加密算法打乱。

* 核心作用：对上一步的明文二进制流进行数学混淆，使其变为不可读的密文。

* 关键：原始明文句柄SerializedItemHandle2不会被修改或自动释放，它与新生成的密文句柄EncrypedItemHandle2同时存在于内存中。
encrypt_serialized_item (SerializedItemHandle2, Secret, EncryptedItemHandle2)

* 输入：EncryptedItemHandle2（加密句柄）+文件名字符串“tuple.henc”.

* 输出：无返回值。

* 核心作用：将EncryptedItemHandle2指向的密文数据落地为磁盘文件。写入完成后，tuple.henc是一个自包含的二进制加密文件，无法用记事本打开，第三方在无密钥情况下无法还原内容。
write_encrypted_item (EncryptedItemHandle2, 'tuple.henc')

* 输入：硬盘上的加密文件名。

* 输出：一个加密句柄，代表内存中加载的密文数据。

* 核心作用：从硬盘读取.henc加密文件，并在内存中创建一个新的加密项句柄。该文件必须由write_encrypted_item算子创建。

read_encrypted_item ('tuple.henc', EncryptedItemHandle3)

* 输入：EncryptedItemHandle3（加密项句柄）+Secret（解密密钥，以字典形式传递）。

* 输出：SerializedItemHandle3一个序列化项句柄，代表解密后的明文二进制数据。

* 核心作用：使用密钥将加密项解密为系列化项。密钥必须以密码字符串的形式，通过字典键'password'传递。
decrypt_serialized_item (EncryptedItemHandle3, Secret, SerializedItemHandle3)

* 输入：一个序列化项句柄

* 输出：恢复后的原始Halcon元组。

* 核心作用：将序列化句柄中的数据反序列化，还原为原始元组。
deserialize_tuple (SerializedItemHandle3, Tuple1)

关于加密机制，官方并未公布其底层运算规则。