当前位置： 首页 > news >正文

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

news 2026/7/18 6:32:43

【HALCON 实战入门】专栏
1. HALCON 简介与安装
2. 图像读取、显示与保存


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

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

在上一篇 1. HALCON 简介与安装 中，我们已经完成了 HALCON 的安装，并成功进入 HDevelop 开发环境，接下来的关键是让程序真正跑起来。

图像的读取与保存是最基础也是最重要的操作。熟练掌握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 图像对象，支持单张、多张、有序或无序批量读取。

函数原型：

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：读取单张图像
*读取一张图像read_image(Image,'D:/Halcon/HALCON.png')

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

工程化的写法如下：

image_files(./imgs','files',ImageFiles)tuple_regexp_select(ImageFiles,'.*(jpg|png|bmp)',Selection)fori:=0to|Selection|-1by1read_image(Image,Selection[i])*处理图像...endfor

2.2 拖放操作读取图像

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

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


2.3 读取图像序列

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

示例：

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

说明：

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

二、图像保存

2.1 图像保存算子（write_image）

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

函数原型：

HDevelop:write_image(Image::Format,FillColor,FileName:)C:write_image(constHobject Image,constchar*Format,constHlong FillColor,constchar*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）。否则，将引发异常。

注意事项：

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

使用示例：

  • 示例 1：将图像保存为PNG格式并进行压缩
*读取一张图像：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算子用于在指定位置显示文本。

函数原型：

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（输出参数）：窗口的句柄，是窗口对象的唯一标识符，用于后续的窗口操作。

使用示例：

*关闭所有已有的窗口（防止冲突）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）。该操作等效于在变量窗口中双击某个图像变量。

函数原型：

HDevelop:dev_display(Object:::)

参数说明：

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

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

参考例程如下：

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算子用于在输出窗口中显示图像的灰度值。显示整幅图像或指定区域内的灰度像素，默认仅显示指定区域的内容。

函数原型：

HDevelop:disp_image(Image::WindowHandle:)C:T_disp_image(constHobject Image,constHtuple WindowHandle)Python:disp_image(image:HObject,window_handle:HHandle)->None

参数说明：

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

注意事项：
在显示灰度图像时，灰度级数量通常会被缩减。。

参考例程：

*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算子用于获取图像的尺寸（宽度和高度），是很多视觉任务的必备基础工具。

函数原型：

HDevelop:get_image_size(Image:::Width,Height)C:get_image_size(constHobject 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’ 等）。常用于某些算子的预处理校验，以避免类型不匹配错误。对于多通道输入图像，仅返回第一个通道的类型。

函数原型：

HDevelop:get_image_type(Image:::Type)C:get_image_type(constHobject 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 三个通道的指针）、类型、宽度和高度。

函数原型：

HDevelop:get_image_pointer1(Image:::Pointer,Type,Width,Height)get_image_pointer3(ImageRGB:::PointerRed,PointerGreen,PointerBlue,Type,Width,Height)C:get_image_pointer1(constHobject Image,Hlong*Pointer,char*Type,Hlong*Width,Hlong*Height)get_image_pointer3(constHobject 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（输出参数）：图像的宽度、高度。

注意事项：

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

参考例程：

*读取图像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 实战入门】2. 图像读取、显示与保存 (https://youcans.blog.csdn.net/article/details/160216398)
Copyright by youcans@qq.com 2026
Crated：2026-04


http://www.cnnetsun.cn/news/1941668.html

相关文章：

  • 5步掌握League Toolkit：英雄联盟客户端智能助手完整指南
  • 麒麟V10SP1上装Oracle 11gR2，我踩过的那些依赖包的坑（附离线包下载）
  • 网盘下载加速终极指南：八大平台直链解析工具免费解决方案
  • MatLog：3分钟掌握Android日志分析，让应用调试变得简单
  • LVGL-02 构建可复用的 LVGL SDK 层（CMake 模块化设计）
  • 实时AI抠像技术演进：OBS背景移除插件深度探索
  • 别再只会用getOpenFileName了！QT文件对话框8个函数保姆级对比与实战避坑
  • 第8讲：C# 运算符实战精讲：从基础运算到Razor页面中的逻辑控制
  • 解决合伙小店模糊分红问题，制作利润预留备用金核算实操表。
  • 终极Windows和Office激活指南：KMS_VL_ALL_AIO全功能解析
  • 宝塔（bt）新建网站后Nginx显示Welcome页面的排查与修复指南
  • 颠覆性纺织AI质检：YDFID-1色织物图像数据集的完整实践指南
  • 【k8s】从Flannel到Calico：网络插件升级与精细化网络策略实战
  • 【2026奇点智能技术大会权威解码】：AI内容审核的5大技术拐点与企业落地避坑指南
  • 别乱冲销！深入理解SAP外币评估的‘重置’与‘总是评估’到底怎么选
  • 10个Illustrator脚本终极指南：快速实现设计自动化，效率提升300%
  • Bebas Neue免费开源字体终极指南：如何用现代几何字体提升设计质感
  • 从DeepLab-v3+看语义分割：如何用空洞卷积与编码器-解码器架构重塑像素级理解
  • 小白也能搞定！Qwen3-Reranker-0.6B环境配置与Web服务搭建全攻略
  • 桌面畅游酷安社区：Coolapk-UWP让Windows用户获得完整移动体验
  • 《每日一命令03：sed——批量替换从未如此简单》
  • 终极Windows系统优化：Win11Debloat免费去臃肿工具完全指南
  • Java八股之JVM内存结构
  • 终极冒险岛游戏编辑器：5分钟快速上手完整指南
  • 告别设备束缚！这款跨平台漫画神器让你随时随地畅享阅读乐趣
  • 终极OBS背景移除插件：如何免费实现专业级AI抠像效果
  • 告别残留：多环境视角下彻底卸载Jupyter Notebook的完整指南
  • 如何轻松获取国家中小学智慧教育平台电子课本：tchMaterial-parser完整指南
  • 网盘下载革命：8大平台直链解析工具完全指南
  • 3步解锁Python智能体建模：用Mesa轻松模拟复杂系统