GrabBag/Module/BinocularMarkReceiver/Inc/IBinocularMarkReceiver.h

#ifndef IBINOCULARMARKRECEIVER_H
#define IBINOCULARMARKRECEIVER_H

#include <functional>
#include <vector>
#include <string>
#include <cstdint>

// 导出宏定义
#ifdef _WIN32
#  ifdef BINOCULARMARKRECEIVER_LIBRARY
#    define BINOCULARMARKRECEIVER_EXPORT __declspec(dllexport)
#  else
#    define BINOCULARMARKRECEIVER_EXPORT __declspec(dllimport)
#  endif
#else
#  define BINOCULARMARKRECEIVER_EXPORT __attribute__((visibility("default")))
#endif

/**
 * @brief 通用 Mark 3D 数据结构
 * 不依赖具体算法库的 Mark 数据定义
 */
struct VrMark3D
{
    int markID;         // Mark ID
    double x;           // X 坐标
    double y;           // Y 坐标
    double z;           // Z 坐标

    VrMark3D() : markID(-1), x(0.0), y(0.0), z(0.0) {}
    VrMark3D(int id, double _x, double _y, double _z)
        : markID(id), x(_x), y(_y), z(_z) {}
};

/**
 * @brief 事件类型枚举
 */
enum class ReceiverEventType
{
    UNKNOWN,            // 未知事件
    CONNECTED,          // 已连接
    DISCONNECTED,       // 已断开
    CONNECTION_ERROR,   // 连接错误
    HEARTBEAT_TIMEOUT   // 心跳超时
};

/**
 * @brief 相机选择枚举
 */
enum class SVrCameraEnum
{
    LEFT,               // 左相机
    RIGHT,              // 右相机
    BOTH                // 双相机
};

/**
 * @brief 双目Mark数据接收器接口
 * 用于从BinocularMarkApp接收3D Mark检测结果
 */
class BINOCULARMARKRECEIVER_EXPORT IBinocularMarkReceiver
{
public:
    virtual ~IBinocularMarkReceiver() = default;

    /**
     * @brief 单次检测结果结构
     */
    struct SingleDetectionResult {
        std::vector<VrMark3D> marks;        // 检测到的3D标记列表
        std::string leftImageBase64;         // 左相机图像（Base64编码）
        std::string rightImageBase64;        // 右相机图像（Base64编码）
        int64_t timestamp;                   // 时间戳
        int errorCode;                       // 错误码（0表示成功）
    };

    /**
     * @brief 图像数据结构
     */
    struct ImageData {
        std::string leftImageBase64;         // 左相机图像（Base64编码）
        std::string rightImageBase64;        // 右相机图像（Base64编码）
        int64_t timestamp;                   // 时间戳
    };


    /**
     * @brief 相机信息结构
     */
    struct CameraInfo {
        std::string serialNumber;    // 相机序列号
        std::string modelName;        // 相机型号
        std::string displayName;      // 显示名称
        double exposureTime;          // 当前曝光时间
        double gain;                  // 当前增益
    };

    /**
     * @brief Mark结果回调函数类型（持续工作模式）
     * @param marks 检测到的3D标记列表
     * @param timestamp 时间戳
     * @param errorCode 错误码（0表示成功）
     */
    using MarkResultCallback = std::function<void(const std::vector<VrMark3D>& marks, int64_t timestamp, int errorCode)>;

    /**
     * @brief 图像回调函数类型（持续图像流模式）
     * @param leftImageBase64 左相机图像（Base64编码）
     * @param rightImageBase64 右相机图像（Base64编码）
     * @param timestamp 时间戳
     */
    using ImageCallback = std::function<void(const std::string& leftImageBase64, const std::string& rightImageBase64, int64_t timestamp)>;

    /**
     * @brief 事件回调函数类型
     * @param eventType 事件类型
     * @param errorMsg 错误消息（可选）
     */
    using EventCallback = std::function<void(ReceiverEventType eventType, const std::string& errorMsg)>;

