智能制造与工业软件 / 系统课时

使用 GenICam 参数连接相机

使用 GenICam 参数连接相机

把工业相机接入检测程序,需要先找到设备,再通过 GenICam 节点设置采集参数,最后从图像缓冲区取出一帧。本课使用 Python Harvester 和厂商 GenTL 驱动完成单相机连续采集,保存一张可检查的灰度图。

学习目标

  • 区分厂商相机 SDK、GenTL Producer、GenApi 节点映射与采集程序的职责。
  • 枚举并打开相机,读取及设置 AcquisitionMode、TriggerMode、PixelFormat。
  • 获取并保存 Mono8 帧,验证尺寸、像素范围与缓冲区释放行为。

SDK、GenICam 与图像流怎样协作

GenICam 并不是一套可以直接驱动所有相机的独立程序。GenApi 按设备提供的 XML 描述构建节点映射(NodeMap),SFNC 约定常见节点名;GenTL 规定设备枚举与图像传输接口。厂商 SDK 中的 GenTL Producer 通常以 .cti 库文件提供,并依赖其配套驱动。

本例用 harvesters 充当 GenTL Consumer:控制侧经 remote_device.node_map 写入相机参数,采集侧经 Producer 接收相机发送的图像并交给缓冲区。两条链路使用同一个相机连接,但参数节点与图像数据不是一回事。

GenICam参数控制与图像采集的双链路关系

检查连接环境与采集参数

先确认相机在厂商自带的相机查看工具中能被发现并实时预览。USB3 Vision 相机应检查 USB3 接口与驱动;GigE Vision 相机应检查网卡和相机 IP 是否可达、是否位于可通信的网段。关闭厂商查看工具的占用连接后,再运行脚本。

  1. 安装与操作系统、CPU 架构匹配的厂商 SDK 和 64 位 GenTL Producer,找到 SDK 安装目录下的 .cti 绝对路径;保持文件在原目录,不单独拷贝,以免缺少依赖库。
  2. 使用 64 位 CPython 3.10 或 3.11 建立实验环境;先验证 genicam Python 绑定及 .cti 与本机兼容。
  3. 在终端安装并验证 Harvester 1.4.3。其 Python 包负责调用 Producer,不能替代厂商驱动。
bash
python -m pip install "harvesters==1.4.3" pillow
python -c "from harvesters.core import Harvester; print('Harvester import OK')"

预期输出:安装日志因环境而异,最后一行包含以下内容。

text
Harvester import OK

本次使用以下三个节点,均应在停止采集时设置;设备未实现或暂时只读的节点不能强行写入。

GenICam 节点 本次值 作用与注意点
AcquisitionMode Continuous 连续采集而非只采一帧
TriggerMode Off 先取消外部触发,排除无触发信号导致的等待
PixelFormat Mono8 8 位单通道图像;仅适用于支持该格式的相机

完成设备枚举、打开及首帧读取

将以下代码保存为 capture.py。示例限定只接入一台、支持 Mono8 和上述采集节点的相机,遇到多相机或不支持的像素格式会明确报错,避免误取产线上的其他设备。正式项目宜按序列号选择设备,而不是长期依赖列表索引 0。

python
from pathlib import Path
from sys import argv

from harvesters.core import Harvester
from PIL import Image

def main():
    if len(argv) != 2:
        raise SystemExit("用法:python capture.py <CTI文件绝对路径>")
    cti = Path(argv[1])
    if not cti.is_file():
        raise FileNotFoundError(cti)

    with Harvester() as h:
        h.add_file(str(cti), check_existence=True)
        h.update()  # 加载 Producer 后刷新设备列表
        print(f"发现相机:{len(h.device_info_list)}")
        if len(h.device_info_list) != 1:
            raise RuntimeError("本例要求恰好连接一台相机")
        info = h.device_info_list[0]
        print(f"设备:{info.model},SN={info.serial_number}")

        with h.create(0) as ia:
            nodes = ia.remote_device.node_map
            # 开始传输前完成配置,避免运行时节点被锁定。
            nodes.AcquisitionMode.value = "Continuous"
            nodes.TriggerMode.value = "Off"
            if "Mono8" not in nodes.PixelFormat.symbolics:
                raise RuntimeError(f"不支持 Mono8:{nodes.PixelFormat.symbolics}")
            nodes.PixelFormat.value = "Mono8"
            print(f"采集模式:{nodes.AcquisitionMode.value};触发:{nodes.TriggerMode.value};像素格式:{nodes.PixelFormat.value}")

            ia.start()
            try:
                with ia.fetch(timeout=3.0) as buffer:
                    component = buffer.payload.components[0]
                    if component.data_format != "Mono8":
                        raise RuntimeError("收到的不是 Mono8 图像")
                    # 归还缓冲前复制,避免后续访问被复用的内存。
                    image = component.data.reshape(
                        component.height, component.width
                    ).copy()
            finally:
                ia.stop()

    Image.fromarray(image).save("frame.png")
    print(f"帧:{image.shape[1]}x{image.shape[0]},类型:{image.dtype}")
    print(f"灰度最小/最大:{image.min()}/{image.max()}")
    print("已保存:frame.png")

if __name__ == "__main__":
    main()

把 <PATH> 替换为实际 .cti 的绝对路径,运行:

bash
python capture.py "<PATH>"

预期输出格式如下;<ID>、<MODEL>、<WIDTH>、<HEIGHT>、<MIN>、<MAX> 都来自实际设备和图像,不是固定值。

text
发现相机:1
设备:<MODEL>,SN=<ID>
采集模式:Continuous;触发:Off;像素格式:Mono8
帧:<WIDTH>x<HEIGHT>,类型:uint8
灰度最小/最大:<MIN>/<MAX>
已保存:frame.png

fetch(timeout=3.0) 的超时单位是秒。with ia.fetch(...) 退出时会自动把缓冲区归还采集队列;.copy() 则使保存图像不再依赖这块缓冲。with h.create(0) 和 with Harvester() 负责在退出时分别释放相机和 Producer 资源。

验收图像并定位常见失败

打开输出的 frame.png:画面应对应当前工件,图像宽高与设备 ROI 设置一致;Mono8 的数组类型为 uint8,像素值范围为 0~255。改变镜头前物体或照明后重采一帧,灰度极值或画面应随之变化。重复运行五次,确认均能成功关闭、重新打开并保存图像。

现象 优先检查与修复
发现相机数为 0 先用厂商查看工具验证驱动与连接;核对 .cti 路径、64 位架构以及 GigE 网段
打开时设备占用 关闭厂商查看工具或其他采集进程,再重新枚举
PixelFormat 写入失败 查看 nodes.PixelFormat.symbolics,确认确有 Mono8;彩色 Bayer 相机不能直接按灰度二维图处理
获取帧超时 先查 TriggerMode=Off 是否已生效,再查供电、传输带宽和 GigE 丢包;外触发模式必须另行提供触发信号
图像全黑或全白 先检查光源、镜头盖、曝光与增益;可在设备支持且可写时调整 ExposureTime,例如从 5000 μs 试起并核对允许范围

验收通过的标志是:能枚举目标设备,读回三个参数,3 秒内得到完整 Mono8 帧,图像内容随场景变化,重复运行不会因缓冲区或设备句柄未释放而失败。接口细节可对照 Harvester 官方教程 和 EMVA GenICam 介绍。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

使用 GenICam 参数连接相机

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通