ViewDesignEngine/include/vde/core/cam_5axis.h

#pragma once
/**
 * @file cam_5axis.h
 * @brief 5 轴联动 CAM 加工策略
 *
 * 在 3 轴 cam_strategies.h 的基础上扩展为 5 轴联动：
 *  - 刀位点 + 刀轴矢量 (CLData)
 *  - 侧刃加工 (swarf_machining)
 *  - 多轴粗加工 3+2 定位 (multi_axis_roughing)
 *  - 多轴精加工 + 碰撞检测 (multi_axis_finishing)
 *  - 机床运动学逆解 (inverse_kinematics)
 *  - 刀轴策略枚举 (ToolAxisStrategy)
 *
 * @ingroup core
 */
#include "vde/core/point.h"
#include "vde/core/aabb.h"
#include "vde/core/cam_toolpath.h"
#include "vde/core/cam_strategies.h"
#include "vde/mesh/halfedge_mesh.h"
#include <vector>
#include <string>
#include <optional>
#include <functional>

namespace vde::brep {
class BrepModel;
}  // namespace vde::brep

namespace vde::curves {
class NurbsSurface;
}  // namespace vde::curves

namespace vde::core {

using core::Point3D;
using core::Vector3D;
using core::AABB3D;

// ═══════════════════════════════════════════════════════════════════════════
//  5 轴刀位数据
// ═══════════════════════════════════════════════════════════════════════════

/// 单个刀位点 + 刀轴矢量 (Cutter Location Data)
struct CLData {
    Point3D position;     ///< 刀尖点/TCP 位置
    Vector3D tool_axis;   ///< 刀轴单位矢量（从刀尖指向刀柄）
    double feed_rate = 500.0;  ///< 进给速度 (mm/min)

    /// 便捷构造
    CLData() : position(Point3D::Zero()), tool_axis(Vector3D::UnitZ()) {}
    CLData(const Point3D& pos, const Vector3D& axis_, double feed = 500.0)
        : position(pos), tool_axis(axis_.normalized()), feed_rate(feed) {}
};

/// 5 轴刀路 — CLData 集合
struct AxisToolpath5 {
    std::string name;
    std::vector<CLData> points;   ///< 刀位点序列
    double safe_height = 50.0;    ///< 安全高度 (mm)

    /// 刀位点数量
    [[nodiscard]] size_t size() const { return points.size(); }

    /// 是否为空
    [[nodiscard]] bool empty() const { return points.empty(); }
};

// ═══════════════════════════════════════════════════════════════════════════
//  刀轴策略
// ═══════════════════════════════════════════════════════════════════════════

/// 刀轴控制策略
enum class ToolAxisStrategy {
    FixedAngle,       ///< 固定角度：刀轴保持与 Z 轴固定偏角
    LeadLag,          ///< 导前/滞后角：沿切削方向前倾或后倾
    Tilted,           ///< 侧倾：垂直于切削方向倾斜
    NormalToSurface   ///< 法向：刀轴始终沿曲面法向
};

// ═══════════════════════════════════════════════════════════════════════════
//  机床配置
// ═══════════════════════════════════════════════════════════════════════════

/// 机床结构类型
enum class MachineType {
    HeadHead,    ///< 双摆头：A/B 轴均在主轴侧
    TableTable,  ///< 双转台：A/C 轴均在工作台侧
    HeadTable    ///< 摆头+转台：主轴侧一轴 + 工作台侧一轴
};

/// 旋转轴配置
enum class MachineAxisConfig {
    AC,   ///< A 轴（绕 X 旋转）+ C 轴（绕 Z 旋转）
    BC,   ///< B 轴（绕 Y 旋转）+ C 轴（绕 Z 旋转）
    AB    ///< A 轴（绕 X 旋转）+ B 轴（绕 Y 旋转）
};

/// 机床运动学配置
struct MachineConfig {
    MachineType machine_type = MachineType::TableTable;
    MachineAxisConfig axis_config = MachineAxisConfig::AC;

    /// 旋转轴行程限制（度）
    double a_min = -120.0;
    double a_max = 120.0;
    double b_min = -120.0;
    double b_max = 120.0;
    double c_min = -9999.0;  // C 轴通常无限制（360°连续）
    double c_max = 9999.0;

    /// 主轴端到旋转中心的偏移 (mm)
    Vector3D pivot_offset = Vector3D::Zero();

    /// 刀具长度 (mm)
    double tool_length = 100.0;

    /// 检查旋转角是否在行程范围内
    [[nodiscard]] bool in_range(double a, double b, double c) const;

