📚 课程目录第3章相机SDK开发基础

3、相机SDK开发基础：初始化、参数配置与图像采集

相机SDK开发，说白了就是让相机听话。你得告诉它什么时候拍、怎么拍、拍完的数据往哪送。我刚开始接触SDK时，觉得文档又长又乱，后来发现核心流程就那么几步。今天咱们就把这层窗户纸捅破。

3.1 相机初始化流程

初始化是第一步，也是最容易出问题的一步。我个人习惯把初始化拆成四个阶段：

枚举设备——找到相机
创建句柄——拿到控制权
打开设备——建立连接
开始采集——进入工作状态

你想想看，这跟开车很像：先找车钥匙（枚举），插进钥匙孔（创建句柄），拧到ON档（打开设备），最后挂挡起步（开始采集）。

核心要点：初始化失败90%是因为设备枚举没找到相机，或者句柄重复创建。每次初始化前，务必先释放上一次的资源。

下面是一段典型的初始化代码（以海康威视SDK为例）：

// 1. 枚举设备
MV_CC_DEVICE_INFO_LIST stDeviceList;
memset(&stDeviceList, 0, sizeof(MV_CC_DEVICE_INFO_LIST));
nRet = MV_CC_EnumDevices(MV_GIGE_DEVICE | MV_USB_DEVICE, &stDeviceList);
if (nRet != MV_OK) {
    printf("枚举设备失败，错误码：%d\n", nRet);
    return -1;
}

// 2. 创建句柄
void* handle = NULL;
nRet = MV_CC_CreateHandle(&handle, stDeviceList.pDeviceInfo[0]);
if (nRet != MV_OK) {
    printf("创建句柄失败\n");
    return -1;
}

// 3. 打开设备
nRet = MV_CC_OpenDevice(handle);
if (nRet != MV_OK) {
    printf("打开设备失败\n");
    MV_CC_DestroyHandle(handle);
    return -1;
}

// 4. 开始采集
nRet = MV_CC_StartGrabbing(handle);
if (nRet != MV_OK) {
    printf("开始采集失败\n");
    MV_CC_CloseDevice(handle);
    MV_CC_DestroyHandle(handle);
    return -1;
}

我曾经在产线上遇到过一个问题：相机明明插着，但枚举总是返回空列表。查了半天，发现是网卡巨帧（Jumbo Frame）没开。GigE相机对网络配置很敏感，初始化前先确认IP地址、子网掩码、巨帧设置都对得上。

3.2 参数配置：曝光、增益与触发模式

初始化只是热身，真正的调教在参数配置。三个最核心的参数：曝光、增益、触发模式。我习惯把它们叫做“相机三要素”。

3.2.1 曝光时间

曝光时间决定了传感器收集光线的时长。单位通常是微秒（μs）。

长曝光：图像亮，但运动物体会模糊
短曝光：图像暗，但能冻结运动

实际项目中，我一般从1000μs开始试，然后根据图像亮度调整。如果目标在快速运动，我会把曝光压到500μs以下，再配合补光灯。

// 设置曝光时间（单位：微秒）
MVCC_FLOATVALUE stExposure;
stExposure.fCurValue = 2000.0f;  // 2毫秒
nRet = MV_CC_SetFloatValue(handle, "ExposureTime", stExposure.fCurValue);
if (nRet != MV_OK) {
    printf("设置曝光失败\n");
}

3.2.2 增益

增益是电子放大信号。说白了就是图像不够亮时，硬拉亮度。但增益会放大噪声，图像会出现颗粒感。

参数	优点	缺点	我的建议
低增益（0-6dB）	噪声小，图像干净	需要足够光照	优先使用
中增益（6-12dB）	亮度适中	噪声开始明显	可接受范围
高增益（>12dB）	暗光下能成像	噪声严重	尽量避免

我的经验：先调曝光，曝光不够再加增益。增益超过12dB时，图像质量会断崖式下降。如果必须用高增益，记得后续做滤波处理。

