【HALCON 实战入门】2. HALCON 快速入门-开发者社区

欢迎订阅【HALCON 实战入门】专栏：
1. HALCON 简介与安装
2. HALCON 快速入门
3. 图像读取、显示与保存
4. 图像采集
5. 交互式与 ROI

2. HALCON 快速入门

第 1 章：安装 HALCON
第 2 章：HALCON 架构
- 2.1 算子
- - 2.1.1 参数与数据结构
- 2.2 扩展包
- 2.3 语言接口
- - 2.3.1 HALCON/Python 接口
  - 2.3.2 HALCON/C 接口
  - 2.3.3 HALCON/C++ 接口
  - 2.3.4 HALCON/.NET 接口
- 2.4 图像采集接口
- 2.5 专用 I/O 接口
第 3 章：应用程序开发
- 3.1 HDevelop
- 3.2 示例程序
- - 3.2.1 在 HDevelop 中创建原型
  - 3.2.2 准备 Visual Studio 项目
  - 3.2.3 导出库项目
  - 3.2.4 将库项目集成到 Visual Studio 中
第 4 章：学习指南

本文译自：HALCON：Quick Guide，版权属于 Copyright © 2003-2025 by MVTec Software GmbH, Munich, Germany。
有关 HALCON 的更多信息，请访问：https://www.halcon.com

关于本手册
本手册对 HALCON 进行介绍，面向无 HALCON 使用基础的初学者。
本手册包括以下主题：

HALCON 安装：本章介绍 MVTec 软件管理器（SOM）。
HALCON 架构：本章讲解理解 HALCON 及其工作原理所需的部分理论基础。
应用开发方法：本章阐述基于 HALCON 进行开发的三种基本方式，并通过首个编程实例引导您上手。
后续学习指引：本章列出可参考的其他信息来源。

第 1 章：安装 HALCON

HALCON 是德国 MVtec 公司开发的一款综合性的机器视觉标准软件，拥有全球通用的集成开发环境（HDevelop）。

对于 Linux 和 Windows 用户，我们建议通过MVTec 软件管理器（SOM）下载并安装 HALCON。SOM 是一款用于软件包的安装管理器，可访问远程产品目录，并支持软件包的下载与安装等功能。通过 SOM 安装 HALCON 的详细步骤说明，请参阅《安装指南》。

注：通过 SOM 安装 HALCON 的详细步骤说明，请参阅：【HALCON 实战入门】1. HALCON 简介与安装。

第 2 章：HALCON 架构

HALCON 的基础架构如图 2.1 所示。其核心部分为图像处理库，包含超过 2000 个算子。
通过扩展包可以开发自定义算子。
在应用程序中，可以通过各类语言接口调用这些算子，例如 HALCON/C++ 或 HALCON/Python。这些接口库支持以对应编程语言的典型编程风格直接使用算子。
针对图像采集设备的接入，HALCON 提供图像采集接口，可以使用统一的方式操控各类不同的图像采集设备。包含设备专属实现逻辑的库会在需要时动态加载。类似地，I/O 设备通过专用 I/O 接口进行访问。

图 2.1：HALCON 基础架构。

2.1 算子

HALCON 库中的所有功能都是通过算子（Operators）完成的。
每个算子都包含多种实现方法，可以通过参数选择。
所有算子的列表可以在 HALCON 算子参考手册（HALCON Operator Reference）中查看，该手册提供了 HDevelop, .NET, Python, C++, 和 C syntax 接口语法。

算子的特性如下：

算子之间不存在层级关系。
算子自然会形成逻辑分组。
算子的设计遵循开放式架构规范。
许多算子可自动实现并行化处理，且对用户透明。
算子的输入、输出参数遵循标准化排序规则：输入图像参数、输出图像参数、输入控制参数、输出控制参数。

2.1.1 参数与数据结构

HALCON 包含两类基础参数类型：图像类数据与控制类数据。

图像类数据包含图像、区域和 XLD（扩展线型描述，eXtended Line Description）。
- 图像
  图像主要由多个通道构成，即由包含像素值的矩阵组成。
  同一幅图像的所有通道尺寸均相同。关于像素与通道的详细说明，请参阅 HALCON 算子参考手册中的 “图像” 章节。
  每幅图像均可通过 ** 感兴趣区域（ROI）** 指定需要处理的图像部分。关于 ROI 处理的详细内容，见《解决方案指南 I（Solution Guide I）》中的 “感兴趣区域（ROI）” 章节。
