ViewDesignEngine/include/vde/brep/assembly_patterns.h

#pragma once
/**
 * @file assembly_patterns.h
 * @brief 装配体阵列/模式 — 环形阵列、矩形阵列、镜像、特征驱动阵列、填充阵列
 *
 * 提供类似 SolidWorks/Inventor 的装配级阵列功能：
 *  - CircularPattern      — 环形阵列（绕轴旋转分布零件）
 *  - RectangularPattern   — 矩形阵列（沿两个方向的网格分布）
 *  - MirrorPattern        — 镜像阵列（相对于平面镜像复制）
 *  - PatternDriven        — 特征驱动阵列（由装配特征自动驱动布件）
 *  - fill_pattern         — 填充阵列（在指定区域内自动填充零件）
 *
 * @ingroup brep
 */
#include "vde/core/point.h"
#include "vde/core/transform.h"
#include "vde/brep/brep.h"
#include "vde/brep/assembly.h"
#include <vector>
#include <string>
#include <memory>
#include <functional>

namespace vde::brep {

using core::Point3D;
using core::Vector3D;
using core::Transform3D;

// ═══════════════════════════════════════════════════════════════════════════
//  阵列参数结构体
// ═══════════════════════════════════════════════════════════════════════════

/// 环形阵列参数
struct CircularPatternParams {
    Point3D center          = Point3D::Zero();   ///< 环形中心点
    Vector3D axis           = Vector3D::UnitZ(); ///< 旋转轴（自动归一化）
    int count               = 6;                  ///< 实例总数（含源）
    double total_angle_deg  = 360.0;              ///< 总角度 (度)
    bool equal_spacing      = true;               ///< 等距分布
    /// 可选：仅生成指定索引的实例（跳过的实例不会创建）
    std::vector<int> skip_instances;
};

/// 矩形阵列参数
struct RectangularPatternParams {
    Vector3D direction1     = Vector3D::UnitX(); ///< 第一方向
    Vector3D direction2     = Vector3D::UnitY(); ///< 第二方向
    double spacing1         = 10.0;               ///< 第一方向间距 (mm)
    double spacing2         = 10.0;               ///< 第二方向间距 (mm)
    int count1              = 3;                  ///< 第一方向实例数（含源）
    int count2              = 3;                  ///< 第二方向实例数（含源）
    bool staggered          = false;              ///< 交错排列
    double stagger_offset   = 0.5;                ///< 交错偏移量 (间距比例)
};

/// 镜像阵列参数
struct MirrorPatternParams {
    Point3D plane_origin    = Point3D::Zero();   ///< 镜像平面上的点
    Vector3D plane_normal   = Vector3D::UnitX(); ///< 镜像平面法向（自动归一化）
    bool copy_original      = true;               ///< 是否保留原始零件
};

/// 特征驱动阵列参数
struct PatternDrivenParams {
    /// 驱动特征的类型：孔、槽、凸台
    enum class FeatureType { Hole, Slot, Boss };
    FeatureType feature_type = FeatureType::Hole;
    double min_spacing       = 5.0;    ///< 最小间距 (mm)
    double max_instances     = 100;    ///< 最大实例数
    /// 驱动特征位置的来源装配体
    const Assembly* source_assembly = nullptr;
};

/// 填充阵列参数
struct FillPatternParams {
    /// 填充区域 — 由 AABB 定义矩形边界
    Point3D fill_min        = Point3D::Zero();
    Point3D fill_max        = Point3D(100, 100, 0);
    Vector3D fill_plane_normal = Vector3D::UnitZ(); ///< 填充平面法向

