ViewDesignEngine/include/vde/brep/kinematic_chain.h

#pragma once
/**
 * @file kinematic_chain.h
 * @brief 运动链求解器
 *
 * 经典机构学求解器：四连杆、齿轮传动、凸轮机构。
 * 扩展 v4.0 运动仿真模块的机构学能力。
 *
 * @ingroup brep
 */

#include "vde/core/point.h"
#include <vector>
#include <cmath>
#include <limits>

namespace vde::brep {

// ═══════════════════════════════════════════════════════════
//  四连杆机构 (Four-Bar Linkage)
// ═══════════════════════════════════════════════════════════

/// 四杆机构类型（按 Grashof 条件分类）
enum class FourBarType {
    CrankRocker,     ///< 曲柄摇杆：最短杆为曲柄，旋转完整 360°
    DoubleCrank,     ///< 双曲柄：最短杆为机架
    DoubleRocker,    ///< 双摇杆：最短杆为连杆
    ChangePoint,     ///< 变点机构：Grashof 等号成立
    NonGrashof,      ///< 非 Grashof：无杆可完整旋转
};

/// 四杆机构定义
struct FourBarLinkage {
    double ground = 1.0;    ///< 机架长度（固定杆）
    double crank = 1.0;     ///< 曲柄（输入杆）长度
    double coupler = 1.0;   ///< 连杆长度
    double rocker = 1.0;    ///< 摇杆（输出杆）长度

    /// 按 Grashof 条件分类
    [[nodiscard]] FourBarType classify() const;

    /// 检查是否为 Grashof 机构（至少一杆可完整旋转）
    [[nodiscard]] bool is_grashof() const;
};

/// 四杆机构求解结果（单输入角度）
struct FourBarSolution {
    double input_angle = 0.0;       ///< 输入角（弧度）
    double output_angle = 0.0;      ///< 输出角（弧度）
    double coupler_angle = 0.0;     ///< 连杆角（弧度）
    double transmission_angle = 0.0; ///< 传动角（弧度）
    bool valid = false;             ///< 解是否有效
    bool dead_point = false;        ///< 是否处于死点
};

/**
 * @brief 四杆机构位置求解
 *
 * 给定输入角度，计算输出角度和传动角。
 * 使用 Freudenstein 方程求解。
 *
 * @param linkage 四杆机构参数
 * @param input_angle 输入角（弧度），曲柄与机架的夹角
 * @param branch 分支选择：0 = 开式, 1 = 闭式
 * @return 求解结果
 */
[[nodiscard]] FourBarSolution solve_fourbar(
    const FourBarLinkage& linkage, double input_angle, int branch = 0);

/**
 * @brief 四杆机构运动分析（全周期）
 *
 * @param linkage 四杆机构参数
 * @param steps 采样步数
 * @return 各角度位置的解序列
 */
[[nodiscard]] std::vector<FourBarSolution> analyze_fourbar(
    const FourBarLinkage& linkage, int steps = 360);

// ═══════════════════════════════════════════════════════════
//  齿轮传动 (Gear Train)
// ═══════════════════════════════════════════════════════════

/// 齿轮副定义
struct GearPair {
    int teeth_driver = 20;     ///< 主动轮齿数
    int teeth_driven = 40;     ///< 从动轮齿数
    double module = 1.0;       ///< 模数 (mm)
    double pressure_angle = 20.0 * M_PI / 180.0;  ///< 压力角（弧度，默认 20°）
    double center_distance = 0.0; ///< 中心距（0 = 自动计算）

    /// 传动比 = driven_teeth / driver_teeth
    [[nodiscard]] double ratio() const {
        return static_cast<double>(teeth_driven) / teeth_driven;
    }

    /// 计算中心距（若未指定）
    [[nodiscard]] double compute_center_distance() const {
        if (center_distance > 0) return center_distance;
        return module * (teeth_driver + teeth_driven) / 2.0;
    }
};

/// 齿轮传动结果
struct GearSolution {
    double driver_angle = 0.0;   ///< 主动轮角度（弧度）
    double driven_angle = 0.0;   ///< 从动轮角度（弧度）
    double angular_velocity_ratio = 0.0; ///< 角速度比
};

/**
 * @brief 求解齿轮传动
 *
 * @param gear 齿轮副参数
 * @param driver_angle 主动轮转角（弧度）
 * @return 传动结果
 */
[[nodiscard]] GearSolution solve_gear(
    const GearPair& gear, double driver_angle);

/**
 * @brief 齿轮系求解（多级齿轮）
 *
 * @param stages 各级齿轮副（按传动顺序）
 * @param input_angle 第一级输入角
 * @return 各级输出角度
 */
[[nodiscard]] std::vector<GearSolution> solve_gear_train(
    const std::vector<GearPair>& stages, double input_angle);

// ═══════════════════════════════════════════════════════════
//  凸轮机构 (Cam-Follower)
// ═══════════════════════════════════════════════════════════

/// 从动件运动规律类型
enum class CamMotionType {
    Dwell,            ///< 停歇（无运动）
    ConstantVelocity, ///< 等速
    SimpleHarmonic,   ///< 简谐运动
    Cycloidal,        ///< 摆线运动
    Polynomial345,    ///< 3-4-5 多项式
};

/// 凸轮运动段定义
struct CamSegment {
    double start_angle = 0.0;    ///< 起始凸轮角（弧度）
    double end_angle = 0.0;      ///< 终止凸轮角（弧度）
    double start_lift = 0.0;     ///< 起始升程
    double end_lift = 0.0;       ///< 终止升程
    CamMotionType motion = CamMotionType::Dwell;
};

/// 凸轮-从动件系统
struct CamFollowerSystem {
    double base_radius = 20.0;   ///< 基圆半径
    std::vector<CamSegment> segments; ///< 运动段序列
    double follower_offset = 0.0;     ///< 从动件偏距（对心 = 0）

    /// 总升程
    [[nodiscard]] double total_lift() const;
};

/// 从动件瞬时状态
struct FollowerState {
    double cam_angle = 0.0;       ///< 凸轮转角（弧度）
    double displacement = 0.0;    ///< 从动件位移
    double velocity = 0.0;        ///< 从动件速度（mm/rad）
    double acceleration = 0.0;    ///< 从动件加速度（mm/rad²）
    double pressure_angle = 0.0;  ///< 压力角（弧度）
};

/**
 * @brief 凸轮机构求解
 *
 * 给定凸轮角度，计算从动件位移/速度/加速度。
 *
 * @param cam 凸轮-从动件系统
 * @param cam_angle 凸轮转角（弧度）
 * @return 从动件状态
 */
[[nodiscard]] FollowerState solve_cam(
    const CamFollowerSystem& cam, double cam_angle);

/**
 * @brief 凸轮运动全周期分析
 *
 * @param cam 凸轮-从动件系统
 * @param steps 采样步数
 * @return 全周期从动件状态序列
 */
[[nodiscard]] std::vector<FollowerState> analyze_cam(
    const CamFollowerSystem& cam, int steps = 360);

} // namespace vde::brep