📚 课程目录第2章图像采集与相机接口

2. 图像采集与相机接口

在工业视觉系统里，图像采集是整条处理链的源头。HALCON 并不直接“驱动”某一款相机，而是通过一层统一的采集接口（Image Acquisition Interface）把不同厂商、不同协议的相机抽象成一致的算子调用。理解这层抽象，以及它背后的 GenICam、GigE Vision、USB3 Vision 标准，是稳定取像和后续参数调优的基础。

一、HALCON 图像采集接口的分层结构

HALCON 的采集体系可以分成三层：最上层是应用层算子，中间是采集接口动态库，最下层是相机厂商的 SDK 或标准协议栈。应用层最常用的算子包括 open_framegrabber、grab_image、grab_image_async、grab_data、set_framegrabber_param、get_framegrabber_param 和 close_framegrabber。其中 open_framegrabber 的第一个参数 Name 决定使用哪个接口，例如 'GigEVision2'、'USB3Vision'、'GenICamTL'，或厂商专用接口如 'Basler'、'uEye'。

接口层负责把 HALCON 的通用参数翻译成具体协议或 SDK 的调用。例如 set_framegrabber_param(AcqHandle,'ExposureTime',5000) 在 GigE Vision 相机上会映射为 GenICam 的 ExposureTime 节点写入，单位通常是微秒。这种“统一算子 + 标准参数名”的设计，使得同一段代码在更换相机品牌时往往只需修改 Name 和少量参数。

二、GenICam：参数与功能的统一描述

GenICam 是 EMVA 制定的通用相机编程接口标准，核心是 XML 描述文件（GenApi）。相机把自身支持的功能节点、数据类型、取值范围、单位、访问模式写进 XML，主机端读取后就能动态生成参数树。HALCON 通过 get_framegrabber_param 可以枚举这些节点，例如查询 'available_params' 得到当前相机可写的参数名列表。

实际配置时，参数名必须与相机 XML 中的节点名完全一致，大小写敏感。常见节点包括：Width、Height、OffsetX、OffsetY、PixelFormat、ExposureTime、Gain、AcquisitionFrameRate、TriggerMode、TriggerSource、TriggerActivation。如果写错名称，HALCON 会返回错误码 5200 系列，提示参数不存在或不可写。

GenICam 节点有“可见性”和“可用性”之分。某些参数在 TriggerMode=Off 时不可写，必须先切换触发模式，再设置触发源和触发沿。配置顺序错误是现场最常见的报错来源。

三、GigE Vision 与 USB3 Vision 的差异

GigE Vision 基于千兆以太网，使用 GVCP 做控制、GVSP 做流传输，支持较长的线缆（可达 100 m）和多相机组网，适合产线分布式部署。它的关键约束是带宽：千兆网理论 1000 Mbps，实际有效约 900~950 Mbps。以 1280×1024、8 bit 灰度、30 fps 计算，单帧数据量约 1.31 MB，30 fps 需要约 315 Mbps，单相机尚有余量；若换成 500 万像素彩色 30 fps，则接近 900 Mbps，必须启用巨帧（Jumbo Frame）并调整 PacketSize 和 InterPacketDelay。

USB3 Vision 基于 USB 3.0，理论 5 Gbps，实际持续带宽约 3.2~3.8 Gbps，线缆通常限制在 3~5 m，适合单机、短距离、高帧率场景。它使用 U3V 控制通道和流通道，同样由 GenICam 描述参数。USB3 的供电和带宽是共享的，多相机同时工作时要计算主机控制器和 Hub 的总带宽。

对比项	GigE Vision	USB3 Vision
物理介质	千兆/万兆以太网	USB 3.0
典型线缆长度	100 m（千兆）	3~5 m
有效带宽	约 900~950 Mbps	约 3.2~3.8 Gbps
多相机扩展	交换机组网，易扩展	受主机控制器和 Hub 限制
典型调优参数	PacketSize、InterPacketDelay、Jumbo Frame	StreamBufferCount、TransferSize

四、相机参数配置与实时取像的实操要点

下面给出一段典型的 HALCON 采集配置示例，使用 GigE Vision 接口，开启连续采集并设置曝光和增益。示例参数为教学假设值，实际需按相机型号和现场光照调整。

open_framegrabber('GigEVision2', 0, 0, 0, 0, 0, 0, 'progressive',
                  -1, 'default', -1, 'false', 'default', 'cam_01', 0, -1, AcqHandle)

set_framegrabber_param(AcqHandle, 'Width', 1280)
set_framegrabber_param(AcqHandle, 'Height', 1024)
set_framegrabber_param(AcqHandle, 'PixelFormat', 'Mono8')
set_framegrabber_param(AcqHandle, 'ExposureTime', 5000)
set_framegrabber_param(AcqHandle, 'Gain', 6.0)
set_framegrabber_param(AcqHandle, 'AcquisitionFrameRate', 30.0)
set_framegrabber_param(AcqHandle, 'TriggerMode', 'Off')

grab_image_async(Image, AcqHandle, -1)
* 处理 Image ...
close_framegrabber(AcqHandle)

实时取像时，grab_image_async 的第三个参数是超时时间（毫秒），-1 表示无限等待。若使用软触发，则先设 TriggerMode='On'、TriggerSource='Software'，再调用 grab_image_async 后执行 set_framegrabber_param(AcqHandle,'TriggerSoftware',0) 发出触发。硬触发则把 TriggerSource 设为 'Line0'，并配置 TriggerActivation 为 'RisingEdge' 或 'FallingEdge'。

连续采集时不要在主循环里反复 open_framegrabber 和 close_framegrabber，这会导致相机重新枚举、丢帧甚至掉线。正确做法是打开一次，循环内只调用 grab_image_async，退出时统一关闭。

五、结果观察与判断依据

取像是否正常，可以从三个层面判断。第一，算子返回值：grab_image_async 成功返回图像对象，失败会抛异常或返回错误码。第二，图像统计：用 min_max_gray 查看灰度范围，若最小值等于最大值，说明图像全黑或全白，通常是曝光、增益或触发配置错误。第三，帧率与丢帧：用 count_seconds 统计连续 100 帧耗时，若明显低于设定帧率，检查 PacketSize、网卡巨帧、USB 控制器带宽或主机 CPU 占用。

一个实用的排查顺序是：先确认相机在厂商工具中能正常出图，再回到 HALCON 检查接口名和参数名，最后检查网络/USB 带宽与触发时序。这样能把“相机问题”和“配置问题”快速分开，避免在错误方向上反复调整。