- 区域
  区域是一组像素的集合。
  区域内的像素无需相互连通，即使是任意离散的像素集合也可作为单个区域处理。使用 connection 算子可将一个区域拆分为多个连通区域，即由连通像素构成的组件。
- XLD
  XLD 包含所有基于轮廓与多边形的数据。
  亚像素精度算子（如 edges_sub_pix）会以 XLD 数据形式返回轮廓。轮廓是一系列由线段连接的二维控制点，控制点之间的间距通常约为一个像素。
  XLD 对象除控制点外，还包含局部属性与全局属性。典型示例包括控制点的边缘幅值、轮廓段的回归参数等。
  除提取 XLD 对象外，HALCON 还支持对其进行后续处理，例如根据指定特征范围筛选轮廓、将轮廓分割为直线、圆弧、多边形或平行线等。
控制类数据包含句柄（handles）以及整数、浮点数、字符串等基本数据类型。
- 句柄（handles）是对复杂数据结构的引用，例如图像采集接口的连接，或基于形状匹配的模板。
  出于效率与数据安全考虑，算子之间传递的并非完整数据结构，而仅传递句柄。
  句柄是具有特定意义的标识值，禁止修改，并且在不同运行环境、不同软件版本之间可能存在差异。当所有引用均被覆盖后，句柄会被自动释放。
  使用句柄的典型场景包括：图形窗口、文件、套接字、图像采集接口、OCR、OCV、测量以及匹配。

2.2 扩展包

HALCON 包含了丰富的算子库，也可以通过自定义新算子进行扩展。

HALCON 提供了扩展包接口，支持以扩展包的形式集成使用 C 语言开发的新算子。扩展包接口包含若干预定义例程与宏，便于在 C 语言中便捷处理图像数据与内存对象。新算子成功集成后，即可与其他 HALCON 原生算子一样正常使用。

有关扩展算子库的详细信息，请参阅《扩展包程序员手册（Extension Package Programmer’s Manual）》。

2.3 语言接口

HALCON 提供了各类语言接口，原生支持 Python、C、C++ 及 .NET 语言接口，可以在应用程序中直接调用 HALCON 算子并使用其数据类型。
开始开发前，我们建议先查看可直接运行的示例程序。通过示例，您可以了解项目的搭建方式以及算子与数据类型的使用方法。
为符合对应编程语言的通用规范，不同语言接口在类型名称、类、算子命名规则等方面可能会存在差异。各支持编程语言对应的算子原型在《HALCON 算子参考手册（HALCON Operator Reference）》中提供了详细说明。

2.3.1 HALCON/Python 接口

Python 接口凭借其简洁性和快速原型开发能力脱颖而出。在导入 HALCON/Python 模块后，HALCON 算子可直接作为独立函数进行调用。
注意：HALCON/Python 中的算子参数被划分为函数参数（输入）与返回值（输出）两部分。

示例：以下代码读取一幅图像，并计算其中的连通区域数量。本例程的前提条件与详细说明，请参阅《程序员指南（Programmer’s Guide）》中的：Part 4, 首个示例程序。

img=ha.read_image('pcb')region=ha.threshold(img,0,122)num_regions=ha.count_obj(ha.connection(region))print(f'Number of Regions:{num_regions}')

2.3.2 HALCON/C 接口

C 语言接口是 HALCON 支持的最简接口。HALCON 算子的本身就是由 C 语言实现的，C 语言是原生接口，支持最好。
每个算子对应一个或两个全局函数，算子名称与参数顺序均与 HDevelop 语言相同。

示例：以下代码读取一幅图像，并计算其中的连通区域数量。
本例程的前提条件与详细说明，请参阅《程序员指南（Programmer’s Guide）》中的：Part 5, 首个示例程序。

Hobject img;read_image(&img,"pcb");Hobject region;threshold(img,&region,0,122);Hobject connected_regions;connection(region,&connected_regions);Hlong num_regions=0;count_obj(connected_regions,&num_regions);printf("Number of Regions: %"PRIdPTR"\n",num_regions);

