GrabBag/Device/IKapDevice/README.md

IKapDevice 封装库

简介

IKapDevice 是对 IKapLibrary C 接口的 C++ 封装库，提供了简洁易用的相机操作接口。主要用于获取单张图像和连续采集。

目录结构

IKapDevice/
├── Inc/                    # 公共头文件目录
│   ├── IIKapDevice.h      # 接口类定义
│   └── IKapDevice_global.h # 全局宏定义
├── _Inc/                   # 内部头文件目录
│   └── IKapDevice.h       # 实现类定义
├── Src/                    # 源文件目录
│   └── IKapDevice.cpp     # 实现类源文件
├── IKapDevice.pro          # qmake 工程文件
└── README.md               # 说明文档

特性

• ✅ 支持相机枚举和设备信息查询
• ✅ 支持单张图像采集（同步模式）
• ✅ 支持连续图像采集（异步模式，回调函数）
• ✅ 支持常用相机参数设置（曝光、增益、触发模式等）
• ✅ 支持 ROI 设置
• ✅ 线程安全设计
• ✅ 跨平台支持（Windows x64 / Linux ARM）

接口设计

核心接口

class IIKapDevice
{
public:
    // 创建设备对象
    static int CreateObject(IIKapDevice** ppDevice);

    // 库初始化/释放
    virtual int InitLibrary() = 0;
    virtual int TerminateLibrary() = 0;

    // 枚举设备
    virtual int EnumerateDevices(unsigned int& nCount) = 0;
    virtual int GetDeviceInfo(unsigned int nIndex, IKapDeviceInfo& deviceInfo) = 0;

    // 打开/关闭设备
    virtual int OpenDevice(unsigned int nIndex, int accessMode = 4) = 0;
    virtual int CloseDevice() = 0;

    // 采集图像
    virtual int GrabSingleFrame(ImageData& imageData, unsigned int nTimeout = 5000) = 0;
    virtual int StartGrabbing(ImageCallback callback, void* pUser = nullptr) = 0;
    virtual int StopGrabbing() = 0;

    // 参数设置
    virtual int SetExposureTime(double exposureTime) = 0;
    virtual int GetExposureTime(double& exposureTime) = 0;
    virtual int SetGain(double gain) = 0;
    virtual int GetGain(double& gain) = 0;
    // ... 其他接口
};

使用示例

示例 1: 获取单张图像

#include "IIKapDevice.h"

int main()
{
    // 1. 创建设备对象
    IIKapDevice* pDevice = nullptr;
    if (IIKapDevice::CreateObject(&pDevice) != 0)
    {
        std::cerr << "创建设备对象失败" << std::endl;
        return -1;
    }

    // 2. 初始化库
    if (pDevice->InitLibrary() != 0)
    {
        std::cerr << "初始化库失败" << std::endl;
        delete pDevice;
        return -1;
    }

    // 3. 枚举设备
    unsigned int deviceCount = 0;
    if (pDevice->EnumerateDevices(deviceCount) != 0 || deviceCount == 0)
    {
        std::cerr << "未找到相机设备" << std::endl;
        pDevice->TerminateLibrary();
        delete pDevice;
        return -1;
    }

    std::cout << "找到 " << deviceCount << " 个相机" << std::endl;

    // 4. 获取设备信息
    IKapDeviceInfo devInfo;
    pDevice->GetDeviceInfo(0, devInfo);
    std::cout << "设备型号: " << devInfo.modelName << std::endl;
    std::cout << "序列号: " << devInfo.serialNumber << std::endl;

    // 5. 打开设备（索引 0，独占模式）
    if (pDevice->OpenDevice(0, 4) != 0)
    {
        std::cerr << "打开设备失败" << std::endl;
        pDevice->TerminateLibrary();
        delete pDevice;
        return -1;
    }

    // 6. 设置相机参数
    pDevice->SetExposureTime(10000.0);  // 曝光时间 10ms
    pDevice->SetGain(5.0);              // 增益 5dB

    // 7. 获取单张图像
    ImageData imageData;
    imageData.pData = nullptr;

    if (pDevice->GrabSingleFrame(imageData, 5000) == 0)
    {
        std::cout << "成功采集图像" << std::endl;
        std::cout << "  宽度: " << imageData.width << std::endl;
        std::cout << "  高度: " << imageData.height << std::endl;
        std::cout << "  大小: " << imageData.imageSize << " 字节" << std::endl;

        // 使用图像数据...
        // cv::Mat image(imageData.height, imageData.width, CV_8UC1, imageData.pData);
        // cv::imwrite("image.bmp", image);

        // 释放图像数据
        if (imageData.pData != nullptr)
        {
            delete[] imageData.pData;
        }
    }

    // 8. 清理资源
    pDevice->CloseDevice();
    pDevice->TerminateLibrary();
    delete pDevice;

    return 0;
}

