ViewDesignEngine/include/vde/brep/gdt.h

#pragma once
/**
 * @file gdt.h
 * @brief GD&T 几何公差标注与验证
 *
 * 支持 ASME Y14.5 标准几何公差：形状公差、方向公差、位置公差、跳动公差。
 * 提供公差标注数据结构和公差带计算。
 *
 * @ingroup brep
 */

#include "vde/core/point.h"
#include "vde/brep/brep.h"
#include <vector>
#include <string>
#include <optional>

namespace vde::brep {

// ═══════════════════════════════════════════════════════════
//  Tolerance Types (ASME Y14.5)
// ═══════════════════════════════════════════════════════════

/// GD&T 公差类型
enum class GDTType {
    // Form tolerances (形状公差)
    Flatness,        ///< 平面度
    Straightness,    ///< 直线度
    Circularity,     ///< 圆度
    Cylindricity,    ///< 圆柱度

    // Orientation tolerances (方向公差)
    Parallelism,     ///< 平行度
    Perpendicularity,///< 垂直度
    Angularity,      ///< 倾斜度

    // Location tolerances (位置公差)
    Position,        ///< 位置度
    Concentricity,   ///< 同心度
    Symmetry,        ///< 对称度

    // Profile tolerances (轮廓公差)
    ProfileOfLine,   ///< 线轮廓度
    ProfileOfSurface,///< 面轮廓度

    // Runout tolerances (跳动公差)
    CircularRunout,  ///< 圆跳动
    TotalRunout,     ///< 全跳动
};

// ═══════════════════════════════════════════════════════════
//  Datum Reference
// ═══════════════════════════════════════════════════════════

/// 基准特征引用
struct DatumReference {
    std::string label;           ///< 基准标签（A, B, C...）
    int face_id = -1;            ///< 关联的 B-Rep 面 ID
    bool is_primary = false;     ///< 是否主基准
};

// ═══════════════════════════════════════════════════════════
//  GD&T Feature Control Frame
// ═══════════════════════════════════════════════════════════

/// 特征控制框（一个完整的 GD&T 标注）
struct GDTFeature {
    GDTType type = GDTType::Flatness;      ///< 公差类型
    double tolerance_value = 0.1;           ///< 公差值
    std::vector<DatumReference> datums;     ///< 基准引用
    int target_face_id = -1;                ///< 目标面 ID

    /// 附加修饰符
    bool mmc = false;          ///< 最大实体条件 MⓂ
    bool lmc = false;          ///< 最小实体条件 LⓁ
    bool projected = false;    ///< 投影公差带 PⓅ
    double projected_height = 0.0; ///< 投影高度

    /// 公差带形状（默认平行平面）
    enum class ZoneShape { ParallelPlanes, Cylindrical, Spherical, Uniform };
    ZoneShape zone_shape = ZoneShape::ParallelPlanes;

    /// 获取公差符号（用于显示）
    [[nodiscard]] std::string symbol() const;

    /// 获取完整标注字符串
    [[nodiscard]] std::string to_string() const;
};

// ═══════════════════════════════════════════════════════════
//  GD&T Validation Result
// ═══════════════════════════════════════════════════════════

/// GD&T 验证结果
struct GDTValidationResult {
    bool pass = true;                          ///< 是否合格
    double actual_deviation = 0.0;             ///< 实际偏差
    double tolerance = 0.0;                    ///< 公差要求
    std::string description;                   ///< 描述
    std::vector<std::string> warnings;         ///< 警告信息
};

// ═══════════════════════════════════════════════════════════
//  GD&T Annotations (for drawing views)
// ═══════════════════════════════════════════════════════════

/// 单个 GD&T 标注（含 2D 位置信息，用于工程图）
struct GDTAnnotation {
    GDTFeature feature;                         ///< 特征控制框
    core::Point3D leader_point;                 ///< 引线箭头位置
    core::Point3D frame_position;               ///< 控制框放置位置
    std::string view_name;                      ///< 所属视图名称

    /// 生成 DXF 格式的控制框文本
    [[nodiscard]] std::string to_dxf_text() const;
};

// ═══════════════════════════════════════════════════════════
//  API
// ═══════════════════════════════════════════════════════════

/**
 * @brief 验证 B-Rep 模型的 GD&T 要求
 *
 * @param body B-Rep 模型
 * @param feature GD&T 特征要求
 * @return 验证结果
 */
[[nodiscard]] GDTValidationResult validate_gdt(
    const BrepModel& body, const GDTFeature& feature);

/**
 * @brief 计算面的平面度
 *
 * 测量面到最佳拟合平面（最小二乘）的最大偏差。
 *
 * @param body B-Rep 模型
 * @param face_id 面 ID
 * @return 平面度偏差值
 */
[[nodiscard]] double compute_flatness(const BrepModel& body, int face_id);

/**
 * @brief 计算两面的平行度
 *
 * 测量实际面相对于基准面的平行偏差。
 *
 * @param body B-Rep 模型
 * @param face_id 被测面 ID
 * @param datum_face_id 基准面 ID
 * @return 平行度偏差值
 */
[[nodiscard]] double compute_parallelism(
    const BrepModel& body, int face_id, int datum_face_id);

/**
 * @brief 计算两面的垂直度
 *
 * @param body B-Rep 模型
 * @param face_id 被测面
 * @param datum_face_id 基准面
 * @return 垂直度偏差值
 */
[[nodiscard]] double compute_perpendicularity(
    const BrepModel& body, int face_id, int datum_face_id);

/**
 * @brief 计算同心度
 *
 * 测量两圆柱/圆特征轴线的偏移。
 *
 * @param body B-Rep 模型
 * @param face_id 被测特征面
 * @param datum_face_id 基准特征面
 * @return 同心度偏差值
 */
[[nodiscard]] double compute_concentricity(
    const BrepModel& body, int face_id, int datum_face_id);

/**
 * @brief 计算位置度
 *
 * 测量特征实际位置与理论位置的偏差。
 *
 * @param body B-Rep 模型
 * @param face_id 被测面
 * @param theoretical_position 理论位置
 * @return 位置度偏差值
 */
[[nodiscard]] double compute_position(
    const BrepModel& body, int face_id,
    const core::Point3D& theoretical_position);

/**
 * @brief 将 GD&T 标注转换为 DXF 文本
 *
 * @param annotations GD&T 标注列表
 * @return DXF 格式文本
 */
[[nodiscard]] std::string export_gdt_annotations_dxf(
    const std::vector<GDTAnnotation>& annotations);

} // namespace vde::brep