2.3.3 HALCON/C++ 接口

C++ 接口比 C 接口复杂得多，应用了 C++ 面向对象编程的优点，包括自动类型转换、构造和析构函数等。另外和 C 接口一样，也为每个 HALCON 算子提供了全局函数，来实现程序化的编程风格（a procedural style of programming）。

读取图像并计算连接区域(connected regions)数量的 C++ 接口实现代码如下。

C++ 接口比 C 语言接口复杂，也更加完善。它充分应用了 C++ 面向对象编程的优点，例如自动类型转换、对象构造与析构，以及将函数与其数据封装为类。C++ 也为每个 HALCON 算子提供了全局函数，以支持与 C 接口类似的过程式编程风格。

示例：以下代码读取一幅图像，并计算其中的连通区域数量。
本例程的前提条件与详细说明，请参阅《程序员指南（Programmer’s Guide）》中的：Part 2, 首个示例程序。

HImage img{"pcb"};HRegion region=img.Threshold(0,122);Hlong numRegions=region.Connection().CountObj();std::cout<<"Number of Regions: "<<numRegions<<'\n';

2.3.4 HALCON/.NET 接口

C# 与 Visual Basic.NET 通过 .NET 接口使用 HALCON。
与 C++ 类似，它提供两种编程风格：过程式编程与面向对象编程。

在过程式编程风格中，类 HOperatorSet 提供了全部 HALCON 算子，其中使用 HObject 管理图像类数据，使用 HTuple 管理控制类数据。
在面向对象编程风格中，系统提供了如 HDataCode2d、HMeasure、HShapeModel 等类以实现核心功能，还提供了用于图像类数据的类，例如 HImage 和 HRegion。

示例：
以下代码读取一幅图像，并计算其中的连通区域数量。
本例程的前提条件与详细说明，请参阅《程序员指南（Programmer’s Guide）》中的：Part 3, 首个示例程序。

HImage img=newHImage("pcb");HRegion region=img.Threshold(0d,122d);intnumRegions=region.Connection().CountObj();Console.WriteLine("Number of Regions: "+numRegions);

2.4 图像采集接口

图像采集接口是图像采集设备厂商提供的软件与 HALCON 之间的桥梁。这些接口构成了一套通用、统一的接口，仅需少量算子即可完成操作。详细信息，请参阅《解决方案指南 II-A（Solution Guide II-A）》。

HALCON 通过动态库（Windows: 动态加载库 DLLs, Linux: 共享库 shared libraries）的形式为 50 多个图像采集卡和数百种工业相机提供图像采集接口。库文件名以 hAcq 为前缀开头，HALCON XL 使用的库文件以 xl 为后缀结尾。

基于行业标准、应用最广泛的接口已随 HALCON 库一同安装。其它接口以及已包含接口的最新版本可从网址 https://www.mvtec.com/products/interfaces 下载。MVTec 会持续开发新接口；当设备厂商软件变更时，对应的 HALCON 接口也会随之适配。如需查看所支持图像采集接口的完整列表，也可参阅《图像采集接口参考手册（Image Acquisition Interface Reference）》。

图像采集设备安装成功后，在 HALCON 中可以通过调用算子 open_framegrabber 访问设备，只要指定图像采集接口名称及连接参数即可。然后，通过调用算子 grab_image（或 grab_image_async）即可采集图像。

2.5 专用 I/O 接口

HALCON 为多种 I/O 设备提供接口以实现数据采集。这些接口使用动态库（Windows: 动态加载库 DLLs, Linux: 共享库 shared libraries）。库文件名以 hio 为前缀开头，HALCON XL 使用的库文件以 xl 为后缀结尾。

HALCON 对不同 I/O 设备使用同一类算子实现统一访问。安装好 I/O 设备后，调用算子 open_io_device 建立连接，指定 I/O 设备接口名称及可选的设备专属参数。连接建立后，通过调用 open_io_channel 打开传输通道，然后使用算子 read_io_channel 和 write_io_channel 进行数值读写。

请注意，HALCON I/O 设备接口的最新信息及可下载的接口（含文档）可在网址 https://www.mvtec.com/products/interfaces 获取。如需查看所支持 I/O 设备接口的完整列表，可参阅《I/O 设备接口参考手册（I/O Device Interface Reference）》。