示例 2: 连续采集图像

#include "IIKapDevice.h"
#include <atomic>

std::atomic<int> g_frameCount(0);

// 图像回调函数
void OnImageReceived(const ImageData& imageData, void* pUser)
{
    g_frameCount++;
    std::cout << "收到第 " << g_frameCount << " 帧图像, "
              << "大小: " << imageData.width << "x" << imageData.height
              << std::endl;

    // 处理图像数据...
}

int main()
{
    IIKapDevice* pDevice = nullptr;
    IIKapDevice::CreateObject(&pDevice);

    pDevice->InitLibrary();

    unsigned int deviceCount = 0;
    pDevice->EnumerateDevices(deviceCount);

    if (deviceCount > 0)
    {
        pDevice->OpenDevice(0);

        // 设置参数
        pDevice->SetExposureTime(10000.0);
        pDevice->SetGain(5.0);

        // 开始连续采集
        std::cout << "开始连续采集..." << std::endl;
        pDevice->StartGrabbing(OnImageReceived, nullptr);

        // 采集 10 秒
        std::this_thread::sleep_for(std::chrono::seconds(10));

        // 停止采集
        pDevice->StopGrabbing();
        std::cout << "停止采集，共采集 " << g_frameCount << " 帧" << std::endl;

        pDevice->CloseDevice();
    }

    pDevice->TerminateLibrary();
    delete pDevice;

    return 0;
}

编译

Windows (MSVC)

qmake IKapDevice.pro
nmake

Linux (ARM)

qmake IKapDevice.pro
make

链接到你的项目

在你的 .pro 文件中添加：

# 头文件路径
INCLUDEPATH += $$PWD/../../Device/IKapDevice/Inc

# 库链接
win32:CONFIG(debug, debug|release) {
    LIBS += -L$$PWD/../../Device/IKapDevice/debug -lIKapDevice
}
win32:CONFIG(release, debug|release) {
    LIBS += -L$$PWD/../../Device/IKapDevice/release -lIKapDevice
}
unix:!macx {
    LIBS += -L$$PWD/../../Device/IKapDevice -lIKapDevice
}

注意事项

1. 线程安全: 单个设备对象不支持多线程同时调用，建议在单一线程中操作
2. 资源释放: 使用 GrabSingleFrame 或回调函数获取的图像数据需要手动释放内存
3. 访问模式:
   • 4 - 独占模式（ITKDEV_VAL_ACCESS_MODE_EXCLUSIVE）- 推荐
   • 1 - 监控模式（ITKDEV_VAL_ACCESS_MODE_MONITOR）
   • 2 - 控制模式（ITKDEV_VAL_ACCESS_MODE_CONTROL）
   • 3 - 流模式（ITKDEV_VAL_ACCESS_MODE_STREAM）
4. 参数设置: 不同相机型号支持的参数可能不同，设置前建议查阅相机手册

与 VrEyeDevice 的区别

特性	VrEyeDevice	IKapDevice
SDK	VzNLSDK (3D激光相机)	IKapLibrary (通用工业相机)
主要功能	3D点云数据采集	2D图像采集
特殊功能	RGBD、摆动机构、激光检测	触发模式、ROI、通用相机参数
数据格式	点云 + 2D图像	2D图像
接口风格	类似（继承自相同的架构模式）	类似（继承自相同的架构模式）

版本历史

• v1.0.0 (2025-01-XX) - 初始版本
  • 支持基本的相机操作
  • 支持单张和连续采集
  • 支持常用参数设置

许可

遵循项目整体许可协议

联系方式

如有问题请联系项目维护者