GrabBag/Device/EpicEyeDevice/README.md

# EpicEyeDevice 封装库

## 简介

EpicEyeDevice 是对 EpicEye SDK 的 C++ 封装库，提供了简洁易用的 3D 相机点云采集接口。EpicEye 是一款基于结构光的 3D 视觉相机，可以同时获取 2D 彩色图像和 3D 点云数据。

## 目录结构

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

## 特性

- ✅ 支持相机搜索和设备信息查询
- ✅ 支持通过 IP 地址连接相机
- ✅ 支持触发式拍摄（trigger + fetch）
- ✅ **支持获取点云数据**（主要功能）
- ✅ 支持获取 2D 彩色图像
- ✅ 支持获取深度图
- ✅ 支持获取相机内参（相机矩阵和畸变参数）
- ✅ 支持获取/设置相机配置（JSON 格式）
- ✅ 便捷方法：一次性触发并获取点云/图像
- ✅ 线程安全设计
- ✅ 跨平台支持（Windows x64 / Linux ARM）

## 接口设计

### 核心接口

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

    // 搜索和连接
    virtual int SearchCameras(std::vector<EpicEyeDeviceInfo>& deviceList) = 0;
    virtual int Connect(const std::string& ipAddress) = 0;
    virtual int Disconnect() = 0;
    virtual bool IsConnected() = 0;

    // 获取设备信息
    virtual int GetDeviceInfo(EpicEyeDeviceInfo& deviceInfo) = 0;

    // 触发拍摄
    virtual int TriggerCapture(std::string& frameID, bool withPointCloud = true) = 0;

    // 获取数据（使用 frameID）
    virtual int GetPointCloud(const std::string& frameID, PointCloudData& pointCloud) = 0;
    virtual int GetImage(const std::string& frameID, ImageData2D& image) = 0;
    virtual int GetDepth(const std::string& frameID, DepthData& depth) = 0;

    // 便捷方法（一步到位）
    virtual int CapturePointCloud(PointCloudData& pointCloud, unsigned int timeout = 5000) = 0;
    virtual int CaptureImage(ImageData2D& image, unsigned int timeout = 5000) = 0;

    // 相机参数
    virtual int GetCameraIntrinsics(CameraIntrinsics& intrinsics) = 0;
    virtual int GetConfig(std::string& configJson) = 0;
    virtual int SetConfig(const std::string& configJson) = 0;
};
```

## 使用示例

### 示例 1: 搜索相机并获取点云

```cpp
#include "IEpicEyeDevice.h"
#include <iostream>

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

    // 2. 搜索相机
    std::vector<EpicEyeDeviceInfo> deviceList;
    if (pDevice->SearchCameras(deviceList) != 0 || deviceList.empty())
    {
        std::cerr << "未找到相机" << std::endl;
        delete pDevice;
        return -1;
    }

    std::cout << "找到 " << deviceList.size() << " 个相机" << std::endl;
    std::cout << "第一个相机 IP: " << deviceList[0].ipAddress << std::endl;

    // 3. 连接第一个相机
    if (pDevice->Connect(deviceList[0].ipAddress) != 0)
    {
        std::cerr << "连接相机失败" << std::endl;
        delete pDevice;
        return -1;
    }

    std::cout << "成功连接到相机" << std::endl;

    // 4. 获取设备信息
    EpicEyeDeviceInfo info;
    pDevice->GetDeviceInfo(info);
    std::cout << "相机型号: " << info.modelName << std::endl;
    std::cout << "序列号: " << info.serialNumber << std::endl;
    std::cout << "分辨率: " << info.width << " x " << info.height << std::endl;

    // 5. 获取点云数据（一步到位）
    PointCloudData pointCloud;
    pointCloud.pData = nullptr;

    if (pDevice->CapturePointCloud(pointCloud) == 0)
    {
        std::cout << "成功采集点云数据" << std::endl;
        std::cout << "  点数: " << pointCloud.pointCount << std::endl;
        std::cout << "  宽度: " << pointCloud.width << std::endl;
        std::cout << "  高度: " << pointCloud.height << std::endl;

        // 使用点云数据...
        // 点云格式: x, y, z 交替存储
        // 例如: pointCloud.pData[0], pointCloud.pData[1], pointCloud.pData[2] 是第一个点
        for (unsigned int i = 0; i < 10 && i < pointCloud.pointCount; ++i)
        {
            float x = pointCloud.pData[i * 3 + 0];
            float y = pointCloud.pData[i * 3 + 1];
            float z = pointCloud.pData[i * 3 + 2];
            std::cout << "  点 " << i << ": (" << x << ", " << y << ", " << z << ")" << std::endl;
        }

        // 保存为 PLY 文件（可选）
        // saveToPLY("pointcloud.ply", pointCloud);

        // 释放点云数据
        if (pointCloud.pData != nullptr)
        {
            delete[] pointCloud.pData;
        }
    }

    // 6. 清理资源
    pDevice->Disconnect();
    delete pDevice;

    return 0;
}
```

### 示例 2: 分步获取点云（Trigger + Fetch）

```cpp
#include "IEpicEyeDevice.h"

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

    // 连接相机
    pDevice->Connect("192.168.1.100");

    // 步骤1: 触发拍摄
    std::string frameID;
    if (pDevice->TriggerCapture(frameID, true) == 0)  // true = 包含点云
    {
        std::cout << "触发拍摄成功, frameID: " << frameID << std::endl;

        // 步骤2: 获取点云数据
        PointCloudData pointCloud;
        pointCloud.pData = nullptr;

        if (pDevice->GetPointCloud(frameID, pointCloud) == 0)
        {
            std::cout << "获取点云成功" << std::endl;

            // 处理点云数据...

            // 释放内存
            delete[] pointCloud.pData;
        }

        // 步骤3: 也可以获取对应的2D图像
        ImageData2D image;
        image.pData = nullptr;

        if (pDevice->GetImage(frameID, image) == 0)
        {
            std::cout << "获取图像成功" << std::endl;

            // 处理图像数据...

            // 释放内存
            delete[] image.pData;
        }
    }

    pDevice->Disconnect();
    delete pDevice;

    return 0;
}
```

### 示例 3: 获取相机内参

```cpp
#include "IEpicEyeDevice.h"

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

    pDevice->Connect("192.168.1.100");

    // 获取相机内参
    CameraIntrinsics intrinsics;
    if (pDevice->GetCameraIntrinsics(intrinsics) == 0)
    {
        std::cout << "相机内参矩阵 (3x3):" << std::endl;
        for (int i = 0; i < 3; ++i)
        {
            for (int j = 0; j < 3; ++j)
            {
                std::cout << intrinsics.cameraMatrix[i * 3 + j] << " ";
            }
            std::cout << std::endl;
        }

        std::cout << "畸变参数:" << std::endl;
        for (float dist : intrinsics.distortion)
        {
            std::cout << dist << " ";
        }
        std::cout << std::endl;
    }

    pDevice->Disconnect();
    delete pDevice;

    return 0;
}
```

## 点云数据格式

点云数据存储在 `PointCloudData` 结构中：

```cpp
struct PointCloudData
{
    float* pData;           // 点云数据指针
    unsigned int width;     // 点云宽度
    unsigned int height;    // 点云高度
    unsigned int pointCount;// 点数 (width * height)
    std::string frameID;    // 帧ID
};
```

- **数据排列**: x, y, z 交替存储，单位为米（m）
- **访问方式**:
  ```cpp
  for (unsigned int i = 0; i < pointCloud.pointCount; ++i)
  {
      float x = pointCloud.pData[i * 3 + 0];
      float y = pointCloud.pData[i * 3 + 1];
      float z = pointCloud.pData[i * 3 + 2];
  }
  ```
- **内存管理**: 调用者负责释放 `pData` 内存

## 编译

### Windows (MSVC)

```bash
qmake EpicEyeDevice.pro
nmake
```

### Linux (ARM)

```bash
qmake EpicEyeDevice.pro
make
```

## 链接到你的项目

在你的 .pro 文件中添加：

```qmake
# 头文件路径
INCLUDEPATH += $$PWD/../../Device/EpicEyeDevice/Inc

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

