4、第一个动态调用程序：编写最简单的HDevEngine程序，加载并执行一个HDevelop脚本，获取结果

当开发者第一次接触HDevEngine时，最容易产生的困惑是：它和直接运行HDevelop软件到底有什么区别？本质上，HDevEngine是一个可嵌入的运行时库，它允许你在C++、C#、Python等宿主语言中创建HDevelop脚本的执行环境，加载 .hdvp 或 .hdev 程序，并像调用普通函数一样获取图像处理结果。本章将带领你从零开始，编写一个最小可用的HDevEngine程序，完成“加载脚本→设置输入→执行→获取输出”的完整闭环。这个最小程序将成为后续所有复杂应用（如多线程调度、结果可视化、异常恢复）的骨架。

上图展示了HDevEngine动态调用的核心链路。可以看到，宿主程序与HDevelop脚本之间通过引擎API进行双向通信：宿主负责输入数据准备和输出结果消费，脚本负责图像处理算法实现。这种架构使得算法工程师可以在HDevelop中快速迭代算法，而软件工程师则专注于系统集成和业务逻辑，两者通过明确定义的接口协作。

4.1 核心原理：HDevEngine的运行时模型

HDevEngine的运行时模型可以概括为“宿主驱动、脚本执行、数据桥接”。与HDevelop交互式环境不同，HDevEngine将脚本视为一个可调用的计算单元。其底层实现基于HALCON的运行时虚拟机，该虚拟机能够解析并执行HDevelop脚本编译后的字节码。

理解这一模型需要把握三个关键点：

• 程序对象（HDevProgram）：代表一个已加载的 .hdvp 文件，是脚本的静态表示。它包含过程定义、全局变量声明和初始化代码。
• 程序实例（HDevProgramInstance）：由HDevProgram创建，代表一次独立的执行上下文。每次调用Execute()都会在该实例中运行，实例之间互不干扰，这为多线程并发执行提供了基础。
• 变量桥接机制：通过SetInputIconicVar()、SetInputCtrlVar()等接口将宿主语言的数据传入脚本，通过GetOutputIconicVar()、GetOutputCtrlVar()等接口取回结果。这种桥接支持HALCON的HImage、HRegion等图像数据类型，也支持HTuple（元组）类型的控制变量。

值得注意的是，HDevEngine并不支持HDevelop中的所有交互式功能，例如可视化窗口、算子断点调试等。它专注于“无头执行”——即不依赖图形界面的批处理或嵌入式运行。因此，在编写脚本时，应避免使用dev_open_window、disp_obj等显示相关算子，而应将结果通过输出参数返回。

4.2 操作流程：从零搭建第一个动态调用程序

下面以C++为例，演示一个完整的HDevEngine调用流程。假设我们有一个HDevelop脚本 measure_part.hdvp，其中定义了一个主过程 measure_part，输入为一张图像，输出为区域的面积和中心坐标。

步骤一：环境准备

在项目配置中，需要链接HDevEngine库。以Visual Studio为例，需要添加头文件路径和库文件路径，并链接 halcon.lib 和 hdevengine.lib。同时，确保HALCON的运行时DLL（如 halcon.dll）位于系统路径或应用程序目录中。

步骤二：初始化引擎并加载脚本

#include "HDevEngine.h"
using namespace HalconCpp;

// 1. 创建引擎实例
HDevEngine engine;

// 2. 设置脚本搜索路径（可选，但推荐）
engine.SetProcedurePath("C:/HDevelopScripts/");

// 3. 加载脚本文件
HDevProgram program("measure_part.hdvp");

// 4. 创建程序实例（执行上下文）
HDevProgramInstance instance(program);

步骤三：设置输入参数

假设脚本的主过程名为 measure_part，它接受一个图像输入和一个阈值控制参数：

// 准备输入图像（从文件读取）
HImage image;
image.ReadImage("part_01.png");

// 设置图标变量输入（图像）
instance.SetInputIconicVar("Image", image);

// 设置控制变量输入（阈值）
HTuple threshold = 128;
instance.SetInputCtrlVar("Threshold", threshold);

步骤四：执行脚本

// 执行主过程
instance.Execute("measure_part");

步骤五：获取输出结果

// 获取图标变量输出（区域）
HRegion region = instance.GetOutputIconicVar("Region");

// 获取控制变量输出（面积和中心坐标）
HTuple area, row, col;
area = instance.GetOutputCtrlVar("Area");
row = instance.GetOutputCtrlVar("Row");
col = instance.GetOutputCtrlVar("Col");

// 打印结果
std::cout << "Area: " << area[0].I() << ", Row: " << row[0].D() 
          << ", Col: " << col[0].D() << std::endl;

步骤六：资源清理

HDevEngine使用RAII机制管理资源，当 HDevProgramInstance 和 HDevProgram 对象超出作用域时，会自动释放底层资源。但在长时间运行的应用程序中，建议显式调用 instance.Reset() 来清理执行状态，避免内存碎片化。

