1. HALCON环境搭建与第一个图像读取显示程序
环境准备与安装要点
HALCON 的安装分为两部分：HALCON 运行时/开发库（由 MVTec 官方安装包提供）和 HDevelop 集成开发环境。安装时需注意以下关键点：
- 版本与授权：HALCON 需要许可证文件（license）。安装完成后首次启动 HDevelop 会提示选择许可证，通常使用本地 license 文件或授权服务器。无有效许可证时，程序可编译但运行算子会报授权错误。
- 安装路径：默认路径形如
C:\Program Files\MVTec\HALCON-XX.X（XX.X 为版本号）。路径中避免中文和空格，便于后续在工程中引用库文件。 - 环境变量：安装程序一般会自动配置
HALCONROOT（安装根目录）和HALCONARCH（平台架构，如x64-win64）。若手动部署，需要自行设置，否则编译时找不到头文件和库。 - 语言接口：HALCON 支持 C++、C#、Python 等接口。本课程以 HDevelop 脚本为主线，同时保留导出到 C++/Python 的路径。
验证安装是否成功的最直接方式：启动 HDevelop，若能正常打开主界面且不报许可证错误，即表示环境基本可用。
HDevelop 界面与程序结构
HDevelop 的程序由若干算子（operator）按顺序组成，每个算子完成一个图像处理动作。一个典型的图像读取显示流程包含三个核心算子：
| 算子 | 作用 | 关键参数 |
|---|---|---|
read_image | 从磁盘读取图像到图像变量 | 输出图像变量、文件路径 |
get_image_size | 获取图像宽高，用于验证读取结果 | 输入图像、输出 Width/Height |
dev_display | 在图形窗口显示图像 | 输入图像 |
此外还需要窗口管理算子：dev_close_window 关闭已有窗口，dev_open_window 打开指定大小的图形窗口，dev_set_window 激活窗口。这些算子不处理图像数据，但决定了显示行为。
完整可运行示例
下面是一段完整的 HDevelop 程序，实现读取一张图像、获取尺寸并显示。请将 ImagePath 替换为你本机实际存在的图像文件路径（HALCON 安装目录下通常自带示例图像，例如 %HALCONROOT%\images\clip.png）。
* 第一个HALCON程序：读取并显示图像
* 1. 关闭可能已存在的图形窗口
dev_close_window ()
* 2. 打开一个640x480的图形窗口
dev_open_window (0, 0, 640, 480, 'black', WindowHandle)
* 3. 指定图像路径（请替换为实际存在的文件）
ImagePath := 'C:/Program Files/MVTec/HALCON-XX.X/images/clip.png'
* 4. 读取图像
read_image (Image, ImagePath)
* 5. 获取图像尺寸，用于验证读取是否成功
get_image_size (Image, Width, Height)
* 6. 在窗口中显示图像
dev_display (Image)
* 7. 在窗口中输出图像尺寸信息
disp_message (WindowHandle, 'Width: ' + Width + ' Height: ' + Height, 'window', 12, 12, 'black', 'true')
运行方式：在 HDevelop 中按 F5 逐句执行，或按 F6 连续运行。执行到 read_image 后，变量窗口会出现 Image 变量；执行 dev_display 后，图形窗口应显示该图像。
关键步骤说明与结果判断
- 窗口句柄：
dev_open_window的输出WindowHandle是后续显示操作的依据。若省略窗口打开步骤，dev_display可能无窗口可显示或报错。 - 路径格式：HALCON 字符串中路径分隔符建议使用正斜杠
/或双反斜杠\\，单反斜杠会被当作转义字符。 - 读取成功判断：若路径错误，
read_image会抛出异常并在 HDevelop 状态栏显示错误信息。此时应检查文件是否存在、路径是否正确。 - 尺寸验证：
get_image_size返回的Width和Height应与图像实际分辨率一致。若显示为 0 或异常值，说明图像未正确读取。 - 显示结果：图形窗口中出现图像内容，且
disp_message在左上角显示宽高文本，即表示基础图像操作流程验证通过。
常见问题排查
| 现象 | 可能原因 | 处理方式 |
|---|---|---|
| 启动 HDevelop 报许可证错误 | 未配置 license 或 license 过期 | 检查 license 文件路径或联系授权服务器 |
read_image 报文件不存在 | 路径错误或文件被移动 | 确认路径，使用 HALCON 自带示例图像测试 |
| 图形窗口空白 | 未执行 dev_display 或窗口未激活 | 确认执行顺序，必要时用 dev_set_window 激活 |
| 编译时报找不到 halcon 库 | 环境变量未配置 | 检查 HALCONROOT 与 HALCONARCH |
从 HDevelop 到工程代码
HDevelop 中验证通过的流程可以导出为 C++、C# 或 Python 代码。导出时 HDevelop 会自动生成对应的库调用和窗口初始化代码。建议先在 HDevelop 中把读取、显示、尺寸获取这条链路跑通，再导出到目标语言工程中集成，这样可以避免在工程代码中反复调试图像路径和窗口参数。
完成本案例后，你应能独立完成：安装并验证 HALCON 环境、在 HDevelop 中读取任意本地图像、获取其尺寸并在图形窗口显示。这是后续所有图像处理案例的基础操作链路。