3.2.3 触发模式

触发模式决定了相机什么时候拍照。三种模式：

连续采集：相机一直拍，像录像一样
软件触发：程序发指令，相机拍一张
硬件触发：外部信号（如PLC）触发拍照

视觉引导项目里，我几乎只用硬件触发。为什么？因为产线上的工件不会等你。PLC给一个上升沿，相机立刻抓拍，延迟控制在微秒级。

// 设置为硬件触发模式
nRet = MV_CC_SetEnumValue(handle, "TriggerMode", 1);  // 1=开启触发
nRet = MV_CC_SetEnumValue(handle, "TriggerSource", 0); // 0=Line0，硬件触发源

注意：硬件触发时，触发信号的电平和脉宽必须符合相机规格。我见过有人用PLC的24V信号直接接3.3V的相机IO口，结果烧了触发电路。一定要加电平转换或光耦隔离。

3.3 图像采集与回调函数

参数配好了，接下来就是拿图像。两种方式：主动取图和回调函数。

3.3.1 主动取图

主动取图就是程序循环调用取图函数。简单直接，但会阻塞线程。

MV_FRAME_OUT stImageInfo;
nRet = MV_CC_GetImageBuffer(handle, &stImageInfo, 1000); // 超时1000ms
if (nRet == MV_OK) {
    // 处理图像数据
    ProcessImage(stImageInfo.pBufAddr, stImageInfo.nWidth, stImageInfo.nHeight);
    MV_CC_FreeImageBuffer(handle, &stImageInfo);
}

3.3.2 回调函数（推荐）

回调函数是更优雅的方式。你注册一个函数，相机每采集到一帧图像，SDK自动调用它。不阻塞主线程，实时性好。

// 回调函数定义
void __stdcall ImageCallback(MV_FRAME_OUT_INFO_EX* pFrameInfo, void* pData, void* pUser) {
    if (pFrameInfo && pData) {
        printf("收到一帧图像：宽=%d, 高=%d, 大小=%d\n",
               pFrameInfo->nWidth, pFrameInfo->nHeight, pFrameInfo->nFrameLen);
        // 在这里处理图像，比如保存或分析
        SaveImage(pData, pFrameInfo->nWidth, pFrameInfo->nHeight);
    }
}

// 注册回调
nRet = MV_CC_RegisterImageCallBackEx(handle, ImageCallback, NULL);
if (nRet != MV_OK) {
    printf("注册回调失败\n");
}

为什么推荐回调？因为主动取图时，如果图像处理耗时较长，会拖慢采集循环，导致丢帧。回调函数由SDK内部线程调用，你只管处理数据，不用操心时序。

3.4 本章知识体系

下面这张图把相机SDK开发的核心流程串起来了。你可以把它当作开发时的检查清单。

3.5 避坑指南

做SDK开发这些年，我踩过不少坑。挑几个典型的分享给你：

资源泄漏：每次初始化后，程序退出前一定要调用MV_CC_CloseDevice和MV_CC_DestroyHandle。我见过有人开了100次不关，最后系统内存爆了。
回调函数里做耗时操作：回调函数是SDK内部线程调用的，你在里面做图像处理、保存文件，会阻塞采集线程，导致丢帧。正确的做法是把图像数据扔进队列，另起线程处理。
触发信号抖动：硬件触发时，如果信号有毛刺，相机可能会误触发。可以在PLC侧加滤波，或者在相机触发配置里设置去抖时间。

一个小技巧：调试阶段，先用连续采集模式确认相机能正常出图，再切换到触发模式。这样能快速定位问题是出在相机本身还是触发信号上。

好了，相机SDK开发的基础就这些。初始化、参数配置、图像采集，三步走通，后面做视觉引导就顺了。记住：初始化要严谨，参数要调优，采集要高效。这三板斧砍好了，项目就稳了一半。