GrabBag/Module/ChessboardDetector/Inc/IChessboardDetector.h

#ifndef ICHESSBOARDDETECTOR_H
#define ICHESSBOARDDETECTOR_H

#include <vector>

/**
 * @brief 2D 点结构
 */
struct Point2D
{
    double x;
    double y;

    Point2D() : x(0.0), y(0.0) {}
    Point2D(double _x, double _y) : x(_x), y(_y) {}
};

/**
 * @brief 3D 点结构
 */
struct Point3D
{
    double x;
    double y;
    double z;

    Point3D() : x(0.0), y(0.0), z(0.0) {}
    Point3D(double _x, double _y, double _z) : x(_x), y(_y), z(_z) {}
};

/**
 * @brief 标定板检测结果
 */
struct ChessboardDetectResult
{
    bool detected;                          // 是否检测到标定板
    std::vector<Point2D> corners;           // 角点坐标（图像坐标系）
    int patternWidth;                       // 标定板内角点宽度
    int patternHeight;                      // 标定板内角点高度

    // 位姿信息（如果提供了相机内参）
    bool hasPose;                           // 是否计算了位姿
    Point3D center;                         // 标定板中心位置（相机坐标系，单位：mm）
    Point3D normal;                         // 标定板法向量（单位向量）
    double rvec[3];                         // 旋转向量
    double tvec[3];                         // 平移向量
    double rotationMatrix[9];               // 旋转矩阵 (3x3)
    double eulerAngles[3];                  // 欧拉角 (roll, pitch, yaw) 单位：度

    ChessboardDetectResult()
        : detected(false)
        , patternWidth(0)
        , patternHeight(0)
        , hasPose(false)
    {
        for (int i = 0; i < 3; i++) {
            rvec[i] = 0.0;
            tvec[i] = 0.0;
            eulerAngles[i] = 0.0;
        }
        for (int i = 0; i < 9; i++) {
            rotationMatrix[i] = 0.0;
        }
    }
};

/**
 * @brief 相机内参
 */
struct CameraIntrinsics
{
    double fx;          // 焦距 x
    double fy;          // 焦距 y
    double cx;          // 主点 x
    double cy;          // 主点 y
    double k1, k2, p1, p2, k3;  // 畸变系数

    CameraIntrinsics()
        : fx(1000.0), fy(1000.0)
        , cx(640.0), cy(480.0)
        , k1(0.0), k2(0.0), p1(0.0), p2(0.0), k3(0.0)
    {}
};

/**
 * @brief 标定板检测接口
 */
class IChessboardDetector
{
public:
    virtual ~IChessboardDetector() = default;

    /**
     * @brief 检测标定板角点
     * @param imageData 图像数据（灰度图或彩色图）
     * @param width 图像宽度
     * @param height 图像高度
     * @param channels 图像通道数 (1=灰度, 3=BGR)
     * @param patternWidth 标定板内角点宽度
     * @param patternHeight 标定板内角点高度
     * @param result 输出检测结果
     * @return 成功返回0，失败返回错误码
     */
    virtual int DetectChessboard(
        const unsigned char* imageData,
        int width,
        int height,
        int channels,
        int patternWidth,
        int patternHeight,
        ChessboardDetectResult& result) = 0;

    /**
     * @brief 检测标定板并计算位姿
     * @param imageData 图像数据
     * @param width 图像宽度
     * @param height 图像高度
     * @param channels 图像通道数
     * @param patternWidth 标定板内角点宽度
     * @param patternHeight 标定板内角点高度
     * @param squareSize 标定板格子大小（单位：mm）
     * @param intrinsics 相机内参
     * @param result 输出检测结果（包含位姿）
     * @return 成功返回0，失败返回错误码
     */
    virtual int DetectChessboardWithPose(
        const unsigned char* imageData,
        int width,
        int height,
        int channels,
        int patternWidth,
        int patternHeight,
        double squareSize,
        const CameraIntrinsics& intrinsics,
        ChessboardDetectResult& result) = 0;

    /**
     * @brief 设置检测参数
     * @param adaptiveThresh 是否使用自适应阈值
     * @param normalizeImage 是否归一化图像
     * @param filterQuads 是否过滤四边形
     * @return 成功返回0
     */
    virtual int SetDetectionFlags(
        bool adaptiveThresh,
        bool normalizeImage,
        bool filterQuads) = 0;
};

/**
 * @brief 创建标定板检测实例
 * @return 标定板检测实例指针
 */
IChessboardDetector* CreateChessboardDetectorInstance();

/**
 * @brief 销毁标定板检测实例
 * @param instance 实例指针
 */
void DestroyChessboardDetectorInstance(IChessboardDetector* instance);

#endif // ICHESSBOARDDETECTOR_H