3. pylon Viewer快速上手与参数调试

pylon Viewer 是 Basler pylon 软件平台自带的图形化相机调试工具，它把 GigE、USB3、CoaXPress 等接口相机的枚举、连接、取流、参数读写和图像保存集中在一个界面里。对刚接触 Basler 相机的开发者来说，先用 pylon Viewer 把相机跑通、把参数调对，再把这些参数迁移到 pylon SDK 代码中，是最省时间的路径。本节围绕界面布局、参数树、实时取流、曝光/增益/白平衡、像素格式、ROI、触发模式以及参数与图像的保存加载，给出一条可复现的调试主线。

界面布局与设备连接

pylon Viewer 主窗口大致分为四个区域：左侧是设备树（Device Tree），列出本机识别到的所有 Basler 相机及其接口类型；中间是图像显示区，用于实时预览和抓取单帧；右侧是参数树（Feature Tree），按类别组织相机所有 GenICam 特征；底部是状态与消息栏，显示连接状态、帧率、丢帧统计和错误信息。打开软件后，在设备树中双击目标相机即可建立连接，连接成功后状态栏会显示相机型号、序列号和当前采集状态。

如果设备树为空，通常需要检查三件事：网口相机是否与主机在同一网段、USB3 相机驱动是否安装、以及是否被其他进程（如另一份 pylon Viewer 或自研程序）占用。GigE 相机建议启用巨帧（Jumbo Frame），并把相机与主机置于独立网卡，避免与办公网络争抢带宽。

相机参数树的结构与读写逻辑

参数树是 pylon Viewer 的核心。它按 Image Format Control、Acquisition Control、Analog Control、Digital IO Control 等分组，每个节点对应一个 GenICam 特征。节点有几种典型状态：可读写的（如 ExposureTime）、只读的（如 ResultingFrameRate）、以及受其他参数约束而暂时不可用的（灰色）。理解“参数之间的依赖”比记住每个参数名更重要——例如像素格式会限制最大帧率，ROI 尺寸会影响帧率与带宽，触发模式会改变采集的启动方式。

实时图像采集与曝光/增益调节

连接相机后，点击工具栏的连续采集按钮即可看到实时画面。此时先关注底部状态栏的帧率是否稳定、有无丢帧。若帧率远低于预期，优先检查网卡带宽、ROI 是否过大、像素格式是否为高数据量格式。

曝光和增益在 Analog Control 组中。曝光时间（ExposureTime）决定传感器积分时间，单位微秒；增益（Gain）是对信号的电学放大，单位 dB。调试原则是：优先加曝光，慎加增益。曝光增加会提升亮度但可能引入运动模糊；增益增加会提升亮度但会放大噪声。以一条产线上的静态零件检测为例，可先把增益设为 0 dB，逐步增加曝光时间，直到图像直方图主体落在中高灰度区间且不过曝。若曝光已接近上限（受帧率约束）仍偏暗，再小幅增加增益，每次 1～2 dB，观察噪声是否可接受。

白平衡用于彩色相机。在 Analog Control 中可切换 BalanceWhiteAuto 为 Once 或 Continuous，也可手动设置 BalanceRatioRed、BalanceRatioGreen、BalanceRatioBlue。对颜色检测任务，建议先用 Once 在标准白板下完成一次白平衡，再切回 Off 锁定，避免自动白平衡在运行中漂移导致颜色判据不稳定。

像素格式切换与 ROI 设置

像素格式在 Image Format Control 的 PixelFormat 中选择。黑白相机常用 Mono8、Mono12；彩色相机常用 BayerRG8、BayerRG12、RGB8、BGR8。Mono8 每像素 1 字节，BayerRG8 也是 1 字节但需去马赛克，RGB8 每像素 3 字节，带宽是 Mono8 的三倍。切换格式后要重新确认帧率是否满足节拍。

ROI 同样在 Image Format Control 中设置，包括 Width、Height、OffsetX、OffsetY。缩小 ROI 能显著提高帧率并降低带宽。例如把 1920×1200 缩到 800×600，数据量约为原来的 20.8%，在带宽受限时帧率可明显回升。设置 Offset 时要注意不能超出传感器有效区域，且部分相机对 Offset 有对齐要求（如 2 或 4 像素对齐）。

触发模式配置

触发模式在 Acquisition Control 中配置。关键参数包括 TriggerMode（Off/On）、TriggerSource（Software、Line1、Line2 等）、TriggerActivation（RisingEdge/FallingEdge）以及 TriggerDelay。自由运行用 TriggerMode=Off；软触发用 TriggerMode=On、TriggerSource=Software，然后在 pylon Viewer 中点击软触发按钮；硬触发用 TriggerSource=Line1，由外部光电传感器或 PLC 给出上升沿。配置硬触发时，还要确认 LineSelector 与 LineMode 的输入输出方向正确，否则触发信号进不来。

参数保存与加载、图像保存与录像

调好参数后，pylon Viewer 支持把当前相机特征保存为 .pfs 文件（Feature Stream），也可保存为 .csv 便于查看。加载时选择对应文件即可把参数写回相机。注意：.pfs 保存的是特征值，不包含固件版本差异带来的兼容性问题，跨型号加载可能失败，建议同型号复用。

图像保存方面，pylon Viewer 支持单帧保存为 BMP、JPEG、PNG、TIFF 等格式，也支持连续录像保存为 AVI 或图像序列。录像时要注意磁盘写入速度，高分辨率高帧率下建议使用 SSD 并预留足够空间。保存路径和文件名可在保存对话框中设置，也可启用自动命名规则。

一个可复用的参数调试记录表

下面给出一份可直接填写的参数记录表示例，用于把 pylon Viewer 中的调试结果固化下来，方便迁移到 pylon SDK 代码或交接给同事。

把这张表填完，再导出 .pfs，你就完成了一次完整的 pylon Viewer 调试闭环。后续在 pylon SDK 中，只需按表中参数名调用对应的 CInstantCamera 特征接口，即可复现同样的采集效果。