    /// 解析刀轴矢量为旋转角（根据 axis_config）
    /// @return (a_deg, b_deg, c_deg)，失败返回 std::nullopt
    [[nodiscard]] std::optional<std::tuple<double, double, double>>
    axis_to_angles(const Vector3D& tool_axis) const;
};

// ═══════════════════════════════════════════════════════════════════════════
//  5 轴加工参数
// ═══════════════════════════════════════════════════════════════════════════

/// 侧刃加工参数
struct SwarfParams {
    double step_down = 1.0;         ///< 每层切深 (mm)
    double step_over = 0.5;         ///< 横向步距 (mm)
    double feed_rate = 600.0;       ///< 进给速度 (mm/min)
    double safe_height = 50.0;      ///< 安全高度 (mm)
    double tilt_angle = 0.0;        ///< 刀轴相对于曲面法线的偏转角 (度)
};

/// 多轴粗加工参数
struct MultiAxisRoughingParams {
    double step_down = 2.0;         ///< 每层切深 (mm)
    double step_over = 3.0;         ///< 横向步距 (mm)
    double stock_to_leave = 1.0;    ///< 留量 (mm)
    double feed_rate = 800.0;       ///< 进给速度 (mm/min)
    double safe_height = 50.0;      ///< 安全高度 (mm)
    /// 3+2 定位角度 — 固定刀轴方向（相对于 Z 轴的倾斜角, 度）
    double tilt_angle = 15.0;
    double lead_angle = 0.0;        ///< 导前角 (度)
};

/// 多轴精加工参数
struct MultiAxisFinishingParams {
    double step_over = 0.3;         ///< 行距 (mm)
    double feed_rate = 500.0;       ///< 进给速度 (mm/min)
    double safe_height = 50.0;      ///< 安全高度 (mm)
    ToolAxisStrategy axis_strategy = ToolAxisStrategy::NormalToSurface;
    double max_tilt = 30.0;         ///< 最大倾斜角 (度)
    double lead_angle = 3.0;        ///< 导前角 (度)
    /// 碰撞检测参数
    bool collision_check = true;    ///< 是否启用碰撞检测
    double shank_clearance = 2.0;   ///< 刀柄安全间隙 (mm)
    double holder_clearance = 5.0;  ///< 刀杆安全间隙 (mm)
};

// ═══════════════════════════════════════════════════════════════════════════
//  5 轴加工策略函数
// ═══════════════════════════════════════════════════════════════════════════

/// 侧刃加工 (Swarf Machining)
///
/// 使用刀具侧刃贴合曲面进行切削，刀轴沿曲面法线偏转。
/// 适用于直纹面侧壁加工。
///
/// @param surface 目标 NURBS 曲面
/// @param tool    刀具参数
/// @param params  侧刃加工参数
/// @return 5 轴刀路
///
/// @ingroup core
[[nodiscard]] AxisToolpath5 swarf_machining(
    const curves::NurbsSurface& surface,
    const Tool& tool,
    const SwarfParams& params);

/// 多轴粗加工 (3+2 定位加工)
///
/// 使用 3+2 定位方式对实体进行分层粗加工。
/// 自动优化刀轴方向以最大化材料去除率，同时避免干涉。
///
/// @param body    B-Rep 实体
/// @param tool    刀具参数
/// @param params  多轴粗加工参数
/// @param config  机床运动学配置（用于刀轴方向可行性检查）
/// @return 5 轴刀路
///
/// @ingroup core
[[nodiscard]] AxisToolpath5 multi_axis_roughing(
    const brep::BrepModel& body,
    const Tool& tool,
    const MultiAxisRoughingParams& params,
    const MachineConfig& config = MachineConfig{});

/// 多轴精加工
///
/// 对曲面进行 5 轴联动精加工。刀轴平滑变化，
/// 包含刀柄和刀杆的碰撞检测。
///
/// @param surface 目标 NURBS 曲面
/// @param body    完整 B-Rep 模型（碰撞检测用）
/// @param tool    刀具参数
/// @param params  多轴精加工参数
/// @param config  机床运动学配置
/// @return 5 轴刀路
///
/// @ingroup core
[[nodiscard]] AxisToolpath5 multi_axis_finishing(
    const curves::NurbsSurface& surface,
    const brep::BrepModel& body,
    const Tool& tool,
    const MultiAxisFinishingParams& params,
    const MachineConfig& config = MachineConfig{});

/// 机床运动学逆解
///
/// 将工件坐标系下的刀路 (CLData) 转换为机床各轴坐标。
/// 根据机床配置 (AC/BC/AB + 双转台/摆头) 计算 X/Y/Z/A/B/C。
///
/// @param toolpath 工件坐标系下的 5 轴刀路
/// @param config   机床运动学配置
/// @return 机床坐标刀路（points 中 position 存 X/Y/Z，tool_axis 存 A/B/C 度）
///
/// @ingroup core
[[nodiscard]] AxisToolpath5 inverse_kinematics(
    const AxisToolpath5& toolpath,
    const MachineConfig& config);

/// 刀轴碰撞检测
///
/// 检查刀柄和刀杆是否与工件发生碰撞。
///
/// @param position  刀尖位置
/// @param tool_axis 刀轴方向
/// @param body      B-Rep 工件
/// @param tool      刀具参数
/// @param shank_clearance 刀柄安全间隙
/// @param holder_clearance 刀杆安全间隙
/// @return true 如果发生碰撞
///
/// @ingroup core
[[nodiscard]] bool check_collision(
    const Point3D& position,
    const Vector3D& tool_axis,
    const brep::BrepModel& body,
    const Tool& tool,
    double shank_clearance = 2.0,
    double holder_clearance = 5.0);

/// 刀轴方向优化
///
/// 给定候选刀轴方向列表，选择最优方向：
///  - 优先选择更接近 Z 轴（减小旋转轴行程）
///  - 避免超出机床行程的配置
///  - 考虑切削条件（避免刀尖切削）
///
/// @param candidates 候选刀轴方向
/// @param config     机床配置
/// @return 最优刀轴方向（归一化），若无可行方向返回 Z 轴
///
/// @ingroup core
[[nodiscard]] Vector3D optimize_tool_axis(
    const std::vector<Vector3D>& candidates,
    const MachineConfig& config);

}  // namespace vde::core