智能制造与工业软件 / 系统课时
使用 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 接收相机发送的图像并交给缓冲区。两条链路使用同一个相机连接,但参数节点与图像数据不是一回事。

检查连接环境与采集参数
先确认相机在厂商自带的相机查看工具中能被发现并实时预览。USB3 Vision 相机应检查 USB3 接口与驱动;GigE Vision 相机应检查网卡和相机 IP 是否可达、是否位于可通信的网段。关闭厂商查看工具的占用连接后,再运行脚本。
- 安装与操作系统、CPU 架构匹配的厂商 SDK 和 64 位 GenTL Producer,找到 SDK 安装目录下的
.cti绝对路径;保持文件在原目录,不单独拷贝,以免缺少依赖库。 - 使用 64 位 CPython 3.10 或 3.11 建立实验环境;先验证
genicamPython 绑定及.cti与本机兼容。 - 在终端安装并验证 Harvester 1.4.3。其 Python 包负责调用 Producer,不能替代厂商驱动。
python -m pip install "harvesters==1.4.3" pillow
python -c "from harvesters.core import Harvester; print('Harvester import OK')"预期输出:安装日志因环境而异,最后一行包含以下内容。
Harvester import OK本次使用以下三个节点,均应在停止采集时设置;设备未实现或暂时只读的节点不能强行写入。
| GenICam 节点 | 本次值 | 作用与注意点 |
|---|---|---|
AcquisitionMode |
Continuous |
连续采集而非只采一帧 |
TriggerMode |
Off |
先取消外部触发,排除无触发信号导致的等待 |
PixelFormat |
Mono8 |
8 位单通道图像;仅适用于支持该格式的相机 |
完成设备枚举、打开及首帧读取
将以下代码保存为 capture.py。示例限定只接入一台、支持 Mono8 和上述采集节点的相机,遇到多相机或不支持的像素格式会明确报错,避免误取产线上的其他设备。正式项目宜按序列号选择设备,而不是长期依赖列表索引 0。
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 的绝对路径,运行:
python capture.py "<PATH>"预期输出格式如下;<ID>、<MODEL>、<WIDTH>、<HEIGHT>、<MIN>、<MAX> 都来自实际设备和图像,不是固定值。
发现相机:1
设备:<MODEL>,SN=<ID>
采集模式:Continuous;触发:Off;像素格式:Mono8
帧:<WIDTH>x<HEIGHT>,类型:uint8
灰度最小/最大:<MIN>/<MAX>
已保存:frame.pngfetch(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 介绍。