GrabBag/AppAlgo/holeDetection/include/HoleDetectionParams.h

#ifndef HOLE_DETECTION_PARAMS_H
#define HOLE_DETECTION_PARAMS_H

#include <cmath>
#include "../include/VZNL_Types.h"  // 使用 VZNL_Types.h 中的类型

/**
 * @brief 检测到的孔洞排序模式
 */
enum ESortMode {
    keSortMode_None = 0,        // 不排序
    keSortMode_ByRadius = 1,    // 按半径排序（最大的在前）
    keSortMode_ByDepth = 2,     // 按深度排序（最深的在前）
    keSortMode_ByQuality = 3    // 按质量分数排序（最高的在前）
};

/**
 * @brief 孔洞检测算法的检测参数
 */
struct SHoleDetectionParams {
    // 凹坑检测参数
    int neighborCount;              // 线连接的相邻点数（默认值：3）
    float angleThresholdPos;        // 正角度阈值，单位：度（默认值：10.0）
    float angleThresholdNeg;        // 负角度阈值，单位：度（默认值：-10.0）
    float minPitDepth;              // 最小凹坑深度，单位：mm（默认值：1.0）

    // 椭圆拟合参数
    float minRadius;                // 最小孔洞半径，单位：mm（默认值：2.0）
    float maxRadius;                // 最大孔洞半径，单位：mm（默认值：50.0）

    // 平面拟合参数
    int expansionSize1;             // 第一环扩展大小，单位：mm（默认值：5）
    int expansionSize2;             // 第二环扩展大小，单位：mm（默认值：10）

    // V型检测参数
    int minVTransitionPoints;       // V型端点之间的最小有效过渡点数（默认值：1）

    // 构造函数，设置默认值
    SHoleDetectionParams()
        : neighborCount(3)
        , angleThresholdPos(10.0f)
        , angleThresholdNeg(-10.0f)
        , minPitDepth(1.0f)
        , minRadius(2.0f)
        , maxRadius(50.0f)
        , expansionSize1(5)
        , expansionSize2(10)
        , minVTransitionPoints(1)
    {}
};

/**
 * @brief 孔洞过滤参数
 */
struct SHoleFilterParams {

    // 质量阈值过滤
    float maxEccentricity;          // 最大离心率（默认值：0.99995，标准公式 e=sqrt(1-(b/a)^2)）

    // 形状过滤（拟合前）
    float minAngularCoverage;       // 最小角度覆盖范围，单位：度（默认值：10.0）
                                    // 用于过滤非闭合边界。设置为 0 可禁用。
    float maxRadiusFitRatio;        // 最大半径拟合比率 radiusVariance/radius（默认值：1.0）
                                    // 衡量点与圆的拟合程度。设置为 1.0 可禁用。
    float minQualityScore;          // 最小整体质量分数（默认值：0.0）
                                    // 形状指标的加权组合。设置为 0 可禁用。

    // 平面性过滤（投影前）
    float maxPlaneResidual;         // 最大点到平面残差，单位：mm（默认值：10.0）
                                    // 拒绝非平面簇（例如悬崖、台阶边缘）。
    float maxAngularGap;            // 最大角度间隙，单位：度（默认值：90.0）
                                    // 拒绝 L 型或非闭合边界。
    float minInlierRatio;           // 椭圆拟合的最小内点比率（默认值：0.0）
                                    // 在拟合椭圆容差范围内的点的比例。

    // 构造函数，设置默认值
    SHoleFilterParams()
        : maxEccentricity(0.99995f)
        , minAngularCoverage(10.f)
        , maxRadiusFitRatio(1.f)
        , minQualityScore(0.f)
        , maxPlaneResidual(10.0f)
        , maxAngularGap(90.0f)
        , minInlierRatio(0.f)
    {}
};

/**
 * @brief 单个孔洞检测结果
 *
 * 注意：SVzNL3DPointF 和 SVzNL2DPointF 在 VZNL_Types.h 中定义
 */
struct SHoleResult {
    SVzNL3DPointF center;           // 孔洞中心点 (x, y, z)
    SVzNL3DPointF normal;           // 平面法向量（单位长度）
    float radius;                   // 孔洞半径，单位：mm
    float depth;                    // 凹坑深度，单位：mm
    float eccentricity;             // 离心率（0 = 完美圆形）
    float radiusVariance;           // 半径方差，单位：mm
    float angularSpan;              // 角度覆盖范围，单位：度
    float qualityScore;             // 质量分数（0-1，越高越好）

    SHoleResult()
        : center()
        , normal()
        , radius(0.0f)
        , depth(0.0f)
        , eccentricity(0.0f)
        , radiusVariance(0.0f)
        , angularSpan(0.0f)
        , qualityScore(0.0f)
    {}
};

/**
 * @brief 多孔洞检测结果
 *
 * @note 内存管理：holes 数组不会自动释放。
 *       调用者必须调用 FreeMultiHoleResult() 或手动 delete[] holes。
 */
struct SMultiHoleResult {
    int holeCount;                  // 检测到的孔洞数量
    SHoleResult* holes;             // 孔洞结果数组（调用者必须释放）
    int totalCandidates;            // 过滤前的候选孔洞总数
    int filteredCount;              // 被过滤掉的孔洞数量

    SMultiHoleResult()
        : holeCount(0)
        , holes(nullptr)
        , totalCandidates(0)
        , filteredCount(0)
    {}
};

/**
 * @brief 释放 DetectMultipleHoles 分配的内存
 *
 * @param [in,out] result 要释放的结果结构
 */
inline void FreeMultiHoleResult(SMultiHoleResult* result) {
    if (result != nullptr && result->holes != nullptr) {
        delete[] result->holes;
        result->holes = nullptr;
        result->holeCount = 0;
    }
}

/**
 * @brief 线段端点对结构
 *
 * 表示在线扫描中检测到的线段，包含起点和终点。
 * 注意：尽管名称为"PeakValley"，但此结构存储的是线段端点，
 * 不一定是峰值/谷值点。保留此命名是为了兼容性。
 */
struct SSegmentPair {
    SVzNLPointXYZ startPoint;       // 线段起点
    SVzNLPointXYZ endPoint;         // 线段终点
    int startRow;                   // 起点行索引
    int startCol;                   // 起点列索引
    int endRow;                     // 终点行索引
    int endCol;                     // 终点列索引
    float depth;                    // 起点和终点之间的深度差

    SSegmentPair()
        : startPoint()
        , endPoint()
        , startRow(0)
        , startCol(0)
        , endRow(0)
        , endCol(0)
        , depth(0.0f)
    {}
};

#endif // HOLE_DETECTION_PARAMS_H