ViewDesignEngine/include/vde/brep/brep_boolean.h

#pragma once
/**
 * @file brep_boolean.h
 * @brief B-Rep 级别的布尔运算
 *
 * 对 BrepModel 实体执行精确的布尔运算，区别于基于网格的布尔运算
 * （后者通过 mesh_boolean.h 提供）。
 *
 * ## B-Rep 布尔运算 vs 网格布尔运算
 *
 * | 特性              | B-Rep 布尔             | 网格布尔                |
 * |-------------------|------------------------|-------------------------|
 * | 精度              | 精确（解析曲面）        | 近似（离散三角形）        |
 * | 速度              | 较慢（需要曲面交线计算） | 较快                    |
 * | 输出              | B-Rep 模型             | 三角网格                 |
 * | 适用场景           | CAD 精确建模            | 实时/渲染/快速原型       |
 *
 * ## 典型工作流
 *
 * 1. 通过 modeling.h 创建基本体（如 make_box + make_cylinder）
 * 2. 使用本文件的布尔运算组合它们
 * 3. 通过 to_mesh() 或 export_step() 导出结果
 *
 * @ingroup brep
 */
#include "vde/brep/brep.h"

namespace vde::brep {

/**
 * @brief B-Rep 布尔并集: A ∪ B
 *
 * 合并两个 B-Rep 实体为一个，自动处理相交曲面的分割和重新连接。
 *
 * **算法概要:**
 * 1. 计算两个模型之间的所有曲面交线
 * 2. 沿交线分割曲面
 * 3. 根据布尔操作类型保留或丢弃分割后的面片
 * 4. 重新连接拓扑结构（边、环、壳）
 *
 * @param a 第一个 B-Rep 实体
 * @param b 第二个 B-Rep 实体
 * @return 新的 B-Rep 实体（a ∪ b）
 *
 * @warning 两个输入实体必须都是水密（watertight）且非自交（non-self-intersecting）。
 *          如果任一输入未通过验证，结果未定义。
 *
 * @code{.cpp}
 * auto box = make_box(2, 2, 2);
 * auto sphere = make_sphere(1.5);
 * auto result = brep_union(box, sphere);
 * @endcode
 *
 * @see brep_intersection 交集
 * @see brep_difference 差集
 */
[[nodiscard]] BrepModel brep_union(const BrepModel& a, const BrepModel& b);

/**
 * @brief B-Rep 布尔交集: A ∩ B
 *
 * 保留两个实体共有的区域。
 *
 * @param a 第一个 B-Rep 实体
 * @param b 第二个 B-Rep 实体
 * @return 新的 B-Rep 实体（a ∩ b）
 *
 * @pre a 和 b 必须是有效的封闭实体
 *
 * @code{.cpp}
 * // 长方体与球体的交集 = 八分之一球（角部）
 * auto box = make_box(2, 2, 2);
 * auto sphere = make_sphere(1.8);
 * auto result = brep_intersection(box, sphere);
 * @endcode
 *
 * @see brep_union 并集
 * @see brep_difference 差集
 */
[[nodiscard]] BrepModel brep_intersection(const BrepModel& a, const BrepModel& b);

/**
 * @brief B-Rep 布尔差集: A \ B
 *
 * 从 A 中减去 B 所占据的区域。
 *
 * @param a 被减实体 A
 * @param b 减去实体 B
 * @return 新的 B-Rep 实体（a \ b）
 *
 * @pre a 和 b 必须是有效的封闭实体
 *
 * @code{.cpp}
 * // 从盒子中减去球体 = 带球形凹陷的盒子
 * auto box = make_box(2, 2, 2);
 * auto sphere = make_sphere(0.5);
 * auto result = brep_difference(box, sphere);
 * @endcode
 *
 * @see brep_union 并集
 * @see brep_intersection 交集
 */
[[nodiscard]] BrepModel brep_difference(const BrepModel& a, const BrepModel& b);

}  // namespace vde::brep