【HALCON 实战入门】2. HALCON 快速入门

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

2. HALCON 快速入门

• [第 1 章：安装 HALCON](#第 1 章：安装 HALCON)
• [第 2 章：HALCON 架构](#第 2 章：HALCON 架构)
• • [2.1 算子](#2.1 算子)
  • • [2.1.1 参数与数据结构](#2.1.1 参数与数据结构)
  • [2.2 扩展包](#2.2 扩展包)
  • [2.3 语言接口](#2.3 语言接口)
  • • [2.3.1 HALCON/Python 接口](#2.3.1 HALCON/Python 接口)
    • [2.3.2 HALCON/C 接口](#2.3.2 HALCON/C 接口)
    • [2.3.3 HALCON/C++ 接口](#2.3.3 HALCON/C++ 接口)
    • [2.3.4 HALCON/.NET 接口](#2.3.4 HALCON/.NET 接口)
  • [2.4 图像采集接口](#2.4 图像采集接口)
  • [2.5 专用 I/O 接口](#2.5 专用 I/O 接口)
• [第 3 章：应用程序开发](#第 3 章：应用程序开发)
• • [3.1 HDevelop](#3.1 HDevelop)
  • [3.2 示例程序](#3.2 示例程序)
  • • [3.2.1 在 HDevelop 中创建原型](#3.2.1 在 HDevelop 中创建原型)
    • [3.2.2 准备 Visual Studio 项目](#3.2.2 准备 Visual Studio 项目)
    • [3.2.3 导出库项目](#3.2.3 导出库项目)
    • [3.2.4 将库项目集成到 Visual Studio 中](#3.2.4 将库项目集成到 Visual Studio 中)
• [第 4 章：学习指南](#第 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 = new HImage("pcb");
HRegion region = img.Threshold(0d, 122d);
int numRegions = 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 进行开发的核心窗口：

1. 图形窗口（GraphicsWindow）：显示（中间）结果，即图像类数据，如图像、区域和 XLD 轮廓。
2. 程序窗口（ProgramWindow）：在此窗口中编写程序代码，通过算子调用 HALCON 的图像处理功能。
3. 变量窗口（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 中创建原型

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

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

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

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

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

1. 高亮选中以下代码行：

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

2. 单击鼠标右键，打开上下文菜单。

3. 选择 "创建新过程（Create New Procedure）"。

4. 将其命名为 count_regions。

5. 选择 "参数"，并将选择方案更改为："先入后出（First In Last Out）"。

6. 点击 "确定" 确认。

7. 将 HDevelop 程序保存为 hdev_count_regions.hdev。

3.2.2 准备 Visual Studio 项目

本示例将使用 Visual Studio 2019。

1. 创建一个空的 C++ Windows 控制台项目，命名为 vs_count_regions。请勾选 "将解决方案和项目放在同一目录中" 选项。

2. 添加 C++ 源文件（菜单：项目 → 添加新项 → C++ 文件），并命名为 vs_count_regions.cpp。

3. 在工具栏的下拉菜单中选择解决方案平台 x64。

4. 打开项目属性（菜单：项目 → 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 项目文件夹中。

1. 打开此前创建的 HDevelop 程序 hdev_count_regions.hdev。

2. 打开 文件 → 导出库项目。

3. 进行以下设置：

   • 输入文件：当前程序；
   • 目标语言：C++；
   • 项目名称：hdev_count_regions；
   • 项目位置：选择 Visual Studio 项目 vs_count_regions 所在路径。
   • 命名空间：hdev_count_regions

4. 单击 "导出" 确认。

现在，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 项目中。

1. 打开 Visual Studio 项目。

2. 打开 "项目 → 添加现有项"，选择由 HDevelop 库导出功能创建的 C++ 文件 hdev_count_regions.cpp 和头文件 hdev_count_regions.h。（文件位于 hdev_count_regions\source 文件夹中）

3. 将以下代码输入到 vs_count_regions.cpp 中。

#include <iostream>
#include "HalconCpp.h"
#include "hdev_count_regions/source/hdev_count_regions.h"
int main()
{
HalconCpp::HImage Image("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';
}

4. 执行程序。
   控制台打开，并显示结果 "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