    double spacing          = 10.0;     ///< 实例间距 (mm)
    double margin           = 5.0;      ///< 边界留白 (mm)
    double angle_deg        = 0.0;      ///< 填充方向角度 (度)
    bool   hexagonal        = false;    ///< 六边形密排（vs 正方形网格）
    /// 可选：排除区域（在这些 AABB 内不放置实例）
    std::vector<std::pair<Point3D, Point3D>> exclude_regions;
};

// ═══════════════════════════════════════════════════════════════════════════
//  阵列结果
// ═══════════════════════════════════════════════════════════════════════════

/// 阵列实例信息
struct PatternInstance {
    Transform3D transform;           ///< 世界变换矩阵
    std::string name;                ///< 实例名称（含序号）
    int index = 0;                   ///< 实例序号（源为 0）
};

/// 阵列结果
struct PatternResult {
    std::vector<PatternInstance> instances;  ///< 生成的实例列表
    size_t total_count = 0;                  ///< 总实例数（含源）
    size_t skipped_count = 0;                ///< 跳过的实例数
};

// ═══════════════════════════════════════════════════════════════════════════
//  阵列函数
// ═══════════════════════════════════════════════════════════════════════════

/// 环形阵列 — 绕轴旋转分布零件的多个副本
///
/// 以源零件的世界变换为基准，绕指定轴旋转生成 count 个等距副本。
///
/// @param source_transform 源零件的世界变换矩阵
/// @param source_name      源零件名称
/// @param params           环形阵列参数
/// @return 包含所有实例变换的阵列结果
///
/// @ingroup brep
[[nodiscard]] PatternResult circular_pattern(
    const Transform3D& source_transform,
    const std::string& source_name,
    const CircularPatternParams& params);

/// 矩形阵列 — 沿两个方向生成网格分布副本
///
/// 支持交错排列 (staggered)，方向可任意指定（不必正交）。
///
/// @param source_transform 源零件的世界变换矩阵
/// @param source_name      源零件名称
/// @param params           矩形阵列参数
/// @return 包含所有实例变换的阵列结果
///
/// @ingroup brep
[[nodiscard]] PatternResult rectangular_pattern(
    const Transform3D& source_transform,
    const std::string& source_name,
    const RectangularPatternParams& params);

/// 镜像阵列 — 相对于平面镜像复制
///
/// 将源零件相对于指定平面镜像，可选是否保留原始零件。
///
/// @param source_transform 源零件的世界变换矩阵
/// @param source_name      源零件名称
/// @param params           镜像参数
/// @return 包含源和镜像（或仅镜像）实例的阵列结果
///
/// @ingroup brep
[[nodiscard]] PatternResult mirror_pattern(
    const Transform3D& source_transform,
    const std::string& source_name,
    const MirrorPatternParams& params);

/// 特征驱动阵列 — 根据装配特征自动布件
///
/// 扫描装配体中的特征（孔/槽/凸台），在每个特征位置放置零件实例。
/// 适用于螺栓孔阵列自动装配、焊接点阵列等。
///
/// @param source_transform 源零件的世界变换矩阵
/// @param source_name      源零件名称
/// @param params           特征驱动参数
/// @return 包含所有实例变换的阵列结果
///
/// @ingroup brep
[[nodiscard]] PatternResult pattern_driven(
    const Transform3D& source_transform,
    const std::string& source_name,
    const PatternDrivenParams& params);

/// 填充阵列 — 在指定区域内自动填充零件实例
///
/// 在由 AABB 定义的矩形区域内，以指定间距和角度自动填充零件实例。
/// 支持正方形网格和六边形密排两种模式，可设置边界留白和排除区域。
///
/// @param source_transform 源零件的世界变换矩阵
/// @param source_name      源零件名称
/// @param params           填充参数
/// @return 包含所有实例变换的阵列结果
///
/// @ingroup brep
[[nodiscard]] PatternResult fill_pattern(
    const Transform3D& source_transform,
    const std::string& source_name,
    const FillPatternParams& params);

/// 将阵列结果应用到装配体
///
/// 根据阵列结果，在装配体中创建所有实例的副本。
///
/// @param assembly 目标装配体（将在其根节点下添加实例）
/// @param result   阵列结果
/// @param source_name 源零件名称（用于查找）
/// @return 成功创建的实例数
///
/// @ingroup brep
size_t apply_pattern_to_assembly(
    Assembly& assembly,
    const PatternResult& result,
    const std::string& source_name);

}  // namespace vde::brep