    /**
     * @brief 启动TCP客户端并连接到服务器
     * @param serverIp 服务器IP地址
     * @param serverPort 服务器端口
     * @return 0-成功，其他-失败
     */
    virtual int Connect(const std::string& serverIp, uint16_t serverPort) = 0;

    /**
     * @brief 断开连接
     * @return 0-成功，其他-失败
     */
    virtual int Disconnect() = 0;

    /**
     * @brief 检查是否已连接
     * @return true-已连接，false-未连接
     */
    virtual bool IsConnected() const = 0;

    /**
     * @brief 获取相机信息（同步请求）
     * @param target 相机目标（左/右）
     * @param timeoutMs 超时时间（毫秒），默认3000ms
     * @return 相机信息结构体
     */
    virtual CameraInfo GetCameraInfo(SVrCameraEnum target, int timeoutMs = 3000) = 0;

    /**
     * @brief 获取标定矩阵（同步请求）
     * @param timeoutMs 超时时间（毫秒），默认3000ms
     * @return 标定矩阵XML字符串
     */
    virtual std::string GetCalibrationMatrix(int timeoutMs = 3000) = 0;

    /**
     * @brief 设置标定矩阵（发送标定文件内容到服务端）
     * @param calibrationXml 标定文件XML内容
     * @return 0-成功，其他-失败
     */
    virtual int SetCalibrationMatrix(const std::string& calibrationXml) = 0;

    /**
     * @brief 设置曝光时间
     * @param target 相机目标（左/右/双）
     * @param exposureTime 曝光时间
     * @return 0-成功，其他-失败
     */
    virtual int SetExposureTime(SVrCameraEnum target, double exposureTime) = 0;

    /**
     * @brief 设置增益
     * @param target 相机目标（左/右/双）
     * @param gain 增益
     * @return 0-成功，其他-失败
     */
    virtual int SetGain(SVrCameraEnum target, double gain) = 0;

    /**
     * @brief 请求单次检测（同步返回图像和Mark结果）
     * @param timeoutMs 超时时间（毫秒），默认5000ms
     * @return 检测结果结构体
     */
    virtual SingleDetectionResult RequestSingleDetection(int timeoutMs = 5000) = 0;

    /**
     * @brief 请求获取单次图像（同步返回）
     * @param timeoutMs 超时时间（毫秒），默认5000ms
     * @return 图像数据结构体
     */
    virtual ImageData RequestSingleImage(int timeoutMs = 5000) = 0;

    /**
     * @brief 开始持续工作（持续检测并回调结果）
     * @return 0-成功，其他-失败
     */
    virtual int StartWork() = 0;

    /**
     * @brief 停止持续工作
     * @return 0-成功，其他-失败
     */
    virtual int StopWork() = 0;

    /**
     * @brief 开始持续图像流（持续接收图像并回调）
     * @return 0-成功，其他-失败
     */
    virtual int StartCapture() = 0;

    /**
     * @brief 停止持续图像流
     * @return 0-成功，其他-失败
     */
    virtual int StopCapture() = 0;

    /**
     * @brief 设置Mark结果回调（持续工作模式使用）
     * @param callback 回调函数
     */
    virtual void SetMarkResultCallback(MarkResultCallback callback) = 0;

    /**
     * @brief 设置图像回调（持续图像流模式使用）
     * @param callback 回调函数
     */
    virtual void SetImageCallback(ImageCallback callback) = 0;

    /**
     * @brief 设置事件回调
     * @param callback 回调函数
     */
    virtual void SetEventCallback(EventCallback callback) = 0;

    /**
     * @brief 创建BinocularMarkReceiver实例
     * @param ppReceiver 接收器实例指针
     * @return 0-成功，其他-失败
     */
    static int CreateInstance(IBinocularMarkReceiver** ppReceiver);
};

#endif // IBINOCULARMARKRECEIVER_H