📚 课程目录第4章 Teledyne相机SDK与开发环境搭建

4. Teledyne相机SDK与开发环境搭建

Teledyne 旗下的工业相机产品线覆盖 DALSA、e2v、Photometrics 等多个品牌，不同系列的 SDK 并不通用。以最常见的 GenICam 兼容面阵相机（如 Teledyne DALSA Genie Nano、Linea 系列）为例，官方统一使用 Sapera LT SDK 作为采集与设备控制的核心库；而部分高速/线扫相机则可能配套 Teledyne DALSA Sapera LT + GigE Vision Filter Driver 或 Teledyne FLIR Spinnaker（针对原 Point Grey 系列）。因此，环境搭建的第一步不是急着装软件，而是先确认相机型号对应的 SDK 分支，否则后续枚举和采集都会失败。

一、SDK 安装与版本选择

从 Teledyne 官方支持站点下载 Sapera LT 时，需要同时关注三个版本维度：SDK 主版本（如 8.60、9.00）、操作系统位数（x64 为主流）、以及是否包含 GigE Vision Filter Driver。安装包通常为 Sapera_LT_8.60.00.xxxx_x64.exe 形式。安装过程中建议勾选以下组件：

Sapera LT Runtime：核心运行时，提供 SapClass、SapAcqDevice 等 C++ 类库；
GigE Vision Filter Driver：用于绕过 Windows 默认网卡协议栈，降低丢包率；
CamExpert：官方相机配置与诊断工具，用于验证枚举和参数读写；
示例代码与头文件：位于 C:\Program Files\Teledyne DALSA\Sapera\Examples。

安装完成后，需要将 Sapera\Include 和 Sapera\Classes\Basic 加入 Visual Studio 的包含目录，将 Sapera\Lib\Win64 加入库目录，并在链接器中加入 SapClass.lib、SapAcqDevice.lib、SapBuffer.lib。若使用 C#，则引用 SapClassNET.dll 与 SapAcqDeviceNET.dll。

二、驱动配置与网络参数

GigE 相机对网络环境敏感。推荐为相机单独分配一块千兆网卡，并关闭该网卡的“节能以太网”“中断节流”等选项。相机默认使用链路本地地址（169.254.x.x）或 DHCP，若网络中没有 DHCP 服务器，需手动将主机网卡设为同网段静态 IP，例如相机为 169.254.10.20，主机设为 169.254.10.10，子网掩码 255.255.0.0。随后在 CamExpert 中点击“Detect Cameras”，若能列出设备，说明驱动与网络配置正确。

若相机未被枚举，优先检查：网卡是否被 Sapera 过滤器驱动接管、防火墙是否拦截了 GigE Vision 发现端口（通常为 UDP 3956）、相机是否处于同一子网。

三、相机枚举与连接

Sapera LT 提供两种枚举方式：基于设备名的 SapAcqDevice::GetDeviceCount() 与基于 GenICam 的 SapManager 枚举。实际开发中更常用后者，因为它能返回设备序列号、IP、厂商等完整信息。以下为 C++ 枚举与连接的核心片段：

#include "SapClassBasic.h"

SapManager *pMgr = SapManager::GetInstance();
int count = pMgr->GetResourceCount(SapManager::ResourceAcqDevice);
for (int i = 0; i < count; i++) {
    char name[CORSERVER_MAX_STRLEN];
    pMgr->GetResourceName(SapManager::ResourceAcqDevice, i, name);
    printf("Device %d: %s\n", i, name);
}

SapAcqDevice acqDev("Genie_Nano_01");
if (!acqDev.Create()) {
    printf("Create failed: %s\n", acqDev.GetCreateStatus());
    return -1;
}
acqDev.SetParameter("AcquisitionMode", "Continuous");
acqDev.SetParameter("ExposureTime", 5000);   // 单位微秒
acqDev.SetParameter("Gain", 6);              // 单位 dB

连接成功后，建议先读取 DeviceTemperature、Width、Height、PixelFormat 等参数，确认相机处于预期状态。若 Create() 返回失败，可通过 GetCreateStatus() 获取错误码，常见原因包括：相机被 CamExpert 占用、IP 冲突、固件版本与 SDK 不匹配。

四、基础采集示例与结果判读

采集流程遵循“创建缓冲区—注册回调—启动采集—取图—停止”的固定链路。Sapera LT 使用 SapBuffer 管理图像内存，SapAcqDevice 负责触发与传输。以下示例采用连续采集模式，抓取 10 帧后停止：

SapBuffer *pBuffers[4];
for (int i = 0; i < 4; i++) {
    pBuffers[i] = new SapBuffer(1, &acqDev);
    pBuffers[i]->Create();
}

SapAcqDeviceToBuf *pAcq = new SapAcqDeviceToBuf(&acqDev, pBuffers[0]);
pAcq->Create();
pAcq->Grab();          // 启动连续采集

for (int f = 0; f < 10; f++) {
    pAcq->Wait(2000);  // 等待一帧，超时 2000 ms
    void *pData;
    pBuffers[f % 4]->GetAddress(&pData);
    printf("Frame %d acquired, addr=%p\n", f, pData);
}

pAcq->Freeze();
pAcq->Destroy();

结果判读主要看三点：帧计数是否稳定递增、Wait() 是否频繁超时、图像首行数据是否出现全黑或全白。若帧率远低于设定值，可检查 AcquisitionFrameRate、ExposureTime 与网卡带宽是否匹配；若出现丢包，则启用 GigE Vision Filter Driver 并增大 ReceiveBuffer。

五、常见问题与排查顺序

实际搭建中，最典型的故障是“CamExpert 能看到相机，但代码枚举不到”。这通常是因为 CamExpert 占用了设备句柄，关闭 CamExpert 后重新运行程序即可。其次是“能连接但采集超时”，此时应检查 PacketSize 是否超过网卡 MTU（默认 1500，若网卡支持 Jumbo Frame 可设为 9000），以及 InterPacketDelay 是否过小导致相机发送速率超过主机接收能力。建议的排查顺序为：物理链路 → 网卡驱动 → IP 配置 → 枚举 → Create → 参数读写 → 采集 → 图像判读，逐层缩小范围，避免在多个环节同时改动。

Sapera LT 的 32 位与 64 位库不可混用；若项目为 x64，务必确认链接的是 Lib\Win64 下的库文件，否则会在运行期出现无法解析的符号错误。

完成上述步骤后，开发者应能稳定枚举到 Teledyne 相机、建立连接、配置曝光与增益，并连续采集到有效图像。这一套环境是后续高分辨率图像处理、标定与检测算法开发的基础，建议在项目初期就将 SDK 版本、网卡型号、相机固件版本记录在案，便于后续复现与排障。