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）

## 接口设计

### 核心接口

```cpp
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: 获取单张图像

```cpp
#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: 连续采集图像

```cpp
#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)

```bash
qmake IKapDevice.pro
nmake
```

### Linux (ARM)

```bash
qmake IKapDevice.pro
make
```

## 链接到你的项目

在你的 .pro 文件中添加：

```qmake
# 头文件路径
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) - 初始版本
  - 支持基本的相机操作
  - 支持单张和连续采集
  - 支持常用参数设置

## 许可

遵循项目整体许可协议

## 联系方式

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