3. Basler pylon SDK环境搭建与相机连接

在开始任何USB3视觉采集程序之前，必须先把“软件栈”和“物理链路”这两层打通。pylon SDK是Basler相机的官方开发包，它同时提供驱动、运行时库、相机枚举工具和示例代码。本节围绕pylon安装、相机枚举、IP配置、USB3端口兼容性检查以及第一个取流程序展开，目标是让一台Basler USB3相机在Windows或Linux主机上稳定出现在pylon Viewer中，并能被C++或Python程序成功取流。

一、pylon安装：选对组件比装得快更重要

从Basler官网下载pylon Camera Software Suite时，需要根据主机操作系统和开发语言选择安装包。Windows下通常选择pylon x.x.x Windows 64-bit，安装向导中会出现几个关键选项：

• pylon Viewer：图形化工具，用于枚举、配置和预览相机，是排障的第一入口。
• pylon Runtime：运行时库，任何基于pylon的应用程序都依赖它。
• USB3 Vision Driver：USB3相机的底层驱动，必须勾选，否则相机无法被识别为USB3 Vision设备。
• SDK Development Files：C++头文件、库文件和示例工程，做二次开发时必须安装。
• Python Bindings：如果使用pypylon，需要额外安装pypylon包，通常通过pip完成。

安装完成后，建议先重启系统，让USB3 Vision驱动完成注册。随后打开pylon Viewer，如果左侧设备树中能看到相机型号，说明驱动层已经就绪。若使用Python，可在命令行执行：

pip install pypylon
python -c "from pypylon import pylon; print(pylon.__version__)"

能打印出版本号，说明Python绑定可用。注意pypylon版本要与pylon Runtime版本匹配，否则可能出现“找不到pylon运行时”的错误。

二、相机枚举：从设备树到代码枚举

pylon Viewer中的设备树是最直观的枚举结果。USB3相机通常会显示为“Basler ace 2”或具体型号，并带有USB3图标。如果设备树为空，先检查USB线是否插在蓝色USB3口上，再检查设备管理器中是否出现“Basler USB3 Vision”设备。

在代码中，pylon提供了TlFactory和InstantCamera两层接口。枚举相机的典型C++代码如下：

#include <pylon/PylonIncludes.h>
using namespace Pylon;

int main() {
    PylonInitialize();
    CTlFactory& tlFactory = CTlFactory::GetInstance();
    DeviceInfoList_t devices;
    tlFactory.EnumerateDevices(devices);
    std::cout << "Found " << devices.size() << " camera(s)" << std::endl;
    for (auto& dev : devices) {
        std::cout << dev.GetModelName() << " | "
                  << dev.GetSerialNumber() << " | "
                  << dev.GetDeviceClass() << std::endl;
    }
    PylonTerminate();
    return 0;
}

Python下更简洁：

from pypylon import pylon
tl_factory = pylon.TlFactory.GetInstance()
devices = tl_factory.EnumerateDevices()
for dev in devices:
    print(dev.GetModelName(), dev.GetSerialNumber())

枚举结果中应包含型号、序列号和设备类。如果枚举到设备但无法打开，通常是驱动或权限问题，而不是枚举失败。

三、IP配置与USB3端口兼容性检查

USB3相机本身不依赖IP地址，但pylon Viewer中若同时存在GigE相机，IP配置会出现在同一界面。对于纯USB3相机，重点不是IP，而是USB3端口兼容性。很多主机虽然标称USB3，但实际端口由第三方控制器提供，带宽或供电不足，导致相机只能以USB2速度枚举，或在高帧率下丢包。

检查方法分三步：

1. 在pylon Viewer中选中相机，查看Device Information中的Device Link Speed，应为SuperSpeed而非High Speed。
2. 在Windows设备管理器中查看USB控制器，确认相机挂在USB 3.0 eXtensible Host Controller下，而不是USB 2.0 Hub。
3. 使用Basler提供的pylon USB Configurator或第三方工具查看端口带宽占用，避免多个USB3设备共享同一控制器导致带宽争用。

如果发现相机以USB2速度运行，优先更换主板原生USB3端口，避免使用前面板延长线或廉价Hub。对于高分辨率相机，建议将相机单独挂在一个USB3控制器上。

四、第一个取流程序：从打开相机到保存一帧

下面给出一个最小可用的C++取流程序，它完成初始化、打开第一台相机、设置连续采集模式、抓取一帧并保存为PNG。示例参数为合理假设：曝光时间设为5000微秒，增益设为0 dB，帧率由相机自动决定。

#include <pylon/PylonIncludes.h>
#include <pylon/PylonImage.h>
#include <pylon/PylonUtility.h>
using namespace Pylon;
using namespace std;

int main() {
    PylonInitialize();
    try {
        CInstantCamera camera(CTlFactory::GetInstance().CreateFirstDevice());
        cout << "Using: " << camera.GetDeviceInfo().GetModelName() << endl;

        camera.Open();
        camera.ExposureTime.SetValue(5000.0);
        camera.Gain.SetValue(0.0);

        camera.StartGrabbing(GrabStrategy_LatestImageOnly);
        CGrabResultPtr ptrGrabResult;
        if (camera.RetrieveResult(5000, ptrGrabResult, TimeoutHandling_ThrowException)) {
            if (ptrGrabResult->GrabSucceeded()) {
                cout << "Frame " << ptrGrabResult->GetImageNumber()
                     << " size " << ptrGrabResult->GetWidth()
                     << "x" << ptrGrabResult->GetHeight() << endl;
                CPylonImage image;
                image.AttachGrabResultBuffer(ptrGrabResult);
                CImagePersistence::Save(ImageFileFormat_Png, "first_frame.png", image);
            } else {
                cerr << "Grab failed: " << ptrGrabResult->GetErrorDescription() << endl;
            }
        }
        camera.StopGrabbing();
        camera.Close();
    } catch (const GenericException& e) {
        cerr << "Error: " << e.GetDescription() << endl;
    }
    PylonTerminate();
    return 0;
}

Python版本更短：

from pypylon import pylon
camera = pylon.InstantCamera(pylon.TlFactory.GetInstance().CreateFirstDevice())
camera.Open()
camera.ExposureTime.Value = 5000.0
camera.StartGrabbing(pylon.GrabStrategy_LatestImageOnly)
result = camera.RetrieveResult(5000, pylon.TimeoutHandling_ThrowException)
if result.GrabSucceeded():
    img = result.Array
    print("frame", result.ImageNumber, img.shape)
    pylon.ImagePersistence.Save(pylon.ImageFileFormat_Png, "first_frame.png", result)
camera.StopGrabbing()
camera.Close()

运行后若输出帧号和分辨率，并在当前目录生成first_frame.png，说明整条链路已经打通。若RetrieveResult超时，优先检查曝光时间是否过长、帧率是否被限制、USB3带宽是否被其他设备占用。若GrabSucceeded()为假，错误描述通常会指出是触发模式未关闭、流通道未使能还是带宽不足。