【HALCON】 HALCON 教程：正确使用 `get_dict_tuple` 获取字典内容

📘 HALCON 教程：正确使用 get_dict_tuple 获取字典内容

在使用 HALCON 的过程中，get_dict_tuple 是一个非常常用的算子，它用于从字典中读取一个键对应的 元组值（HTuple）。但如果使用不当，很容易遇到错误，比如：

HALCON error #1302: Wrong value of control parameter 2 in operator get_dict_tuple

本文将详细介绍 get_dict_tuple 的正确用法，并结合实际错误案例，分析如何避免此类问题。

🧩 1. get_dict_tuple 是什么？

在 HALCON 中，字典（dict）是一种用于存储键值对的数据结构。get_dict_tuple 的作用是：

从字典中取出某个 key 对应的 tuple 值（如字符串、数字、数组等）

🧪 基本语法：

HOperatorSet.GetDictTuple(dictHandle, key, out value);

🔍 2. 示例：正确读取键值对

以下是一个完整示例：

// 创建一个字典并插入键值对
HTuple dict;
HOperatorSet.CreateDict(out dict);
HOperatorSet.SetDictTuple(dict, "DList", new HTuple("A", "B", "C"));

// 正确读取
HTuple dList;
HOperatorSet.GetDictTuple(dict, "DList", out dList);

Console.WriteLine(dList.ToString());  // 输出：A B C

⚠️ 3. 常见错误：HALCON error #1302

如果运行中遇到如下异常：

HALCON error #1302: Wrong value of control parameter 2 in operator get_dict_tuple

这里我想重点说下：
说明 get_dict_tuple 的第二个控制参数参数 key 错误，
HOperatorSet.GetDictTuple(dict, “DList”, out dList);
前两个就是控制参数，最后一个输出参数。
这里说的value of control parameter 2 就是 “DList”（halcon中数参数是从1开始数，而不是0，这里注意！）
为啥 "DList"报错呢，其实是我再某个函数分支直接返回了，还没来得及set_dict_tuple。所以找不到 “DList” 这个key！！！！

总的来说具体原因可能还有以下几种：

🧨 4. 错误分析：为什么会出错？

❌ 错误原因一：key 不存在或拼写错误

get_dict_tuple 要求 key 必须已存在且为元组类型的值。如果 DList 不存在，或字典中保存的不是元组（如图像、句柄等），都会报错。

✔️ 建议加上存在性判断：

HTuple keys;
HOperatorSet.GetDictParam(dict, "keys", out keys);

if (keys.TupleFind("DList") >= 0)
{
    HOperatorSet.GetDictTuple(dict, "DList", out dList);
}
else
{
    Console.WriteLine("Key 'DList' does not exist in the dictionary.");
}

❌ 错误原因二：字典未初始化或为默认值

如果 dictHandle 是一个默认未初始化的 HTuple()，也会出错。

✔️ 建议加判断：

if (!dict.IsInitialized())
{
    Console.WriteLine("字典尚未初始化！");
    return;
}

❌ 错误原因三：Key 存在，但类型不匹配

例如你存的是图像、区域、句柄，而不是元组类型，使用 get_dict_tuple 也会报错。此时应使用：

• get_dict_object：获取非元组的对象
• get_dict_param：获取字典属性（如所有键、类型等）

🛠️ 5. 推荐的安全使用方式

整合安全判断逻辑的推荐代码如下：

if (ResultDict.IsInitialized())
{
    HTuple keys;
    HOperatorSet.GetDictParam(ResultDict, "keys", out keys);

    if (keys.TupleFind("DList") >= 0)
    {
        HOperatorSet.GetDictTuple(ResultDict, "DList", out DList);
    }
    else
    {
        DList = new HTuple(); // 默认值
        Console.WriteLine("⚠️ 字典中未找到键 DList");
    }
}
else
{
    Console.WriteLine("❌ ResultDict 未初始化！");
}

🧾 6. 总结

📝 7. 参考链接

• 🔗 get_dict_tuple 官方文档（MVTec HALCON 18.11）
• 📚 HALCON 字典相关 API 索引

如果你在实际使用中也遇到了类似问题，欢迎留言交流或分享你是如何解决的，希望这篇文章对你有所帮助！

📌 欢迎收藏 + 关注，后续将分享更多 HALCON 调试与 C# 集成开发技巧！

ps：我发现一个问题，把在程序中直接通过HImage直接进行模板匹配，与图片指定一种格式保存到本地后加载模板匹配。得到的打分会有一些差异！
直接打分得到4.9分，保存后在打分得到5.3分。其实是保存导致的问题，我们下一篇讲解~~~