1. 课程导入与HALCON环境搭建
工业缺陷检测系统的目标，是在产线节拍内稳定地判断产品表面是否存在划伤、脏污、缺料、尺寸偏差等缺陷，并把结果传递给PLC或上位机执行分选。它并不是“装一个软件、调几个参数”就能完成的任务，而是一条从成像到决策的完整链路。理解这条链路，是后续所有HALCON开发工作的前提。
1.1 工业缺陷检测系统的整体架构
一套典型的机器视觉缺陷检测系统可以划分为五个层次：被检对象与光源、成像单元、图像采集与传输、视觉处理软件、执行与通信。被检对象在传送带或转盘上运动，光源以特定角度照射，使缺陷与背景形成足够的对比度；工业相机配合镜头把光信号转换为数字图像；采集卡或GigE/USB接口把图像送入工控机；HALCON程序完成图像预处理、特征提取、缺陷判定；最后通过数字IO、Modbus TCP或Profinet把OK/NG信号发给PLC，由执行机构剔除不良品。
在这条链路中，HALCON处于“决策核心”的位置。它不负责打光，也不负责机械动作，但它决定了“什么样的图像算缺陷”。因此，环境搭建阶段必须保证三件事：软件能正常启动、许可证能正确加载、开发环境能编译并运行一个最小可用的图像读取与显示程序。这三件事任何一件出问题，后续的算法开发都无从谈起。
1.2 HALCON安装与许可证配置
HALCON由MVTec公司开发，当前主流版本为HALCON 20.11、22.11、23.11等。安装时需要注意：安装路径不要包含中文和空格，否则后续在Visual Studio中链接库文件时容易出现路径解析失败。安装程序会同时部署HDevelop（交互式开发环境）、HALCON库文件、示例图像和文档。
许可证是HALCON能否运行的关键。HALCON的授权方式主要有两种：加密狗（USB Dongle）和软授权文件（license file）。软授权通常是一个.dat或.lic文件，需要放到系统环境变量HALCON_LICENSE_FILE指定的路径下，或者放到HALCON安装目录的license子目录中。配置完成后，可以在HDevelop中执行get_system ('license_file', Info)来确认当前加载的许可证路径。
一个常见的坑是：安装了HALCON但许可证过期或未正确指向，HDevelop启动时会提示“No license found”。此时应检查环境变量是否生效（重启终端或IDE），以及许可证文件是否与当前HALCON版本匹配。不同版本的许可证通常不通用，这一点在项目部署到现场工控机时尤其要注意。
1.3 HDevelop与Visual Studio的集成
HDevelop是HALCON的交互式开发环境，适合快速验证算法思路。它的优势在于：可以单步执行算子、实时查看图像变量、用“算子窗口”搜索和插入算子。对于缺陷检测项目，通常先在HDevelop中完成图像读取、预处理、缺陷分割和特征计算的原型验证，再把代码导出为C++或C#，嵌入到Visual Studio工程中。
在Visual Studio中集成HALCON，需要完成以下配置：在项目属性中添加HALCON的include目录到“附加包含目录”；添加lib/x64-win64目录到“附加库目录”；在链接器中加入halconcpp.lib（C++）或halcondotnet.dll（C#）。如果使用C++，还需要确保运行时能加载halconcpp.dll，通常把HALCON的bin/x64-win64目录加入系统PATH，或把DLL复制到可执行文件同目录。
1.4 第一个图像读取与显示程序
环境搭建完成后，用一段最小程序验证整条链路是否通畅。在HDevelop中新建程序，输入以下代码：
read_image (Image, 'D:/vision/sample_01.png')
get_image_size (Image, Width, Height)
dev_open_window (0, 0, Width, Height, 'black', WindowHandle)
dev_display (Image)
disp_message (WindowHandle, 'Image loaded: ' + Width + ' x ' + Height, 'window', 12, 12, 'black', 'true')
这段代码做了四件事：从指定路径读取图像、获取图像宽高、打开一个与图像尺寸一致的显示窗口、在窗口中显示图像并叠加一行文字。如果运行后能看到图像和尺寸信息，说明HALCON安装、许可证、图像读取和显示链路都正常。
如果读取失败，常见原因有三类：路径使用了反斜杠但未转义（HALCON中建议用正斜杠/或双反斜杠\\）；图像文件不存在或格式不被支持；当前工作目录与预期不一致。可以用file_exists算子先判断文件是否存在，再执行read_image。
在Visual Studio中，对应的C++代码结构如下：
#include "HalconCpp.h"
using namespace HalconCpp;
int main()
{
HImage image;
try {
image.ReadImage("D:/vision/sample_01.png");
HTuple width, height;
image.GetImageSize(&width, &height);
HWindow window(0, 0, width[0].I(), height[0].I(), "black");
window.DisplayImage(image);
window.DispText("Image loaded", "window", 12, 12, "black", "true");
}
catch (HException &ex) {
printf("HALCON error: %s\n", ex.ErrorMessage().Text());
}
return 0;
}
注意C++版本中需要处理异常，否则一旦图像路径错误，程序会直接崩溃。把这段代码编译运行，如果窗口正常弹出并显示图像，就完成了从HDevelop原型到Visual Studio工程的第一次贯通。