【HALCON 实战入门】4. 图像读取、显示与保存

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

4. 图像读取、显示与保存

一、图像读取
- [2.1 从文件中读取图像（read_image）](#2.1 从文件中读取图像（read_image）)
- [2.2 拖放操作读取图像](#2.2 拖放操作读取图像)
- [2.3 读取图像序列](#2.3 读取图像序列)
二、图像保存
- [2.1 图像保存算子（write_image）](#2.1 图像保存算子（write_image）)
三、图像显示
- [3.1 显示窗口的创建、激活与关闭](#3.1 显示窗口的创建、激活与关闭)
- [3.2 显示多通道图像（dev_display）](#3.2 显示多通道图像（dev_display）)
- [3.3 显示单通道图像（disp_image）](#3.3 显示单通道图像（disp_image）)
四、获取图像信息
- [4.1 获取图像的尺寸](#4.1 获取图像的尺寸)
- [4.2 获取图像的数据类型](#4.2 获取图像的数据类型)
- [4.3 获取图像的指针](#4.3 获取图像的指针)
五、总结

除了从相机采集图像外，HALCON 还支持读取已存储在文件中的图像（支持格式：BMP、TIFF、GIF、JPEG、PNG、PNM、PCX、XWD）。当然，你也可以将采集到的图像保存到文件中。

图像的读取与保存是最基础也是最重要的操作。熟练掌握Halcon中的图像I/O操作，是进行后续图像处理、分析和检测的前提。本文详细介绍 Halcon 中图像读取、显示与保存的基本方法。

一、图像读取

HALCON 支持从文件读取图像或从工业设备采集图像。本文从 "文件读取"开始，设备采集将在后续章节介绍。

根据待读取图像文件的数目不同，Halcon提供了两种不同的图像文件读取方式，分别是：

处理单幅图像：read_image 算子，read_multi_channel_image算子；
处理多幅图像（如图像序列）：read_sequence算子， read_image_sequence算子。

2.1 从文件中读取图像（read_image）

read_image 算子是 Halcon 中最常用的图像读取算子，用于从文件系统中读取指定路径的图像文件并生成 HObject 图像对象，支持单张、多张、有序或无序批量读取。

函数原型：

bash 复制代码

HDevelop: 
  read_image( : Image : FileName : )
C:
  read_image(Hobject* Image, const char* FileName)
Python:
  read_image(file_name: MaybeSequence[str]) -> HObject

参数说明：

Image（输出）：读取后的图像对象（HObject）。
FileName（输入）：件路径或文件名，可为单个字符串或字符串数组。

支持的图像格式：

Halcon 格式：
- HOBJ：Halcon Iconic Object 格式，多个图像存储在一个文件中，会作为图像对象元组返回。
- IMA：Halcon 图像格式，支持从 .ima 文件中读取图像数据。
标准图像格式：
- TIFF、PNG、JPEG、BMP、GIF、JPEG-2000、JPEG-XR 等常用的图像格式。
- PBM、PGM、PPM 等 PNM 格式，以及 PCX、SUN Raster、XWD 等格式。

执行信息：

read_image 操作符是线程安全的，可以在多线程环境中调用。
默认情况下，该算子不会进行并行化处理。

返回值：

操作成功时返回 2（H_MSG_TRUE）。
如果出现错误，会抛出异常，常见错误包括文件路径错误或格式不支持。

使用示例：

示例 1：读取单张图像

csharp 复制代码

* 读取一张图像
  read_image(Image, 'D:/Halcon/HALCON.png')

示例 2：读取多张图像

csharp 复制代码

* 将多张图像读取到图像数组中：
  read_image(Images, ['pic0', 'pic1', 'pic2'])

工程化的写法如下：

csharp 复制代码

image_files(./imgs', 'files', ImageFiles)
tuple_regexp_select(ImageFiles, '.*(jpg|png|bmp)', Selection)

for i := 0 to |Selection|-1 by 1
    read_image(Image, Selection[i])
    * 处理图像...
endfor

2.2 拖放操作读取图像

HDevelop 支持多种图像格式，可以直接读取。最简单的方式，是直接从文件浏览器中将图像拖放到 HDevelop 窗口中。

从菜单中选择 "文件 - 读取图像"，弹出 "读取图像" 对话框。
在 "读取图像" 对话框中，从文件管理器中选择要读取的图像，图像的路径和名称自动加载到 "文件名称"。
在对话框的 "文件名称" 中会显示图像的完整路径和名称，并自动生成一个变量名称。
对话框里还会显示图像预览和基本信息（宽度、高度、色彩类型、通道数）。
用户可以修改变量名称，也可以从下拉列表里选择一个已有的图像变量名称。
用户还可以选择插入位置：插入光标（IC）或程序计数器（PC）。
点击"确定"后，read_image 的命令就会被添加到当前程序中，用于实现读取图像。

2.3 读取图像序列

read_sequence 算子用于从文件中读取图像序列，并将读取的图像存储为图像对象元组。

示例：

c 复制代码

* 定义文件路径和变量
FileName := 'image_sequence/*.png'
read_sequence (FileName, ImageSequence)
* 遍历读取的图像序列
for Index := 0 to |ImageSequence| - 1 by 1
   select_obj (ImageSequence, Image, Index + 1)
   dev_display (Image)
endfor

说明：

文件路径：FileName 参数支持通配符（如 *.png），可以指定目录下的所有符合条件的文件。
输出变量：读取的图像序列会存储在 ImageSequence 中，作为一个图像对象元组。
性能优化：对于大批量图像，建议分批处理以节省内存。
如果只需要读取单张图像，建议使用 read_image 算子。

二、图像保存

2.1 图像保存算子（write_image）

write_image 算子是 Halcon 中的图像保存算子，它允许将图像对象保存为图片文件。支持将图像保存为多种格式，如BMP、PNG、JPEG、TIFF等，并提供压缩选项。

函数原型：

c 复制代码

HDevelop: 
  write_image(Image : : Format, FillColor, FileName : )
C:
  write_image(const Hobject Image, const char* Format, const Hlong FillColor, const char* FileName)
Python:
  write_image(image: HObject, format: str, fill_color: Union[int, float], file_name: MaybeSequence[str])

参数说明：

Image（输入对象）：输入图像或输入图像的数组。支持 byte、direction、cyclic、int1、complex、int2、uint2、vector_field、int4、int8 和 real 类型。
Format（输入控制）：保存的图形格式。支持的格式包括：
- 'tiff'，'bigtiff'：TIFF 格式；
- 'bmp'：Windows-BMP 格式；
- 'jpeg'：JPEG 格式；
- 'jp2'：JPEG-2000 格式；
- 'jpegxr'：JPEG-XR 格式；
- 'png'：PNG 格式；
- 'hobj'：HALCON Iconic Object（HOBJ）格式；
- 'ima'：HALCON 格式。
FillColor（输入控制）：不属于图像区域的灰度像素填充值，默认值为 0。

对于灰度值图像，必须传递0（黑色）到255（白色）之间的值。

对于RGB彩色图像，RGB值可以直接传递为十六进制值，例如，对于黄色背景，可以传递0xffff00（红=255，绿=255，蓝=0）。
FileName（输入变量）：保存图像的路径和文件名，包括文件扩展名。路径和名称中不要使用中文字符。

执行信息：

多线程类型：可重入（可以与非独占操作同时运行）；
多线程范围：全局（可以从任何线程调用）；
自动并行化：在元组级别上自动并行化。

返回结果：

如果参数值正确，write_image 操作符将返回值2（H_MSG_TRUE）。否则，将引发异常。

注意事项：

保存图像的路径和文件名不要使用中文字符。
使用更高的压缩级别可能会导致保存过程变慢，需要权衡压缩率和性能。
JPEG是有损压缩格式，会引入一定程度的颜色损失。
在性能测试中，使用 'jpeg 30' 格式保存时速度最快。

使用示例：

示例 1：将图像保存为PNG格式并进行压缩

csharp 复制代码

* 读取一张图像：
  read_image(Image1, 'D:/Halcon/CellTop01.png')
* 将图像保存为PNG格式并设置压缩级别
  write_image(Image1, 'png', 0, 'D:/Halcon/images/CellTop01.png')

三、图像显示

3.1 显示窗口的创建、激活与关闭

为了更直接地观察处理过程，可以在指定窗口中显示图像。首先使用 dev_open_window 算子创建一个窗口，然后使用 dev_set_window 算子将该窗口设置为活动窗口（即激活该窗口）。

dev_open_window 算子用于打开一个新的图形窗口，在程序中显示图像、绘制图形或输出文本。

在图形窗口中可以显示各种图像、区域、线条以及文本等对象，并根据需求进行窗口大小、位置和背景颜色的设置。

dev_get_window 算子用于获取当前活动窗口句柄，在多窗口场景下提供灵活的窗口管理能力。常用于多窗口切换、窗口状态的保存与恢复。

dev_clear_window 算子用于清除当前活动图形窗口的内容，包括窗口中显示的图像、区域、轮廓等，但不会影响窗口设置的参数（如颜色、绘制模式等）。常用于实时动态显示、多区域遍历。

dev_close_window 算子用于关闭当前活动的浮动窗口。这一操作在多窗口管理中尤为重要。

dev_set_part 算子用于设置在图形窗口中显示的图像局部区域。参数 Row1、Column1 指定待显示区域的左上角坐标，Row2、Column2 指定右下角坐标。

dev_disp_text 算子用于在指定位置显示文本。

函数原型：

c 复制代码

HDevelop: 
  dev_open_window( : : Row, Column, Width, Height, Background : WindowHandle)
  dev_get_window( : : : WindowHandle)
  dev_clear_window( : : : )
  dev_close_window( : : : )
  dev_set_part( : : Row1, Column1, Row2, Column2 : )
  dev_disp_text( : : String, CoordSystem, Row, Column, Color, GenParamName, GenParamValue : )

参数说明：

Row（输入控制）：窗口左上角的行坐标（垂直位置），默认值为 0。
Column（输入控制）：窗口左上角的列坐标（水平位置），默认值为 0。
Width（输入控制）：窗口的宽度，默认值为 512，-1 表示自适应大小。
Height（输入控制）：窗口的高度，默认值为 512，-1 表示自适应大小。
Background（输入控制）：设置窗口的背景颜色，例如 'black'、'white' 或 RGB 值，，默认值为 'black'。
WindowHandle（输出参数）：窗口的句柄，是窗口对象的唯一标识符，用于后续的窗口操作。

使用示例：

csharp 复制代码

* 关闭所有已有的窗口（防止冲突）
dev_close_window()

* 读取图像文件
read_image(For5, 'for5')

* 获取图像的宽度和高度，用于设置窗口大小
get_image_size(For5, Width, Height)

* 打开一个新的图形窗口
* 参数：
* (Row, Column): 窗口位置设置为 (0, 0)
* (Width, Height): 窗口大小与图像一致
* 'black': 背景颜色设置为黑色
* WindowHandle: 返回的窗口句柄，用于后续操作
dev_open_window(0, 0, Width, Height, 'black', WindowHandle)

* 在窗口中显示图像
dev_display(For5)

* 更改窗口的显示颜色表为'彩虹'模式
dev_set_lut('rainbow')

* 再次显示图像以观察颜色表效果
dev_display(For5)
stop()

* 恢复默认颜色表
dev_set_lut('default')
dev_display(For5)
stop()

* 设置显示区域为图像中 (100, 100) 到 (300, 300) 的部分
dev_set_part(100, 100, 300, 300)

* 显示设置后的图像部分
dev_display(For5)

3.2 显示多通道图像（dev_display）

dev_display 算子用于在活动图形窗口中显示图像类对象（图像、区域或 XLD）。该操作等效于在变量窗口中双击某个图像变量。

函数原型：

c 复制代码

HDevelop: 
  dev_display(Object : : : )

参数说明：

Object (输入对象)：待显示的图像对象。

注意事项：

使用 HDevelop 的代码导出功能时，为该算子生成的代码可能与对应的原生 HALCON 算子行为存在差异。

参考例程如下：

c 复制代码

dev_close_window ()
read_image (ImgCell01, 'D:/Halcon/images/CellTop01.png')
dev_open_window (0, 0, -1, -1, 'black', WindowHandle)
dev_display (ImgCell01)
stop ()

3.3 显示单通道图像（disp_image）

disp_image 算子用于在输出窗口中显示图像的灰度值。显示整幅图像或指定区域内的灰度像素，默认仅显示指定区域的内容。

函数原型：

c 复制代码

HDevelop: 
  disp_image(Image : : WindowHandle : )
C:
  T_disp_image(const Hobject Image, const Htuple WindowHandle)
Python:
  disp_image(image: HObject, window_handle: HHandle) -> None

参数说明：

Image（输入对象）：单通道图像，待显示的灰度值图像。
WindowHandle（输入控制）：窗口，窗口句柄.

注意事项：

在显示灰度图像时，灰度级数量通常会被缩减。。

参考例程：

c 复制代码

* Output of a gray image:
dev_close_window ()
read_image (ImgCell01, 'D:/Halcon/images/CellSide01.png')
dev_open_window (0, 0, -1, -1, 'black', WindowHandle)
dev_display (ImgCell01)

四、获取图像信息

图像通常有空间分辨率（即长度宽度）、通道（单色图像还是彩色图像）、存储数据类型（单个像素点对应的存储数据类型）、图像格式等信息。Halcon提供了丰富的算子，方便快捷地获取上述图像信息。

4.1 获取图像的尺寸

get_image_size 算子用于获取图像的尺寸（宽度和高度），是很多视觉任务的必备基础工具。

函数原型：

c 复制代码

HDevelop: 
  get_image_size(Image : : : Width, Height)
C:
  get_image_size(const Hobject Image, Hlong* Width, Hlong* Height)
Python:
  get_image_size(image: HObject) -> Tuple[Sequence[int], Sequence[int]]

参数说明：

Image（输入对象）：输入图像，灰度图或多通道彩色图像。
Width（输出参数）：图像的宽度（单位：像素）。
Height（输出参数）：图像的高度（单位：像素）

4.2 获取图像的数据类型

get_image_type 算子用于返回输入图像的像素类型（例如 'byte'、'int2'、'uint2' 等）。常用于某些算子的预处理校验，以避免类型不匹配错误。对于多通道输入图像，仅返回第一个通道的类型。

函数原型：

c 复制代码

HDevelop: 
  get_image_type(Image : : : Type)
C:
  get_image_type(const Hobject Image, char* Type)
Python:
  get_image_type(image: HObject) -> Sequence[str]

参数说明：

Image（输入对象）：输入图像，灰度图或多通道彩色图像。
Type（输出参数）：返回图像的像素类型。如：'byte'、'complex'、'cyclic'、'direction'、'int1'、'int2'、'int4'、'int8'、'real'、'uint2'、'vector_field_absolute'、'vector_field_relative'。

4.3 获取图像的指针

get_image_pointer1 算子用于返回图像第一个通道的指针、类型、宽度和高度。一般用于单通道图像；对于多通道输入图像，仅返回第一个通道指针与类型。
get_image_pointer3 算子用于返回彩色图像数据的指针（返回 RGB 三个通道的指针）、类型、宽度和高度。

函数原型：

c 复制代码

HDevelop: 
  get_image_pointer1(Image : : : Pointer, Type, Width, Height)
  get_image_pointer3(ImageRGB : : : PointerRed, PointerGreen, PointerBlue, Type, Width, Height)
C:
  get_image_pointer1(const Hobject Image, Hlong* Pointer, char* Type, Hlong* Width, Hlong* Height)
  get_image_pointer3(const Hobject ImageRGB, Hlong* PointerRed, Hlong* PointerGreen, Hlong* PointerBlue, char* Type, Hlong* Width, Hlong* Height)
Python:
  get_image_pointer1(image: HObject) -> Tuple[Sequence[int], Sequence[str], Sequence[int], Sequence[int]]
  get_image_pointer3(image_rgb: HObject) -> Tuple[Sequence[int], Sequence[int], Sequence[int], Sequence[str], Sequence[int], Sequence[int]]

参数说明：

Image（输入对象）：输入图像，get_image_pointer1 必须输入单通道图像，get_image_pointer3 必须输入三通道彩色图像。
Pointer（输出参数）：返回的指针（可以通过它访问图像数据）。
PointerRed、PointerGreen、PointerBlue（输出参数）：分别返回 R、G、B 三个通道的指针。
Type（输出参数）：图像的类型。
Width、Height（输出参数）：图像的宽度、高度。

注意事项：

指针 Pointer 只有在 Image 对象存在时有效。如果 Image 被释放或覆盖，指针会无效，使用它会导致程序崩溃。
如果通过指针 Pointer 向已存在的图像写入数据，所有引用该图像的对象都会被修改。
如果需要修改数据，建议先创建新图像，避免影响原图像。

参考例程：

c 复制代码

* 读取图像
read_image (Img01, 'D:/Halcon/images/CellTop01.png')
* 获取图像的尺寸
get_image_size(Img01, Width, Height)

* 在窗口上显示图像尺寸信息
dev_close_window ()
dev_open_window (0, 0, -1, -1, 'black', WindowHandle)
dev_display(Img01)
disp_message(WindowHandle, '图像宽度: ' + Width$'d' + ' px', 'window', 20, 10, 'black', 'true')
disp_message(WindowHandle, '图像高度: ' + Height$'d' + ' px', 'window', 40, 10, 'black', 'true')

五、总结

工程建议：

机器视觉项目优先使用PNG格式保存结果；
批量处理时做好异常捕获和日志记录；
根据实际场景选择合适的图像格式；
注意图像域（Domain）的处理，避免保存异常。

本文围绕 HALCON 中最基础也是最重要的图像操作，系统介绍了图像读取、显示与保存的完整流程，并补充了常用的图像信息获取方法。通过本篇内容，你已经掌握了：

图像读取的方法（文件读取、拖放读取、序列读取）
图像保存的基本方法（write_image）
图像显示的核心操作（窗口管理与显示算子）
图像基本属性的获取（尺寸、类型及数据访问）

至此，已经打通 "图像输入---处理---输出"的基础链路，为后续图像处理与视觉算法学习奠定了基础。

下一篇将进入"交互操作与入门案例（ROI与简单目标提取）"，逐步从基础操作过渡到实际应用。

【本节完】

版权声明：

转发必须注明原文链接：

【HALCON 实战入门】4. 图像读取、显示与保存 (https://youcans.blog.csdn.net/article/details/160216398)

Copyright by youcans@qq.com 2026

Crated：2026-04