第 3 章：应用程序开发

HDevelop 是面向 HALCON 机器视觉库的交互式开发环境。推荐用户先在 HDevelop 中进行快速原型开发。可以通过 HDevelop 找到最优的算子与参数，以完成图像分析任务。

在完成 HDevelop 程序开发后，需要将其移植到最终运行环境中。有三种方式可以选择：

从头编写程序：
从头编写程序意味着将 HDevelop 代码手动转换为目标编程语言（C++、Python 等）。
注意不同编程语言在算子命名规范、类名等方面可能存在差异，详见《HALCON 算子参考手册》、《程序员指南》。
导出 HDevelop 代码：
使用 HDevelop 的代码导出功能，可以自动将 HDevelop 代码转换为目标编程语言代码。
导出库项目
HDevelop 的库导出功能会生成一个可直接使用的项目文件夹，其中包含目标语言的封装代码以及用于构建项目的 CMake 文件。
该功能基于 HDevEngine 解释器实现，可以在 C++ 或任何可集成 .NET 对象的编程语言编写的应用程序中直接执行 HDevelop 程序。因此，当修改 HDevelop 代码时，无需重新编译整个应用程序。
也可以直接使用 HDevEngine，详见《程序员指南》Part6：HDevEngine 的使用方法。

3.1 HDevelop

我们先来初步了解一下 HDevelop。图 3.1 展示的是加载并部分执行一段程序后的 HDevelop 用户界面。

图 3.1：HDevelop 用户界面

默认情况下，以下窗口为可见状态，它们也是使用 HDevelop 进行开发的核心窗口：

图形窗口（GraphicsWindow）：显示（中间）结果，即图像类数据，如图像、区域和 XLD 轮廓。
程序窗口（ProgramWindow）：在此窗口中编写程序代码，通过算子调用 HALCON 的图像处理功能。
变量窗口（VariableWindow）：显示所有变量，包括图像类变量与控制类变量。

有关 HDevelop 的详细说明，请参阅《HDevelop 用户指南（HDevelop User’s Guide）》。下面的视频教程也可以作为学习 HDevelop 的入门教程：

HDevelop 教程 01：界面与导航（GUI and Navigation）
HDevelop 教程 02：变量（Variables）
HDevelop 教程 03：可视化（Visualization）

3.2 示例程序

在学习 HALCON 基本概念和 HDevelop 用户界面之后，我们将使用库导出方式开发一个 C++ 应用程序。

接下来本节将介绍详细的操作步骤，您也可以观看相关教程视频：

通过库项目导出将 HDevelop 代码集成到 C++ 应用程序（Integrate HDevelop code into a C++ application using the Library Project Export）；
通过库项目导出将 HDevelop 代码集成到 C# 应用程序（Integrate HDevelop code into a C# application using the Library Project Export）。

这些视频演示了库导出的完整流程。

3.2.1 在 HDevelop 中创建原型

本示例的任务是读取一幅图像并计算其中的连通区域数量。

打开 HDevelop，并将以下代码输入到程序窗口中：

read_image(Image,'pcb')threshold(Image,Region,0,122)connection(Region,ConnectedRegions)count_obj(ConnectedRegions,Number)

通过点击工具栏中的运行或按F5键来测试您的程序。

为便于将此 HDevelop 代码集成到实际应用程序中，我们将机器视觉部分封装到一个本地过程中。

高亮选中以下代码行：

threshold(Image,Region,0,122)connection(Region,ConnectedRegions)count_obj(ConnectedRegions,Number)

单击鼠标右键，打开上下文菜单。
选择 “创建新过程（Create New Procedure）”。
将其命名为count_regions。
选择 “参数”，并将选择方案更改为：“先入后出（First In Last Out）”。
点击 “确定” 确认。
将 HDevelop 程序保存为hdev_count_regions.hdev。

3.2.2 准备 Visual Studio 项目

本示例将使用 Visual Studio 2019。