步骤	API调用	说明	常见错误
初始化	HDevEngine()	创建引擎实例	DLL缺失导致构造失败
加载脚本	HDevProgram(path)	加载并编译.hdvp文件	路径错误或脚本语法错误
创建实例	HDevProgramInstance(program)	创建独立执行上下文	程序对象已被销毁
设置输入	SetInputIconicVar / SetInputCtrlVar	传入图像或控制变量	变量名与脚本不匹配
执行	Execute(procedure_name)	运行指定主过程	过程名不存在或执行异常
获取输出	GetOutputIconicVar / GetOutputCtrlVar	取回计算结果	输出变量未定义或类型不匹配

4.3 案例拆解：一个真实的零件测量场景

让我们通过一个完整的案例来巩固上述知识。假设某工厂需要检测金属垫片的内径，原始图像由工业相机采集，分辨率为1280×1024，背景为均匀的暗色传送带。HDevelop脚本 measure_washer.hdvp 的主过程 measure_washer 实现以下算法：

1. 使用 read_image 读取图像（实际由宿主传入）；
2. 使用 threshold 将垫片区域从背景中分割出来；
3. 使用 connection 将连通域分离；
4. 使用 select_shape_max 选择面积最大的区域作为目标垫片；
5. 使用 inner_circle 计算最大内接圆，得到内径和圆心坐标。

初始现象与目标：人工检测效率低且易疲劳，需要实现自动化在线测量。目标是在100ms内完成单次测量，精度要求±0.05mm。

关键输入数据：

• 图像：8位灰度图，垫片区域灰度值约180-220，背景灰度值约30-50。
• 阈值参数：初始设定为100，可根据光照变化动态调整。
• 相机标定系数：0.05mm/pixel。

宿主程序实现要点：

// 创建引擎和实例（复用，避免重复加载）
static HDevEngine engine;
static HDevProgram program("measure_washer.hdvp");
static HDevProgramInstance instance(program);

// 在线测量函数
bool MeasureWasher(const HImage& img, double& inner_diameter_mm, 
                   double& center_x, double& center_y) {
    try {
        // 设置输入
        instance.SetInputIconicVar("Image", img);
        instance.SetInputCtrlVar("Threshold", 100);
        
        // 执行
        instance.Execute("measure_washer");
        
        // 获取结果（像素单位）
        HTuple radius_px, row, col;
        radius_px = instance.GetOutputCtrlVar("Radius");
        row = instance.GetOutputCtrlVar("Row");
        col = instance.GetOutputCtrlVar("Col");
        
        // 转换为物理单位
        inner_diameter_mm = 2 * radius_px[0].D() * 0.05;
        center_x = col[0].D() * 0.05;
        center_y = row[0].D() * 0.05;
        
        return true;
    } catch (HDevEngineException& e) {
        // 记录异常日志
        std::cerr << "HDevEngine error: " << e.message() << std::endl;
        return false;
    }
}

分析判断过程：在初次运行时，发现测量结果偶尔出现巨大偏差。通过日志定位，发现是脚本中 select_shape_max 在图像中出现多个高亮反光区域时，选择了错误的连通域。解决方案是在脚本中增加面积范围过滤：select_shape (SelectedRegions, Regions, 'area', 'and', 5000, 50000)，排除过小或过大的干扰区域。

结果对比：优化前，测量成功率约92%，平均耗时85ms；优化后，成功率提升至99.5%，平均耗时88ms（增加了一个过滤算子，耗时略有增加但可接受）。

风险与代价：动态调用虽然灵活，但每次Execute()都有一定的调用开销（约0.5-2ms）。对于高速产线（如每秒处理30帧），建议使用HDevEngine的批处理模式或直接调用HALCON算子以避免脚本解释开销。

4.4 常见误区与总结复盘

在编写第一个HDevEngine程序时，开发者常陷入以下误区：

• 误区一：混淆HDevProgram和HDevProgramInstance。前者是静态的脚本定义，后者是动态的执行上下文。如果多个线程共享同一个Instance，会导致数据竞争。正确做法是每个线程创建独立的Instance。
• 误区二：忽略异常处理。HDevEngine执行脚本时可能抛出多种异常（如图像尺寸不匹配、算子参数错误）。未捕获的异常会导致程序崩溃。务必使用try-catch包裹Execute调用。
• 误区三：在脚本中使用显示算子。如 dev_display、disp_obj 等，这些在HDevEngine中无效且会拖慢执行速度。应通过输出参数返回结果，由宿主负责可视化。
• 误区四：频繁加载和销毁Program对象。加载脚本涉及文件I/O和编译，开销较大。应在程序初始化时加载一次，后续复用。

总结复盘：本章通过一个最小程序，完整演示了HDevEngine的六大核心步骤：初始化、加载、设参、执行、取参、清理。这个流程是所有HDevEngine应用的基础。在实际项目中，建议将引擎封装为单例或服务类，统一管理脚本生命周期和异常策略。同时，在HDevelop中编写脚本时，应遵循“输入参数化、输出明确化、过程单一化”的原则，使脚本易于测试和复用。

掌握本章内容后，你已经具备了HDevEngine动态调用的基本能力。下一阶段，可以尝试将多个脚本组合调用，或探索HDevEngine的线程安全模型，为构建高性能视觉系统打下基础。