3. 从HDevelop到工程代码

在HDevelop里调通一段视觉程序，只是完成了“开发态”的验证；真正交付给产线或上位机软件时，代码必须进入“运行态”。这两者的差别不只是语言不同，更在于执行模型、参数来源、错误处理和生命周期管理的根本差异。理解这一点，才能避免“HDevelop里跑得好好的，导出到C++就报错或结果不一致”这类典型问题。

开发态与运行态的本质差异

HDevelop是解释执行的交互环境，变量是动态类型，图像、区域、XLD等对象由HALCON内部统一管理，操作符调用时自动完成类型推断与内存分配。而导出到C++/C#/Python后，代码变成编译或脚本语言中的静态调用，HALCON对象需要显式声明为HObject、HTuple等类型，图像采集、显示、异常处理都要由宿主程序负责。更关键的是，HDevelop中“程序结束即释放”的隐式生命周期，在工程代码中必须由开发者显式控制，否则会出现句柄泄漏或图像数据被提前释放的问题。

因此，从HDevelop到工程代码不是简单的“翻译”，而是一次执行模型的迁移。迁移的核心工作包括三件事：把过程（Procedure）导出为可调用的接口、把参数从交互变量转为函数签名、把错误处理从HDevelop的异常对话框转为宿主语言的异常或返回码机制。

程序导出的三种典型路径

HALCON提供了多种导出方式，选择哪一种取决于目标语言和工程结构。

• 导出为C++代码：在HDevelop中通过“文件→导出→C++”生成.cpp和.h文件。导出的代码会把每个过程转成一个函数，参数以HObject*和HTuple*指针形式传递。适合需要高性能、与现有C++视觉框架集成的场景。
• 导出为C#代码：通过“导出→C#”生成.cs文件，使用HObject和HTuple类。适合基于WinForm/WPF的上位机软件，调用方式更接近面向对象。
• 导出为Python代码：通过“导出→Python”生成.py文件，使用halcon模块。适合快速原型、算法验证或与深度学习框架配合。

无论哪种路径，导出的代码都只是“骨架”，真正的工程化还需要把过程封装成类或模块，并处理参数传递和错误恢复。

过程封装：从脚本到可复用接口

HDevelop中的过程（Procedure）是代码复用的基本单位。一个设计良好的过程应该满足：输入参数明确、输出参数明确、不依赖全局变量、内部错误可被调用者感知。导出时，HDevelop会自动把过程的输入输出参数映射为函数参数，但开发者需要检查映射是否符合工程预期。

例如，一个用于“定位Mark点”的过程，输入是图像Image和模板句柄ModelID，输出是Row、Column、Angle和Score。导出到C++后，函数签名大致如下：

void locate_mark(const HObject& Image, const HTuple& ModelID,
                 HTuple* Row, HTuple* Column,
                 HTuple* Angle, HTuple* Score)
{
    // 导出的HALCON算子调用序列
    HObject Region;
    HTuple HomMat2D;
    find_shape_model(Image, ModelID, ... , &Row, &Column, &Angle, &Score);
}

这里要注意：Row、Column等输出参数使用指针，是因为HALCON的C++接口用指针返回多值。调用者必须保证这些指针指向有效的HTuple对象，否则会崩溃。这是开发态与运行态最容易出问题的地方之一。

参数传递的三种模式

在工程代码中，参数传递需要区分三种模式，它们对应不同的内存和生命周期管理策略。

句柄传递是最容易出问题的。例如create_shape_model返回的ModelID是一个句柄，它在HDevelop中由环境自动回收，但在C++中必须调用clear_shape_model(ModelID)显式释放。如果忘记释放，长时间运行会累积内存泄漏；如果提前释放，后续find_shape_model会抛出异常。

开发态到运行态的迁移检查清单

为了把迁移工作做得可复现，建议按以下清单逐项检查。这份清单可以直接用于项目评审或代码走查。

接口封装的实际结构

下面这张图展示了从HDevelop过程到工程代码的迁移路径，以及参数在开发态与运行态之间的传递关系。图中左侧是HDevelop中的过程定义，中间是导出后的函数接口，右侧是宿主程序中的调用与生命周期管理。重点观察句柄参数和图像参数在两侧的不同处理方式。

图中最值得关注的是中间列到右侧列的“封装”和“管理”两个箭头。导出接口只是把HDevelop算子调用翻译成目标语言，而真正的工程化需要在外面再包一层：用类管理句柄生命周期，用参数校验拦截非法输入，用异常捕获防止单次失败导致整个程序退出。这一步做得好，代码才能从“能跑”变成“可维护、可复用”。

一个可复用的封装示例

下面给出一个C++封装类的骨架，它把导出的过程函数包在类里，构造时创建模板，析构时释放，调用时做参数校验。这个结构可以直接套用到其他视觉任务上。

class MarkLocator {
public:
    MarkLocator(const char* modelFile) {
        read_shape_model(modelFile, &modelID_);
    }
    ~MarkLocator() {
        if (modelID_.Length() > 0)
            clear_shape_model(modelID_);
    }
    bool locate(const HObject& image, double& row, double& col,
                double& angle, double& score) {
        if (image.CountObj() == 0) return false;
        HTuple r, c, a, s;
        try {
            find_shape_model(image, modelID_, 0, 0, 0.5,
                             1, 0.5, "least_squares", 0, 0.9,
                             &r, &c, &a, &s);
        } catch (HException& e) {
            return false;
        }
        if (s.Length() == 0 || s[0].D() < 0.7) return false;
        row = r[0].D(); col = c[0].D();
        angle = a[0].D(); score = s[0].D();
        return true;
    }
private:
    HTuple modelID_;
};

这个类把“创建模板—查找—释放模板”的生命周期收拢在对象内部，调用者只需要locate()并检查返回值。注意find_shape_model的Score阈值设为0.7，这是示例值，实际项目中应根据Mark点对比度和光照稳定性调整。如果分数低于阈值，函数返回false，上层可以决定重拍、报警或跳过。

最后要强调的是，开发态与运行态的差异不是一次性的迁移问题，而是持续存在的。HDevelop中调参、验证新算子、优化ROI，最终都要同步到工程代码中。建立“HDevelop过程—导出接口—封装类—业务调用”的四层结构，并保持每层职责清晰，才能让视觉项目在迭代中不失控。