创建一个空的 C++ Windows 控制台项目，命名为vs_count_regions。请勾选 “将解决方案和项目放在同一目录中” 选项。
添加 C++ 源文件（菜单：项目 → 添加新项 → C++ 文件），并命名为vs_count_regions.cpp。
在工具栏的下拉菜单中选择解决方案平台 x64。
打开项目属性（菜单：项目 → vs_count_regions 属性），并进行以下设置：
- 选择 C/C++ → 常规，添加以下附加包含目录：(HALCONROOT)\include\halconcpp；
- 选择链接器 → 常规，添加以下附加库目录：KaTeX parse error: Undefined control sequence: \lib at position 13: (HALCONROOT)\̲l̲i̲b̲(HALCONARCH)；
- 选择链接器 → 输入，添加以下附加依赖项：halconcpp.lib;hdevenginecpp.lib；

3.2.3 导出库项目

接下来，将 HDevelop 程序hdev_count_regions.hdev导出到 Visual Studio 项目文件夹中。

打开此前创建的 HDevelop 程序hdev_count_regions.hdev。
打开文件 → 导出库项目。
进行以下设置：
- 输入文件：当前程序；
- 目标语言：C++；
- 项目名称：hdev_count_regions；
- 项目位置：选择 Visual Studio 项目 vs_count_regions 所在路径。
- 命名空间：hdev_count_regions
单击 “导出” 确认。

现在，Visual Studio 项目文件夹 vs_count_regions 中至少应包含以下文件：

vs_count_regions.cpp（源文件）
vs_count_regions.sln（解决方案）
hdev_count_regions（HDevelop 导出的文件夹）
- cmake
- res_hdev_count_regions
  - hdev_count_regions.hdev
- source
  - hdev_count_regions.cpp
  - hdev_count_regions.h
- CMakeLists.txt

3.2.4 将库项目集成到 Visual Studio 中

最后，需要将 HDevelop 程序集成到 Visual Studio 项目中。

打开 Visual Studio 项目。
打开 “项目 → 添加现有项”，选择由 HDevelop 库导出功能创建的 C++ 文件hdev_count_regions.cpp和头文件hdev_count_regions.h。（文件位于 hdev_count_regions\source 文件夹中）
将以下代码输入到vs_count_regions.cpp中。

#include<iostream>#include"HalconCpp.h"#include"hdev_count_regions/source/hdev_count_regions.h"intmain(){HalconCpp::HImageImage("pcb");hdev_count_regions::SetResourcePath("hdev_count_regions/res_hdev_count_regions");HalconCpp::HTuple Number{};hdev_count_regions::count_regions(Image,&Number);std::cout<<"Number of Regions: "<<Number.L()<<'\n';}

执行程序。
控制台打开，并显示结果 “Number of regions: 43”。

第 4 章：学习指南

如果要更深入地学习 HALCON，我们提供了更多文档与支持资源。

MVTec 学院
MVTec 学院提供大量交互式在线课程，涵盖从基础概念到高级专项应用的众多主题。
请访问 https://academy.mvtec.com 了解更多信息。
HDevelop 示例程序
HALCON 提供丰富的示例程序，不仅适用于 HDevelop，也支持多种编程语言。这些示例可在环境变量 %HALCONEXAMPLES% 指向的目录中找到；若未设置该变量，则位于 HALCON 安装目录下的 examples 子文件夹中。
打开 HDevelop 示例程序的方法：选择菜单：“文件 → 浏览 HDevelop 示例程序…”。
若要学习 HALCON 基础概念，建议查看示例程序halcon_basic_concepts.hdev。
服务与支持
mvtec 官网（https://www.mvtec.com/services-support）提供多种支持资源，例如教程视频、研讨会与培训信息、包含开发技巧的开发者专区等更多内容。
HALCON 文档
HALCON 文档包含从入门到专家级的丰富资料。
例如，我们的解决方案指南详细讲解机器视觉方法及其在 HDevelop 中的应用。
推荐从【解决方案指南 I（Solution Guide I）】开始学习，它介绍了主流机器视觉方法。
所有手册的概述与简要说明可在文档首页查看。

【本节完】

版权声明：
本文译自：HALCON：Quick Guide，版权属于 Copyright © 2003-2025 by MVTec Software GmbH, Munich, Germany。
转发必须注明原文链接：
【HALCON 实战入门】2. HALCON 快速入门 (https://youcans.blog.csdn.net/article/details/160250188)
Copyright by youcans@qq.com 2026
Crated：2026-04