## 注意事项

1. **网络连接**: EpicEye 相机通过以太网连接，确保网络可达
2. **IP 地址**: 相机默认 IP 可能需要通过 Web UI 或工具配置
3. **内存释放**: 所有通过 `Get*` 方法获取的数据（点云、图像、深度图）需要手动释放内存
4. **线程安全**: 单个设备对象不支持多线程同时调用
5. **frameID**: 触发拍摄后返回的 frameID 用于获取对应的点云和图像数据
6. **点云单位**: 点云坐标单位为米（m）

## 与其他设备封装的对比

| 特性 | VrEyeDevice | IKapDevice | EpicEyeDevice |
|------|-------------|------------|---------------|
| SDK | VzNLSDK | IKapLibrary | EpicEye SDK |
| 设备类型 | 激光线扫描 3D 相机 | 通用工业 2D 相机 | 结构光 3D 相机 |
| 主要数据 | 3D 激光线点云 | 2D 图像 | 3D 点云 + 2D 图像 |
| 通信方式 | USB/以太网 | GigE/USB3/CameraLink/CXP | 以太网（HTTP REST API） |
| 特殊功能 | RGBD、摆动机构 | ROI、触发模式 | 深度图、相机内参 |

## 版本历史

- v1.0.0 (2025-01-XX) - 初始版本
  - 支持相机搜索和连接
  - 支持点云采集
  - 支持 2D 图像和深度图采集
  - 支持相机内参获取
  - 支持相机配置管理

## 许可

遵循项目整体许可协议

## 联系方式

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