第1章 厂商SDK基础差异扫描
不同相机厂商提供的SDK在底层设计理念上存在显著差异，这些差异直接影响上层适配代码的复杂度。本章从接口命名风格、数据类型约定、回调机制、错误码体系四个维度展开扫描，为后续章节的案例适配奠定认知基础。
1.1 接口命名风格
| 厂商 | 前缀/命名规范 | 示例 |
|---|---|---|
| Basler（Pylon） | C++风格、对象方法，Pylon::命名空间 | camera.Open()、camera.StartGrabbing() |
| FLIR（Spinnaker） | 大驼峰、节点式访问，Spinnaker::命名空间 | system.GetCameras()、camera.BeginAcquisition() |
| Point Grey（FlyCapture2） | C风格、函数加前缀 | flycaptureCreateContext()、flycaptureStartCapture() |
| 大恒（Daheng） | C风格、GX_前缀 | GXOpenDevice()、GXStreamOn() |
| 海康（MVS） | C风格、MV_前缀 | MV_CC_CreateHandle()、MV_CC_StartGrabbing() |
适配原则：接口命名差异会导致调用方式完全不同，建议在适配层定义一个统一的抽象接口（如
ICameraDevice），用工厂模式根据厂商字符串实例化具体SDK实现，避免业务代码直接依赖厂商 API。
1.2 数据类型约定
各厂商对图像帧、设备信息、参数范围等数据结构的定义差异很大，尤其注意字节序、对齐、内存所有权。
| 维度 | 典型差异 | 适配示例 |
|---|---|---|
| 图像帧 | Basler 使用 CPylonImage，FLIR 使用 ImagePtr，大恒使用 GX_FRAME_BUFFER | 统一转换为 FrameData 结构：width, height, pixelFormat, dataBuffer, dataSize |
| 设备信息 | Basler 提供 DeviceInfoList，海康返回 MV_CC_DEVICE_INFO | 提取共性字段：vendor, model, serialNumber, ipAddress |
| 参数类型 | 整型参数可能用 int64（Basler）或 unsigned int（大恒）；浮点参数精度不同 | 适配层提供 SetParam(name, valueVariant)，内部按厂商转换 |
| 内存管理 | 某些SDK要求用户预分配缓冲区（FlyCapture2），某些SDK内部管理（Pylon） | 适配层统一采用“拷贝出内存”或“引用计数”策略 |
1.3 回调机制
回调是实时图像处理的关键，但各厂商的回调触发线程、参数传递、注册方式各不相同。
- Basler Pylon：在
InstantCamera上注册ConfigurationEventHandler和ImageEventHandler，回调运行在SDK内部线程池，用户不能在回调中执行长时间阻塞操作。 - Spinnaker：通过
ImageEvent或轮询GetNextImage()获取帧，推荐异步回调模式，但需要用户显式释放图像对象。 - 大恒 GxIAPI：注册
GXRegisterCaptureCallback，回调参数中包含GX_FRAME_CALLBACK_PARAM，线程上下文由用户设定。 - 海康 MVS：调用
MV_CC_RegisterImageCallBackEx，回调中传递MV_FRAME_OUT_INFO_EX和数据指针。
常见陷阱：回调内部直接操作UI或进行耗时的写盘操作，会导致图像队列堆积、丢帧甚至SDK崩溃。解决方案：回调内只做轻量级数据拷贝和事件信号发送，交由专用工作线程处理。
1.4 错误码体系
错误码的命名、取值范围、含义差异巨大，统一的错误处理逻辑是适配中较早暴露的问题。
| 厂商 | 成功标识 | 错误码结构 | 典型错误示例 |
|---|---|---|---|
| Basler | 返回 GENAPI_EOK（=0） | 枚举值，如 GENAPI_E_INVALID_HANDLE | GENAPI_E_INVALID_HANDLE（0x80020003） |
| Spinnaker | 返回 Spinnaker::GenApi::GENAPI_E_OK | C++异常也可捕获 Spinnaker::Exception | Spinnaker::Exception: Not initialized |
| 大恒 | 返回 GX_STATUS_SUCCESS（=0） | 32位负数错误码，如 GX_STATUS_ERROR | GX_STATUS_NOT_FOUND（-6） |
| 海康 | 返回 MV_OK（=0） | 32位负值，用 unsigned int 接收时需注意 | MV_E_COMM_FAILURE（-3） |
统一错误码映射策略：在适配层定义内部错误码枚举（如
ErrCode::SUCCESS, ErrCode::TIMEOUT, ErrCode::NOT_FOUND），在厂商实现中将原生错误码通过静态映射表转换成内部码，业务代码只依赖内部码。
1.5 四个维度的关联与适配流程图
1.6 调试与部署要点
- 日志开关：开发阶段打开SDK自带的调试日志（如Basler的
Pylon.Logger、海康的MV_CC_SetSDKLogPath()），便于定位初始化失败或回调异常。 - 错误码转字符串：适配层应提供
GetErrorString(ErrCode)函数，内部调用各SDK的ErrorCodeToDescription或类似API，确保调试时能直接看到可读信息。 - 部署注意事项：不同SDK的运行时库、设备驱动、GenICam注册表等需要同时安装。建议为每个厂商创建独立的部署包，通过环境变量或配置文件决定加载哪个SDK，避免版本冲突。
推荐实践：第一阶段先实现一个“最小可行适配器”，仅覆盖一个常用厂商（如Basler），然后逐步添加第二个厂商的适配，此时四个维度的差异会非常直观暴露，及时调整抽象层设计可大幅减小后续成本。