ViewDesignEngine/docs/API-REFERENCE.md

# ViewDesignEngine API 参考手册

> 版本 3.2.0 | 76 个头文件


## 基础模块 (`vde::foundation`)


### `error_codes.h`

**全局错误码枚举**  
`enum class ErrorCode : int32_t {`  



### `exact_predicates.h`

**二维定向测试结果**  
`enum class Orientation { Clockwise, CounterClockwise, Collinear }`  


**圆测试结果**  
`enum class CircleTest { Inside, On, Outside }`  


**自适应精度二维定向测试（Shewchuk 算法）**  
`Orientation orient_2d(const Point2D& a, const Point2D& b, const Point2D& c)`  

| 参数 | 说明 |
|------|------|
| `a` | 第一个点 |
| `b` | 第二个点 |
| `c` | 第三个点 |

**返回**: Orientation::Collinear 若三点共线  
> Delaunay 三角剖分、凸包计算等几何算法的核心原语  

**参见**: `orient_3d, in_circle`  


**自适应精度三维定向测试**  
`Orientation orient_3d(const Point3D& a, const Point3D& b,`  

| 参数 | 说明 |
|------|------|
| `a` | 第一个点 |
| `b` | 第二个点 |
| `c` | 第三个点 |
| `d` | 第四个点（测试点） |

**返回**: Orientation::Collinear 若四点共面  
> 三维 Delaunay 剖分和凸包计算的核心原语  

**参见**: `orient_2d, in_circle`  


**自适应精度圆内测试（In-Circle Test）**  
`CircleTest in_circle(const Point2D& a, const Point2D& b,`  

| 参数 | 说明 |
|------|------|
| `a` | 三角形第一个顶点 |
| `b` | 三角形第二个顶点 |
| `c` | 三角形第三个顶点 |
| `d` | 待测试点 |

**返回**: CircleTest::Outside 若 d 在三角形外接圆外部  
> Delaunay 三角剖分的空圆性质检查核心原语  

**参见**: `orient_2d, orient_3d`  


**自适应双精度谓词后端（默认）**  


**二维定向测试**  
`static exact::Orientation orient_2d(const Point2D& a, const Point2D& b, const Point2D& c) {`  

| 参数 | 说明 |
|------|------|
| `a,b,c` | 三个二维点 |

**返回**: 定向结果  

**参见**: `exact::orient_2d`  


**三维定向测试**  
`static exact::Orientation orient_3d(const Point3D& a, const Point3D& b,`  

| 参数 | 说明 |
|------|------|
| `a,b,c,d` | 四个三维点 |

**返回**: 定向结果  

**参见**: `exact::orient_3d`  


**圆内测试**  
`static exact::CircleTest in_circle(const Point2D& a, const Point2D& b,`  

| 参数 | 说明 |
|------|------|
| `a,b,c` | 三角形三顶点 |
| `d` | 待测试点 |

**返回**: 圆测试结果  

**参见**: `exact::in_circle`  



### `exact_predicates_gmp.h`

**GMP 精确算术谓词后端**  
`struct GmpExact {`  
> 仅在定义了 VDE_USE_GMP 宏且链接了 GMP 库时可用  


**精确有理数二维定向测试**  
`static Orientation orient_2d(const Point2D& a, const Point2D& b, const Point2D& c) {`  

| 参数 | 说明 |
|------|------|
| `a` | 第一个点 |
| `b` | 第二个点 |
| `c` | 第三个点 |

**返回**: 定向结果（保证正确，无舍入误差）  

**参见**: `GmpExact::orient_3d, GmpExact::in_circle`  


**精确有理数三维定向测试**  
`static Orientation orient_3d(const Point3D& a, const Point3D& b,`  

| 参数 | 说明 |
|------|------|
| `a,b,c` | 定义平面的三点 |
| `d` | 待测试点 |

**返回**: 定向结果（零误差）  

**参见**: `GmpExact::orient_2d`  


**精确有理数圆内测试**  
`static CircleTest in_circle(const Point2D& a, const Point2D& b,`  

| 参数 | 说明 |
|------|------|
| `a,b,c` | 三角形三顶点 |
| `d` | 待测试点 |

**返回**: 圆测试结果（零误差）  

**参见**: `GmpExact::orient_2d`  



### `format_utils.h`

**以 CAD 级别精度格式化双精度浮点数**  
`inline std::string fmt_double(double v, int precision = 12) {`  

| 参数 | 说明 |
|------|------|
| `v` | 要格式化的双精度数 |
| `precision` | 有效数字位数（默认 12） |

**返回**: 格式化后的字符串，如 "1.234567890123e+02"  
> 总是确保指数部分带符号（如 "e+00" 而非 "e00"），便于解析器统一处理  

**参见**: `fmt_iges_real, fmt_point`  


**IGES 格式实数输出**  
`inline std::string fmt_iges_real(double v, int /*precision*/ = 12) {`  

| 参数 | 说明 |
|------|------|
| `v` | 要格式化的双精度数 |

**返回**: IGES 格式字符串，如 "3.141592653590D+00"  

**参见**: `fmt_double`  


**格式化三维点为逗号分隔字符串**  
`inline std::string fmt_point(const core::Point3D& p, bool use_d = false) {`  

| 参数 | 说明 |
|------|------|
| `p` | 三维点 |
| `use_d` | 若为 true，使用 IGES 风格 D 指数标记 |

**返回**: 逗号分隔的坐标字符串  

**参见**: `fmt_double, fmt_iges_real`  


**将字符串填充到恰好 72 个字符**  
`inline std::string pad72(const std::string& s) {`  

| 参数 | 说明 |
|------|------|
| `s` | 输入字符串 |

**返回**: 恰好 72 字符的字符串（不足右侧补空格，超出截断）  

**参见**: `format_iges_line`  


**格式化 IGES 段落行**  
`inline std::string format_iges_line(const std::string& data, char section_char, int seq) {`  

| 参数 | 说明 |
|------|------|
| `data` | 数据内容（最多 72 字符，超出截断） |
| `section_char` | 段落标识符（如 'P' 参数段, 'D' 目录段） |
| `seq` | 行序号（1-based） |

**返回**: 完整 IGES 行（含换行符），共 81 字符  

**参见**: `pad72`  



### `interval.h`

**双精度区间算术类**  


**从单值构造精确区间（退化为点）**  
`Interval(double v) : lo(v), hi(v) {}`  

| 参数 | 说明 |
|------|------|
| `v` | 区间值，[v, v] |


**从上下界构造区间**  
`Interval(double l, double h) : lo(std::min(l,h)), hi(std::max(l,h)) {}`  

| 参数 | 说明 |
|------|------|
| `l` | 下界 |
| `h` | 上界 |


**区间中点**  
`[[nodiscard]] double mid() const { return (lo + hi) * 0.5; }`  

**返回**: (lo + hi) / 2  


**区间宽度**  
`[[nodiscard]] double width() const { return hi - lo; }`  

**返回**: hi - lo  


**判断区间是否包含给定值**  
`[[nodiscard]] bool contains(double v) const { return lo <= v && v <= hi; }`  

| 参数 | 说明 |
|------|------|
| `v` | 测试值 |

**返回**: true 若 lo ≤ v ≤ hi  


**判断区间是否足够窄（收敛）**  
`[[nodiscard]] bool is_exact(double eps = 1e-12) const { return width() < eps; }`  

| 参数 | 说明 |
|------|------|
| `eps` | 宽度阈值（默认 1e-12） |

**返回**: true 若区间宽度 < eps  


**判断两个区间是否有重叠**  
`[[nodiscard]] bool overlaps(const Interval& o) const {`  

| 参数 | 说明 |
|------|------|
| `o` | 另一个区间 |

**返回**: true 若存在公共点  


**确定性区间比较**  
`[[nodiscard]] int cmp(const Interval& o) const {`  

| 参数 | 说明 |
|------|------|
| `o` | 另一个区间 |

**返回**: 0 若区间重叠，无法确定  


**区间加法**  
`Interval operator+(const Interval& o) const {`  

**返回**: [this.lo + o.lo, this.hi + o.hi]  


**区间减法**  
`Interval operator-(const Interval& o) const {`  

**返回**: [this.lo - o.hi, this.hi - o.lo]（保守估计）  


**区间乘法**  
`Interval operator*(const Interval& o) const {`  

**返回**: [min(a*c,a*d,b*c,b*d), max(a*c,a*d,b*c,b*d)]  


**区间除法**  
`Interval operator/(const Interval& o) const {`  

**返回**: 结果区间或 [-∞, +∞]（除数为零区间）  


**区间平方根**  
`[[nodiscard]] Interval sqrt() const {`  

**返回**: [sqrt(max(0, lo)), sqrt(max(0, hi))]  


**从双精度值创建区间（含舍入误差带）**  
`static Interval from_double(double v, double error = 0) {`  

| 参数 | 说明 |
|------|------|
| `v` | 中心值 |
| `error` | 误差半径（默认 0） |

**返回**: [v - error, v + error]  


**从坐标值创建区间（含 ULP 误差带）**  
`static Interval from_coord(double v) {`  

| 参数 | 说明 |
|------|------|
| `v` | 坐标值 |

**返回**: 包含浮点舍入误差的区间  


**二维定向行列式的区间验证**  
`inline Interval orient_2d_interval(double ax, double ay, double bx, double by, double cx, double cy) {`  

| 参数 | 说明 |
|------|------|
| `ax,ay` | 点 a 的坐标 |
| `bx,by` | 点 b 的坐标 |
| `cx,cy` | 点 c 的坐标 |

**返回**: 行列式的区间值  

**参见**: `orient_2d_verified`  


**使用区间算术验证 orient_2d 结果**  
`inline int orient_2d_verified(double ax, double ay, double bx, double by, double cx, double cy) {`  

| 参数 | 说明 |
|------|------|
| `ax,ay` | 点 a 的坐标 |
| `bx,by` | 点 b 的坐标 |
| `cx,cy` | 点 c 的坐标 |

**返回**: 1 确认 CounterClockwise  

**参见**: `orient_2d_interval, Interval::cmp`  



### `io_gltf.h`

**glTF 2.0 导出选项**  
`struct GltfOptions {`  


**导出网格为 glTF 2.0 / GLB 格式**  
`bool write_gltf(const std::string& filepath, const mesh::HalfedgeMesh& mesh,`  

| 参数 | 说明 |
|------|------|
| `filepath` | 输出文件路径（.glb 或 .gltf） |
| `mesh` | 要导出的半边网格 |
| `options` | 导出选项（格式、法线、颜色等） |

**返回**: false 导出失败（文件无法创建等）  
> 生成的 glTF 符合 2.0 规范，兼容 Blender、three.js、Unreal Engine 等工具  

**参见**: `write_brep_gltf, GltfOptions`  


**导出 B-Rep 模型为 GLB 格式（通过面片化）**  
`bool write_brep_gltf(const std::string& filepath, const brep::BrepModel& model,`  

| 参数 | 说明 |
|------|------|
| `filepath` | 输出文件路径（建议 .glb） |
| `model` | 要导出的 B-Rep 模型 |
| `tessellation_res` | 每条边的离散段数（默认 32），越大越精确 |

**返回**: false 导出失败  

**参见**: `write_gltf`  



### `io_obj.h`

**OBJ 文件解析结果数据结构**  
`struct ObjMeshData {`  


**每个面的顶点索引列表（0-based）**  
`std::vector<std::vector<int>> faces`  


**每个面的纹理坐标索引列表（0-based）**  
`std::vector<std::vector<int>> face_texcoords`  


**每个面的法线索引列表（0-based）**  
`std::vector<std::vector<int>> face_normals`  


**每个面对应的材质名称**  
`std::vector<std::string> face_materials`  


**读取 Wavefront OBJ 文件**  
`ObjMeshData read_obj(const std::string& filepath)`  

| 参数 | 说明 |
|------|------|
| `filepath` | OBJ 文件路径 |

**返回**: 解析后的 ObjMeshData  
> 不解析 MTL 材质文件，仅记录 usemtl 指令中的材质名称  
> 面索引在内部转换为 0-based；若文件中使用相对索引（负值），自动转换为正向  

**参见**: `write_obj, ObjMeshData`  


**写入 Wavefront OBJ 文件**  
`void write_obj(const std::string& filepath, const ObjMeshData& data)`  

| 参数 | 说明 |
|------|------|
| `filepath` | 输出文件路径 |
| `data` | 要写出的网格数据 |
> 输出的面索引为 1-based（OBJ 标准）  

**参见**: `read_obj`  



### `io_ply.h`

**读取 PLY 文件（Stanford Polygon Format）**  
`mesh::HalfedgeMesh read_ply(const std::string& filepath)`  

| 参数 | 说明 |
|------|------|
| `filepath` | PLY 文件路径 |

**返回**: 解析后的半边网格  
> 自动检测文件头部 magic number 判断 ASCII / 二进制格式  
> 二进制格式仅支持小端序（little-endian）  
> 返回类型为 HalfedgeMesh，内部自动建立半边拓扑  

**参见**: `write_ply`  


**写入 PLY 文件（ASCII 格式）**  
`void write_ply(const std::string& filepath, const mesh::HalfedgeMesh& mesh)`  

| 参数 | 说明 |
|------|------|
| `filepath` | 输出文件路径 |
| `mesh` | 要导出的半边网格 |
> 输出的 PLY 为 ASCII 编码，易于人工阅读和编辑  
> 若需要二进制输出以提高性能，请使用 BinarySerializer  

**参见**: `read_ply, BinarySerializer`  



### `io_stl.h`

**STL 三角形面片**  
`struct StlTriangle {`  


**读取 STL 文件（自动检测格式）**  
`std::vector<StlTriangle> read_stl(const std::string& filepath)`  

| 参数 | 说明 |
|------|------|
| `filepath` | STL 文件路径 |

**返回**: 三角形面片列表  
> 自动格式检测：二进制 STL 的 80 字节头后跟 4 字节三角形数量  
> ASCII STL 以 "solid name" 开头  

**参见**: `write_stl, write_stl_ascii`  


**写入二进制 STL 文件**  
`void write_stl(const std::string& filepath, const std::vector<StlTriangle>& tris)`  

| 参数 | 说明 |
|------|------|
| `filepath` | 输出文件路径 |
| `tris` | 三角形面片列表 |
> 二进制 STL 格式：80 字节头 + 4 字节三角形数 + 每三角形 50 字节  
> 法向量在写入时自动归一化  

**参见**: `read_stl, write_stl_ascii`  


**写入 ASCII STL 文件**  
`void write_stl_ascii(const std::string& filepath, const std::vector<StlTriangle>& tris)`  

| 参数 | 说明 |
|------|------|
| `filepath` | 输出文件路径 |
| `tris` | 三角形面片列表 |

**参见**: `read_stl, write_stl`  



### `math_types.h`

**通用 N 维点类型（使用 Eigen 列向量）**  
`template <typename T, size_t Dim>`  


**通用 N 维向量类型（与 Point 相同的列向量表示）**  
`template <typename T, size_t Dim>`  


**基础模块提供 VDE 引擎的核心基础设施：**  
`/** @} */ // end of foundation group`  



### `memory_pool.h`

**固定块大小的内存池**  
`template <typename T>`  
> 内存池不调用对象的构造函数/析构函数，仅管理原始内存  
> 适合 POD 类型或通过 placement new 手动管理生命周期的类型  


**构造内存池**  
`explicit MemoryPool(size_t chunk_size = 1024) : chunk_size_(chunk_size) {}`  

| 参数 | 说明 |
|------|------|
| `chunk_size` | 每个内存块可容纳的对象数（默认 1024） |


**析构内存池，释放所有已分配的内存块**  
`~MemoryPool() { for (auto* p : chunks_) ::operator delete(p); }`  


**从池中分配 n 个 T 对象的内存**  
`T* allocate(size_t n = 1) {`  

| 参数 | 说明 |
|------|------|
| `n` | 对象数量（当前未使用，保留用于 API 兼容） |

**返回**: 指向未初始化内存的指针  


**将内存归还到池中**  
`void deallocate(T* p, size_t = 1) {`  

| 参数 | 说明 |
|------|------|
| `p` | 之前从 allocate() 获取的指针 |


**分配一个新的内存块并初始化空闲链表**  
`void allocate_chunk() {`  



### `predicates.h`

**统一谓词接口 — 编译时选择 GMP 或自适应双精度后端**  
`struct Predicates {`  


**二维定向测试**  
`static exact::Orientation orient_2d(const Point2D& a, const Point2D& b, const Point2D& c) {`  

| 参数 | 说明 |
|------|------|
| `a,b,c` | 三点 |

**返回**: 定向结果  


**三维定向测试**  
`static exact::Orientation orient_3d(const Point3D& a, const Point3D& b,`  

| 参数 | 说明 |
|------|------|
| `a,b,c,d` | 四点 |

**返回**: 定向结果  


**圆内测试**  
`static exact::CircleTest in_circle(const Point2D& a, const Point2D& b,`  

| 参数 | 说明 |
|------|------|
| `a,b,c` | 三角形三顶点 |
| `d` | 测试点 |

**返回**: 圆测试结果  


**二维定向测试便捷封装**  
`inline exact::Orientation orient(const Point2D& a, const Point2D& b, const Point2D& c) {`  

| 参数 | 说明 |
|------|------|
| `a,b,c` | 三个二维点 |

**返回**: Orientation::Clockwise / CounterClockwise / Collinear  


**三维定向测试便捷封装**  
`inline exact::Orientation orient(const Point3D& a, const Point3D& b, const Point3D& c, const Point3D& d) {`  

| 参数 | 说明 |
|------|------|
| `a,b,c` | 定义平面的三点 |
| `d` | 测试点 |

**返回**: Orientation::Clockwise / CounterClockwise / Collinear  


**圆内测试便捷封装**  
`inline exact::CircleTest in_circle(const Point2D& a, const Point2D& b, const Point2D& c, const Point2D& d) {`  

| 参数 | 说明 |
|------|------|
| `a,b,c` | 三角形三顶点 |
| `d` | 测试点 |

**返回**: CircleTest::Inside / On / Outside  



### `serializer.h`

**二进制序列化格式的网格数据结构**  
`struct SerializedMesh {`  


**二进制序列化器**  
> 该格式专为 VDE 内部快速读写设计，不适用于跨平台数据交换  
> 使用 glTF/OBJ/STL 进行外部交换，此格式用于本地缓存  


**序列化网格到二进制缓冲区**  
`static std::vector<uint8_t> serialize(const mesh::HalfedgeMesh& mesh)`  

| 参数 | 说明 |
|------|------|
| `mesh` | 要序列化的半边网格 |

**返回**: 压缩后的二进制数据（含文件头）  


**从二进制缓冲区反序列化网格**  
`static mesh::HalfedgeMesh deserialize(const std::vector<uint8_t>& data)`  

| 参数 | 说明 |
|------|------|
| `data` | 之前由 serialize() 生成的二进制数据 |

**返回**: 恢复的半边网格  


**序列化并写入文件**  
`static bool write_file(const std::string& path, const mesh::HalfedgeMesh& mesh)`  

| 参数 | 说明 |
|------|------|
| `path` | 输出文件路径 |
| `mesh` | 要保存的半边网格 |

**返回**: false 文件创建失败  

**参见**: `read_file`  


**从文件读取并反序列化**  
`static mesh::HalfedgeMesh read_file(const std::string& path)`  

| 参数 | 说明 |
|------|------|
| `path` | VDE 二进制格式文件路径 |

**返回**: 恢复的半边网格  

**参见**: `write_file`  


**VDE 二进制文件魔数："VDEGEOM\0"**  


**VDE 二进制格式当前版本号**  



### `tolerance.h`

**分层容差管理类**  


**构造容差对象**  
`Tolerance(double absolute = 1e-6, double relative = 1e-8,`  

| 参数 | 说明 |
|------|------|
| `absolute` | 绝对容差，默认 1e-6 |
| `relative` | 相对容差，默认 1e-8 |
| `angular` | 角度容差（弧度），默认 1e-8 |
| `snapping` | 吸附容差，默认 1e-4 |


**判断两点是否相等（基于绝对容差）**  
`bool points_equal(const Eigen::MatrixXd& a, const Eigen::MatrixXd& b) const {`  

| 参数 | 说明 |
|------|------|
| `a` | 第一个点（Eigen 矩阵） |
| `b` | 第二个点（Eigen 矩阵） |

**返回**: true 若两点的欧氏距离 < absolute_  


**判断值是否接近零**  
`template <typename T>`  

| 参数 | 说明 |
|------|------|
| `value` | 测试值 |

**返回**: true 若 |value| < absolute_  


**混合容差相等判断**  
`template <typename T>`  

| 参数 | 说明 |
|------|------|
| `a` | 第一个值 |
| `b` | 第二个值 |

**返回**: true 若两值在容差范围内相等  


**收紧容差**  
`Tolerance tighten(double factor = 0.1) const {`  

| 参数 | 说明 |
|------|------|
| `factor` | 收紧因子（默认 0.1） |

**返回**: 收紧后的新容差对象  


**放宽容差**  
`Tolerance relax(double factor = 10.0) const {`  

| 参数 | 说明 |
|------|------|
| `factor` | 放宽因子（默认 10.0） |

**返回**: 放宽后的新容差对象  


**合并两个容差，取更严格的（更小的）**  
`static Tolerance min(const Tolerance& a, const Tolerance& b) {`  

| 参数 | 说明 |
|------|------|
| `a` | 第一个容差 |
| `b` | 第二个容差 |

**返回**: 每项取 min 的新容差  


**获取全局容差实例**  
`static Tolerance& global() { return global_; }`  

**返回**: 全局容差的引用  


**设置全局容差**  
`static void set_global(const Tolerance& tol) { global_ = tol; }`  

| 参数 | 说明 |
|------|------|
| `tol` | 新的全局容差 |
> 推荐使用 ToleranceScope 进行临时修改，确保自动恢复  


**局部容差作用域（RAII）**  


**进入新的容差作用域**  
`explicit ToleranceScope(const Tolerance& tol) : previous_(Tolerance::global()) {`  

| 参数 | 说明 |
|------|------|
| `tol` | 此作用域内使用的容差 |


**退出容差作用域，恢复之前的全局容差**  
`~ToleranceScope() { Tolerance::set_global(previous_); }`  



## 核心几何 (`vde::core`)


### `aabb.h`

**轴对齐包围盒（AABB）**  
`template <typename T>`  
> 初始状态为空（min = +∞, max = -∞），需要通过 expand() 初始化  


**构造空包围盒**  
`AABB() : min_(Point3D::Constant(std::numeric_limits<T>::max())),`  


**从两个角点构造包围盒**  
`AABB(const Point3D& min, const Point3D& max) : min_(min), max_(max) {}`  

| 参数 | 说明 |
|------|------|
| `min` | 最小角点 |
| `max` | 最大角点 |


**扩展包围盒以包含给定点**  
`void expand(const Point3D& p) {`  

| 参数 | 说明 |
|------|------|
| `p` | 要包含的点 |


**扩展包围盒以包含另一个 AABB**  
`void expand(const AABB& other) {`  

| 参数 | 说明 |
|------|------|
| `other` | 另一个包围盒 |


**包围盒中心点**  
`[[nodiscard]] Point3D center() const { return (min_ + max_) * 0.5; }`  

**返回**: (min + max) / 2  


**包围盒对角线向量（从 min 到 max）**  
`[[nodiscard]] Vector3D extent() const { return max_ - min_; }`  

**返回**: max - min  


**包围盒表面积**  
`[[nodiscard]] T surface_area() const {`  

**返回**: 2 * (dx*dy + dy*dz + dz*dx)  


**包围盒体积**  
`[[nodiscard]] T volume() const {`  

**返回**: dx * dy * dz  


**测试点是否在包围盒内部（含边界）**  
`[[nodiscard]] bool contains(const Point3D& p) const {`  

| 参数 | 说明 |
|------|------|
| `p` | 测试点 |

**返回**: true 若 min ≤ p ≤ max（各分量）  


**测试两个包围盒是否相交（含边界接触）**  
`[[nodiscard]] bool intersects(const AABB& other) const {`  

| 参数 | 说明 |
|------|------|
| `other` | 另一个包围盒 |

**返回**: true 若存在交集  



### `convex_hull.h`

**二维凸包计算（Graham Scan 算法）**  
`std::vector<Point2D> convex_hull_2d(const std::vector<Point2D>& points)`  

| 参数 | 说明 |
|------|------|
| `points` | 输入点集（至少 3 个不共线点） |

**返回**: 凸包顶点序列（逆时针排列），不含共线的中间点  
> 自动过滤共线点，返回严格的凸包顶点  
> 若所有点共线，返回两个端点  

**参见**: `convex_hull_3d, Polygon2D::convex_hull_2d`  


**三维凸包计算（QuickHull 算法）**  
`std::vector<std::array<Point3D, 3>> convex_hull_3d(const std::vector<Point3D>& points)`  

| 参数 | 说明 |
|------|------|
| `points` | 输入点集（至少 4 个不共面点） |

**返回**: 凸包三角形列表，每个三角形三顶点按逆时针排列（从外部观察）  
> 返回的三角形法线方向朝外  
> 共面/退化点被自动丢弃  

**参见**: `convex_hull_2d`  



### `distance.h`

**两点之间的欧氏距离**  
`double distance(const Point3D& a, const Point3D& b)`  

| 参数 | 说明 |
|------|------|
| `a` | 第一个点 |
| `b` | 第二个点 |

**返回**: ||b - a||  


**点到直线的距离**  
`double distance(const Point3D& p, const Line3D<double>& line)`  

| 参数 | 说明 |
|------|------|
| `p` | 测试点 |
| `line` | 直线 |

**返回**: 垂直距离  


**点到线段的距离**  
`double distance(const Point3D& p, const Segment3D<double>& seg)`  

| 参数 | 说明 |
|------|------|
| `p` | 测试点 |
| `seg` | 线段 |

**返回**: 最短距离  


**点到平面的距离**  
`double distance(const Point3D& p, const Plane<double>& plane)`  

| 参数 | 说明 |
|------|------|
| `p` | 测试点 |
| `plane` | 平面 |

**返回**: 绝对垂直距离  

**参见**: `Plane::signed_distance`  


**点到三角形的距离**  
`double distance(const Point3D& p, const Triangle<double>& tri)`  

| 参数 | 说明 |
|------|------|
| `p` | 测试点 |
| `tri` | 三角形 |

**返回**: 最短距离  


**点到包围盒的距离**  
`double distance(const Point3D& p, const AABB<double>& box)`  

| 参数 | 说明 |
|------|------|
| `p` | 测试点 |
| `box` | 包围盒 |

**返回**: 最短距离（内部点返回 0）  


**两条线段之间的最短距离**  
`double distance(const Segment3D<double>& a, const Segment3D<double>& b)`  

| 参数 | 说明 |
|------|------|
| `a` | 第一条线段 |
| `b` | 第二条线段 |

**返回**: 最短距离（若相交则为 0）  


**两条直线之间的最短距离**  
`double distance(const Line3D<double>& a, const Line3D<double>& b)`  

| 参数 | 说明 |
|------|------|
| `a` | 第一条直线 |
| `b` | 第二条直线 |

**返回**: 最短距离  


**两个包围盒之间的最短距离**  
`double distance(const AABB<double>& a, const AABB<double>& b)`  

| 参数 | 说明 |
|------|------|
| `a` | 第一个包围盒 |
| `b` | 第二个包围盒 |

**返回**: 最短距离  


**两个三角形之间的最短距离**  
`double distance(const Triangle<double>& a, const Triangle<double>& b)`  

| 参数 | 说明 |
|------|------|
| `a` | 第一个三角形 |
| `b` | 第二个三角形 |

**返回**: 最短距离（若相交则为 0）  


**三角形上距给定点最近的点**  
`Point3D closest_point(const Point3D& p, const Triangle<double>& tri)`  

| 参数 | 说明 |
|------|------|
| `p` | 查询点 |
| `tri` | 三角形 |

**返回**: 三角形上距离 p 最近的点  


**线段上距给定点最近的点**  
`Point3D closest_point(const Point3D& p, const Segment3D<double>& seg)`  

| 参数 | 说明 |
|------|------|
| `p` | 查询点 |
| `seg` | 线段 |

**返回**: 线段上距离 p 最近的点（可能为端点）  


**包围盒上距给定点最近的点**  
`Point3D closest_point(const Point3D& p, const AABB<double>& box)`  

| 参数 | 说明 |
|------|------|
| `p` | 查询点 |
| `box` | 包围盒 |

**返回**: 包围盒边界上（或内部）距离 p 最近的点  


**平面上距给定点最近的点（正交投影）**  
`Point3D closest_point(const Point3D& p, const Plane<double>& plane)`  

| 参数 | 说明 |
|------|------|
| `p` | 查询点 |
| `plane` | 平面 |

**返回**: 点 p 在平面上的正交投影  

**参见**: `Plane::project`  



### `icp.h`

**ICP（迭代最近点）配准结果**  
`struct ICPResult {`  


**配准后的均方根误差**  
`double rms_error`  


**迭代最近点（ICP）刚体点云配准**  
`[[nodiscard]] ICPResult icp_register(const std::vector<Point3D>& source,`  

| 参数 | 说明 |
|------|------|
| `source` | 源点云（将被移动） |
| `target` | 目标点云（固定参考） |
| `max_iter` | 最大迭代次数（默认 50） |
| `tolerance` | 收敛容差：相邻两次 RMS 变化的阈值（默认 1e-6） |

**返回**: 配准结果，包含最终变换和误差  
> source 和 target 点数可以不同  
> 初始对齐越好，收敛越快；若初始偏差太大，可能收敛到局部最优  



### `line.h`

**三维无限直线**  
`template <typename T>`  


**从原点和方向构造直线**  
`Line3D(const Point3D& origin, const Vector3D& direction)`  

| 参数 | 说明 |
|------|------|
| `origin` | 直线上一点 |
| `direction` | 方向向量（自动归一化） |


**参数方程求点**  
`[[nodiscard]] Point3D point_at(T t) const { return origin_ + direction_ * t; }`  

| 参数 | 说明 |
|------|------|
| `t` | 参数值 |

**返回**: origin + direction * t  


**三维线段**  
`template <typename T>`  


**从两个端点构造线段**  
`Segment3D(const Point3D& p0, const Point3D& p1) : p0_(p0), p1_(p1) {}`  

| 参数 | 说明 |
|------|------|
| `p0` | 起点 |
| `p1` | 终点 |


**方向向量（未归一化）**  
`[[nodiscard]] Vector3D direction() const { return p1_ - p0_; }`  

**返回**: p1 - p0  


**线段长度**  
`[[nodiscard]] T length() const { return direction().norm(); }`  

**返回**: ||p1 - p0||  


**三维射线**  
`template <typename T>`  


**从原点和方向构造射线**  
`Ray3D(const Point3D& origin, const Vector3D& direction)`  

| 参数 | 说明 |
|------|------|
| `origin` | 射线起点 |
| `direction` | 方向向量（自动归一化） |


**参数方程求点（t ≥ 0）**  
`[[nodiscard]] Point3D point_at(T t) const { return origin_ + direction_ * t; }`  

| 参数 | 说明 |
|------|------|
| `t` | 参数值（应为非负） |

**返回**: origin + direction * t  



### `plane.h`

**三维平面**  
`template <typename T>`  


**从点和法线构造平面**  
`Plane(const Point3D& point, const Vector3D& normal)`  

| 参数 | 说明 |
|------|------|
| `point` | 平面上一点 |
| `normal` | 法向量（自动归一化） |


**从三点构造平面**  
`Plane(const Point3D& a, const Point3D& b, const Point3D& c)`  

| 参数 | 说明 |
|------|------|
| `a,b,c` | 平面上不共线的三点（右手定则决定法线方向） |


**获取平面方程常数 d**  
`[[nodiscard]] T d() const { return d_; }`  

**返回**: d 值  


**有向点到平面距离**  
`[[nodiscard]] T signed_distance(const Point3D& p) const { return normal_.dot(p) + d_; }`  

| 参数 | 说明 |
|------|------|
| `p` | 测试点 |

**返回**: normal · p + d  


**绝对点到平面距离**  
`[[nodiscard]] T distance(const Point3D& p) const { return std::abs(signed_distance(p)); }`  

| 参数 | 说明 |
|------|------|
| `p` | 测试点 |

**返回**: |signed_distance(p)|  


**点在平面上的正交投影**  
`[[nodiscard]] Point3D project(const Point3D& p) const {`  

| 参数 | 说明 |
|------|------|
| `p` | 原点 |

**返回**: 投影点（满足在平面上且连线垂直于平面）  



### `point.h`

**核心模块提供 VDE 引擎的几何操作 API：**  


**通用 N 维点类型（重新导出，便于 core 模块使用）**  
`template <typename T, size_t Dim>`  


**通用 N 维向量类型（重新导出）**  
`template <typename T, size_t Dim>`  



### `polygon.h`

**二维平面多边形**  
> 内部假设简单多边形（无自交），非简单多边形的行为未定义  
> 所有几何计算基于（假设的）XY 平面  


**从顶点列表构造多边形**  
`explicit Polygon2D(std::vector<Point2D> vertices) : vertices_(std::move(vertices)) {}`  

| 参数 | 说明 |
|------|------|
| `vertices` | 顶点序列（逆时针或顺时针均可） |


**有向面积（Shoelace 公式）**  
`[[nodiscard]] double signed_area() const`  

**返回**: 有向面积  


**绝对面积**  
`[[nodiscard]] double area() const { return std::abs(signed_area()); }`  

**返回**: |signed_area()|  


**周长（各边长之和）**  
`[[nodiscard]] double perimeter() const`  

**返回**: 总边长  


**面积加权质心**  
`[[nodiscard]] Point2D centroid() const`  

**返回**: 质心坐标  


**二维轴对齐包围盒**  
`[[nodiscard]] AABB<double> bounding_box() const`  

**返回**: 包围盒  


**点包含测试（射线法）**  
`[[nodiscard]] bool contains(const Point2D& p) const`  

| 参数 | 说明 |
|------|------|
| `p` | 测试点 |

**返回**: true 若点在多边形内部或边界上  
> 边界上的点也返回 true  


**多边形是否为逆时针方向**  
`[[nodiscard]] bool is_ccw() const { return signed_area() > 0; }`  

**返回**: signed_area() > 0  


**Douglas-Peucker 简化**  
`[[nodiscard]] Polygon2D simplify(double tolerance) const`  

| 参数 | 说明 |
|------|------|
| `tolerance` | 允许的最大偏差 |

**返回**: 简化后的新多边形  

**参见**: `triangulate`  


**耳切法三角剖分（Ear Clipping）**  
`[[nodiscard]] std::vector<std::array<int, 3>> triangulate() const`  

**返回**: 三角形列表，每个元素为 {i, j, k} 表示顶点索引  
> 时间复杂度 O(n²)，适用于顶点数 < 1000 的多边形  

**参见**: `simplify`  


**Andrew's Monotone Chain 二维凸包**  
`static Polygon2D convex_hull_2d(const std::vector<Point2D>& points)`  

| 参数 | 说明 |
|------|------|
| `points` | 输入点集 |

**返回**: 凸包多边形（CCW，不含共线中间点）  

**参见**: `convex_hull_2d`  



### `transform.h`

**三维仿射变换类型**  
`using Transform3D = Eigen::Transform<double, 3, Eigen::Affine>`  


**创建平移变换**  
`inline Transform3D translate(const Vector3D& v) {`  

| 参数 | 说明 |
|------|------|
| `v` | 平移向量 |

**返回**: 平移变换矩阵  


**创建平移变换（分量形式）**  
`inline Transform3D translate(double x, double y, double z) {`  

| 参数 | 说明 |
|------|------|
| `x` | X 方向位移 |
| `y` | Y 方向位移 |
| `z` | Z 方向位移 |

**返回**: 平移变换矩阵  


**创建旋转变换（轴-角表示）**  
`inline Transform3D rotate(const Vector3D& axis, double angle_rad) {`  

| 参数 | 说明 |
|------|------|
| `axis` | 旋转轴（自动归一化） |
| `angle_rad` | 旋转角度（弧度） |

**返回**: 旋转变换矩阵  


**绕 X 轴旋转**  
`inline Transform3D rotate_x(double rad) { return rotate(Vector3D::UnitX(), rad); }`  

| 参数 | 说明 |
|------|------|
| `rad` | 旋转角度（弧度） |

**返回**: 旋转变换矩阵  


**绕 Y 轴旋转**  
`inline Transform3D rotate_y(double rad) { return rotate(Vector3D::UnitY(), rad); }`  

| 参数 | 说明 |
|------|------|
| `rad` | 旋转角度（弧度） |

**返回**: 旋转变换矩阵  


**绕 Z 轴旋转**  
`inline Transform3D rotate_z(double rad) { return rotate(Vector3D::UnitZ(), rad); }`  

| 参数 | 说明 |
|------|------|
| `rad` | 旋转角度（弧度） |

**返回**: 旋转变换矩阵  


**创建非均匀缩放变换**  
`inline Transform3D scale(double sx, double sy, double sz) {`  

| 参数 | 说明 |
|------|------|
| `sx` | X 方向缩放因子 |
| `sy` | Y 方向缩放因子 |
| `sz` | Z 方向缩放因子 |

**返回**: 缩放变换矩阵  
> 非均匀缩放可能导致法线方向不准确；使用场景中应考虑法线变换 = (M^{-1})^T  


**创建均匀缩放变换**  
`inline Transform3D scale(double s) { return scale(s, s, s); }`  

| 参数 | 说明 |
|------|------|
| `s` | 各方向统一的缩放因子 |

**返回**: 缩放变换矩阵  



### `triangle.h`

**三维三角形**  
`template <typename T>`  


**从三个顶点构造三角形**  
`Triangle(const Point3D& v0, const Point3D& v1, const Point3D& v2)`  

| 参数 | 说明 |
|------|------|
| `v0` | 第一个顶点 |
| `v1` | 第二个顶点 |
| `v2` | 第三个顶点 |


**获取第 i 个顶点**  
`[[nodiscard]] const Point3D& v(int i) const { return v_[i]; }`  

| 参数 | 说明 |
|------|------|
| `i` | 顶点索引（0, 1, 2） |

**返回**: 顶点引用  


**三角形单位法向量**  
`[[nodiscard]] Vector3D normal() const {`  

**返回**: 单位法向量  
> 若三角形退化（面积为零），返回零向量  


**三角形面积**  
`[[nodiscard]] T area() const {`  

**返回**: 0.5 * ||(v1 - v0) × (v2 - v0)||  


**三角形质心（几何中心）**  
`[[nodiscard]] Point3D centroid() const {`  

**返回**: (v0 + v1 + v2) / 3  


**重心坐标包含测试**  
`[[nodiscard]] bool contains(const Point3D& p) const {`  

| 参数 | 说明 |
|------|------|
| `p` | 测试点（三维空间中的任意点） |

**返回**: true 若投影点在三角形内部或边界上  
> 该测试等效于三维点在三角形上的包含测试（先投影再测试）  



### `voronoi.h`

**Voronoi 单元格**  
`struct VoronoiCell {`  


**单元格边界顶点（按逆时针顺序排列）**  
`std::vector<Point2D> vertices`  


**单元格边界边**  
`std::vector<std::array<int, 2>> edges`  


**二维 Voronoi 图生成（通过 Delaunay 对偶图）**  
`std::vector<VoronoiCell> voronoi_2d(const std::vector<Point2D>& points)`  

| 参数 | 说明 |
|------|------|
| `points` | 输入点集（站点） |

**返回**: 每个站点对应的 VoronoiCell 列表（顺序与输入一致）  
> 对于凸包边界上的站点，对应的 Voronoi 单元格无界，顶点不完全闭合  
> 内部使用 Delaunay 三角剖分作为中间步骤  



## 曲线曲面 (`vde::curves`)


### `bezier_curve.h`

**任意阶 Bézier 曲线**  


**构造 Bézier 曲线**  
`explicit BezierCurve(std::vector<Point3D> control_points)`  

| 参数 | 说明 |
|------|------|
| `control_points` | 控制点序列，点数 = degree + 1，最少 2 个 |
> 控制点数量决定了曲线阶次；点数越多，曲线越灵活但计算越昂贵  


**在参数 t 处求值曲线点**  
`[[nodiscard]] Point3D evaluate(double t) const`  

| 参数 | 说明 |
|------|------|
| `t` | 参数值，范围 [0, 1] |

**返回**: 曲线上对应 t 的点坐标  
> 使用 de Casteljau 递推算法，O(n²) 复杂度  


**在参数 t 处求导数**  
`[[nodiscard]] Vector3D derivative(double t, int order = 1) const`  

| 参数 | 说明 |
|------|------|
| `t` | 参数值，范围 [0, 1] |
| `order` | 导数阶数，1 = 一阶（切向量），2 = 二阶（曲率相关） |

**返回**: 导数向量  
> 高阶导数通过降阶 Bézier 曲线计算：  


**曲线阶次**  
`[[nodiscard]] int degree() const { return static_cast<int>(cp_.size()) - 1; }`  

**返回**: 阶次 = 控制点数 - 1  


**参数定义域**  
`[[nodiscard]] std::pair<double, double> domain() const { return {0.0, 1.0}; }`  

**返回**: 固定为 [0, 1]  


**控制点访问**  
`[[nodiscard]] const std::vector<Point3D>& control_points() const { return cp_; }`  

**返回**: 控制点向量的只读引用  


**在 t 处将曲线一分为二**  
`[[nodiscard]] std::pair<BezierCurve, BezierCurve> split(double t) const`  

| 参数 | 说明 |
|------|------|
| `t` | 分割参数，范围 [0, 1] |

**返回**: 左段 + 右段两条 Bézier 曲线  
> 使用 de Casteljau 分割算法，分割点为三角阵的对角线  


**升阶操作**  
`[[nodiscard]] BezierCurve degree_elevate(int times = 1) const`  

| 参数 | 说明 |
|------|------|
| `times` | 升阶次数，≥ 1 |

**返回**: 升阶后的 Bézier 曲线（控制点数增加 times，形状不变）  
> 通过反复应用公式 P_i' = i/(n+1) P_{i-1} + (1 - i/(n+1)) P_i  

**参见**: `split`  



### `bezier_surface.h`

**Bézier 张量积曲面**  


**构造 Bézier 曲面**  
`BezierSurface(std::vector<std::vector<Point3D>> control_grid)`  

| 参数 | 说明 |
|------|------|
| `control_grid` | 控制点网格，grid[i][j] 对应 u 方向第 i 个、v 方向第 j 个控制点 |
> grid 必须矩整（所有行等长）；grid.size() = degree_u+1, grid[0].size() = degree_v+1  


**求曲面点 S(u,v)**  
`[[nodiscard]] Point3D evaluate(double u, double v) const`  

| 参数 | 说明 |
|------|------|
| `u` | u 参数，范围 [0, 1] |
| `v` | v 参数，范围 [0, 1] |

**返回**: 曲面上对应 (u,v) 的 3D 坐标  
> 张量积求值：先按 v 方向对每行做 de Casteljau，再沿 u 方向对结果做一次  


**u 方向偏导数 ∂S/∂u**  
`[[nodiscard]] Vector3D derivative_u(double u, double v) const`  

| 参数 | 说明 |
|------|------|
| `u` | u 参数 |
| `v` | v 参数 |

**返回**: u 方向切向量  
> 通过降阶 Bézier 曲线计算：对 v 求值后沿 u 求导  


**v 方向偏导数 ∂S/∂v**  
`[[nodiscard]] Vector3D derivative_v(double u, double v) const`  

| 参数 | 说明 |
|------|------|
| `u` | u 参数 |
| `v` | v 参数 |

**返回**: v 方向切向量  


**单位法向量 N(u,v) = (∂S/∂u × ∂S/∂v) / |…|**  
`[[nodiscard]] Vector3D normal(double u, double v) const`  

| 参数 | 说明 |
|------|------|
| `u` | u 参数 |
| `v` | v 参数 |

**返回**: 归一化法向量（指向曲面的特选侧）  
> 当两个偏导数平行时返回零向量（奇异点）  


**u 向阶次**  
`[[nodiscard]] int degree_u() const { return static_cast<int>(cp_.size()) - 1; }`  

**返回**: u 方向阶次（控制点行数 - 1）  


**v 向阶次**  
`[[nodiscard]] int degree_v() const { return static_cast<int>(cp_[0].size()) - 1; }`  

**返回**: v 方向阶次（控制点列数 - 1）  


**一维 de Casteljau 求值（内部辅助）**  
`[[nodiscard]] Point3D de_casteljau(double t, const std::vector<Point3D>& pts) const`  

| 参数 | 说明 |
|------|------|
| `t` | 参数 |
| `pts` | 一维控制点序列 |

**返回**: 求值结果  



### `bspline_curve.h`

**B 样条曲线（非有理、均匀/非均匀节点）**  


**构造 B 样条曲线**  
`BSplineCurve(std::vector<Point3D> control_points,`  

| 参数 | 说明 |
|------|------|
| `control_points` | n+1 个控制点 |
| `knots` | 节点向量，必须为非递减序列 |
| `degree` | 阶次 p |
> 节点数量 = 控制点数 + 阶次 + 1；clamped 端点多重度为 p+1  


**在参数 t 处求值曲线点**  
`[[nodiscard]] Point3D evaluate(double t) const`  

| 参数 | 说明 |
|------|------|
| `t` | 参数值，必须在 domain() 范围内 |

**返回**: 曲线上对应 t 的点坐标  
> 使用 de Boor（Cox-de Boor）递推算法  


**在参数 t 处求导数**  
`[[nodiscard]] Vector3D derivative(double t, int order = 1) const`  

| 参数 | 说明 |
|------|------|
| `t` | 参数值 |
| `order` | 导数阶数，1 = 一切向量 |

**返回**: 导数向量  
> B 样条导数公式：  


**曲线阶次**  
`[[nodiscard]] int degree() const { return degree_; }`  

**返回**: 阶次 p  


**参数定义域**  
`[[nodiscard]] std::pair<double, double> domain() const`  

**返回**: 有效参数范围 [knots[p], knots[n+1]]  


**控制点访问**  
`[[nodiscard]] const std::vector<Point3D>& control_points() const { return cp_; }`  

**返回**: 控制点数组只读引用  


**节点向量访问**  
`[[nodiscard]] const std::vector<double>& knots() const { return knots_; }`  

**返回**: 节点向量只读引用  


**查找 t 所在的节点区间**  
`[[nodiscard]] int find_span(double t) const`  

| 参数 | 说明 |
|------|------|
| `t` | 参数值 |

**返回**: 节点区间索引 i 满足 knots[i] ≤ t < knots[i+1]  
> 使用二分查找，O(log n)；求值和基函数的前置步骤  


**在 t 处求非零基函数值**  
`[[nodiscard]] std::vector<double> basis_functions(double t, int span = -1) const`  

| 参数 | 说明 |
|------|------|
| `t` | 参数值 |
| `span` | 节点区间索引，-1 表示自动查找 |

**返回**: N_{span-p}(t), ..., N_{span}(t) 共 p+1 个值  
> 仅返回 p+1 个非零基函数；用于端点求值及插值  

**参见**: `find_span`  


**在 t 处求非零基函数的一阶导数**  
`[[nodiscard]] std::vector<double> basis_derivatives(double t, int span = -1) const`  

| 参数 | 说明 |
|------|------|
| `t` | 参数值 |
| `span` | 节点区间索引，-1 表示自动查找 |

**返回**: dN_{span-p}/du, ..., dN_{span}/du 共 p+1 个值  
> B 样条基函数导数递推：  

**参见**: `basis_functions`  



### `bspline_surface.h`

**B 样条张量积曲面（非有理）**  


**构造 B 样条曲面**  
`BSplineSurface(std::vector<std::vector<Point3D>> control_grid,`  

| 参数 | 说明 |
|------|------|
| `control_grid` | (nu+1)×(nv+1) 控制点网格 |
| `knots_u` | u 向节点向量，长度 = nu + pu + 1 |
| `knots_v` | v 向节点向量，长度 = nv + pv + 1 |
| `degree_u` | u 向阶次 pu |
| `degree_v` | v 向阶次 pv |


**求曲面点 S(u,v)**  
`[[nodiscard]] Point3D evaluate(double u, double v) const`  

| 参数 | 说明 |
|------|------|
| `u` | u 参数 |
| `v` | v 参数 |

**返回**: 曲面上的 3D 点  
> 张量积分解：先行后列（或先列后行）做两次 B 样条求值  


**u 向偏导数 ∂S/∂u**  
`[[nodiscard]] Vector3D derivative_u(double u, double v) const`  

| 参数 | 说明 |
|------|------|
| `u` | u 参数 |
| `v` | v 参数 |

**返回**: u 向切向量  


**v 向偏导数 ∂S/∂v**  
`[[nodiscard]] Vector3D derivative_v(double u, double v) const`  

| 参数 | 说明 |
|------|------|
| `u` | u 参数 |
| `v` | v 参数 |

**返回**: v 向切向量  


**单位法向量**  
`[[nodiscard]] Vector3D normal(double u, double v) const`  

| 参数 | 说明 |
|------|------|
| `u` | u 参数 |
| `v` | v 参数 |

**返回**: N(u,v) = (∂S/∂u × ∂S/∂v) / |…|  


**u 向阶次**  
`[[nodiscard]] int degree_u() const { return degree_u_; }`  

**返回**: pu  


**v 向阶次**  
`[[nodiscard]] int degree_v() const { return degree_v_; }`  

**返回**: pv  


**u 向节点向量**  
`[[nodiscard]] const std::vector<double>& knots_u() const { return knots_u_; }`  

**返回**: 只读引用  


**v 向节点向量**  
`[[nodiscard]] const std::vector<double>& knots_v() const { return knots_v_; }`  

**返回**: 只读引用  



### `nurbs_curve.h`

**NURBS 曲线（Non-Uniform Rational B-Spline）**  


**构造 NURBS 曲线**  
`NurbsCurve(std::vector<Point3D> control_points, std::vector<double> knots,`  

| 参数 | 说明 |
|------|------|
| `control_points` | 控制点序列 |
| `knots` | 节点向量 |
| `weights` | 权重序列，必须与 control_points 等长，各分量 > 0 |
| `degree` | 阶次 p |
> 所有权重必须 > 0 以保证分母不为零（非退化）  


**在参数 t 处求值**  
`[[nodiscard]] Point3D evaluate(double t) const`  

| 参数 | 说明 |
|------|------|
| `t` | 参数值 |

**返回**: 曲线上对应 t 的点坐标  
> 内部将 (w·P, w) 提升为齐次坐标的 B 样条，求值后投影回 3D  


**在参数 t 处求导数**  
`[[nodiscard]] Vector3D derivative(double t, int order = 1) const`  

| 参数 | 说明 |
|------|------|
| `t` | 参数值 |
| `order` | 导数阶数 |

**返回**: 导数向量  
> 有理导数公式：  


**曲线阶次**  
`[[nodiscard]] int degree() const { return degree_; }`  

**返回**: p  


**参数定义域**  
`[[nodiscard]] std::pair<double, double> domain() const`  

**返回**: [knots[degree], knots[n+1]]  


**控制点访问**  
`[[nodiscard]] const std::vector<Point3D>& control_points() const { return cp_; }`  

**返回**: 只读引用  


**权重访问**  
`[[nodiscard]] const std::vector<double>& weights() const { return weights_; }`  

**返回**: 只读引用  


**节点向量访问**  
`[[nodiscard]] const std::vector<double>& knots() const { return knots_; }`  

**返回**: 只读引用  



### `nurbs_operations.h`

**NURBS 曲面等距偏移**  
`[[nodiscard]] NurbsSurface offset_surface(const NurbsSurface& surf, double distance)`  

| 参数 | 说明 |
|------|------|
| `surf` | 输入 NURBS 曲面 |
| `distance` | 偏移距离（正值 = 沿法向外，负值 = 向内） |

**返回**: 偏移后的 NURBS 曲面（近似，阶次与原曲面相同）  
> 这是几何近似，非精确偏移。对于大变曲率曲面，增大控制点数量  
> 偏移可能导致自交（distance 超过曲面局部曲率半径时）  

**参见**: `trim_surface blend_surfaces`  


**NURBS 曲面参数域裁剪**  
`[[nodiscard]] NurbsSurface trim_surface(const NurbsSurface& surf,`  

| 参数 | 说明 |
|------|------|
| `surf` | 输入曲面 |
| `u_min,u_max` | 裁剪后的 u 参数范围（必须在原 domain 内） |
| `v_min,v_max` | 裁剪后的 v 参数范围（必须在原 domain 内） |

**返回**: 裁剪后的 NURBS 曲面  
> 裁剪是"软裁剪"——几何不变，仅改变参数化。如需"硬裁剪"  


**两 NURBS 曲面沿边界边的过渡面**  
`[[nodiscard]] NurbsSurface blend_surfaces(const NurbsSurface& surf_a,`  

| 参数 | 说明 |
|------|------|
| `surf_a` | 第一个曲面 |
| `surf_b` | 第二个曲面 |
| `edge_a` | surf_a 的边界边索引（0=u_min, 1=u_max, 2=v_min, 3=v_max） |
| `edge_b` | surf_b 的边界边索引（0=u_min, 1=u_max, 2=v_min, 3=v_max） |
| `blend_radius` | 过渡半径 |

**返回**: 过渡 NURBS 曲面（在偏移边界曲线间的直纹面）  
> 过渡面与原始曲面在边界处为 C⁰ 连续（非切线连续）  

**参见**: `ruled_surface`  


**两 NURBS 曲线间的直纹面**  
`[[nodiscard]] NurbsSurface ruled_surface(const NurbsCurve& curve_a,`  

| 参数 | 说明 |
|------|------|
| `curve_a` | 第一条曲线（v=0 边界） |
| `curve_b` | 第二条曲线（v=1 边界） |

**返回**: 直纹 NURBS 曲面  
> 两条曲线需有兼容的阶次和节点结构（内部执行升阶和节点精化）  

**参见**: `coons_patch blend_surfaces`  


**由四条边界曲线创建 Coons 曲面**  
`[[nodiscard]] NurbsSurface coons_patch(const NurbsCurve& curve_u0,`  

| 参数 | 说明 |
|------|------|
| `curve_u0` | v=0 处边界（沿 u 方向） |
| `curve_u1` | v=1 处边界（沿 u 方向） |
| `curve_v0` | u=0 处边界（沿 v 方向） |
| `curve_v1` | u=1 处边界（沿 v 方向） |

**返回**: Coons 曲面  
> 仅保证边界插值，不保证内部形状与设计意图一致  

**参见**: `ruled_surface`  


**沿方向向量拉伸 NURBS 曲线为曲面**  
`[[nodiscard]] NurbsSurface extrude_curve(const NurbsCurve& curve,`  

| 参数 | 说明 |
|------|------|
| `curve` | 截面曲线 |
| `direction` | 拉伸方向（内部归一化） |
| `length` | 拉伸长度 |

**返回**: 拉伸 NURBS 曲面  


**提取 NURBS 曲面的等参边界曲线**  
`[[nodiscard]] NurbsCurve extract_boundary_curve(const NurbsSurface& surf, int edge)`  

| 参数 | 说明 |
|------|------|
| `surf` | 输入曲面 |
| `edge` | 边界索引：0=u_min, 1=u_max, 2=v_min, 3=v_max |

**返回**: 指定边界上的 NURBS 曲线  
> 边界曲线继承原曲面该方向的阶次和节点向量  



### `nurbs_surface.h`

**NURBS 张量积曲面**  


**构造 NURBS 曲面**  
`NurbsSurface(std::vector<std::vector<Point3D>> control_grid,`  

| 参数 | 说明 |
|------|------|
| `control_grid` | 控制点网格 |
| `knots_u` | u 向节点向量 |
| `knots_v` | v 向节点向量 |
| `weights` | 权重网格，维度与 control_grid 一致，所有值 > 0 |
| `degree_u` | u 向阶次 |
| `degree_v` | v 向阶次 |


**求曲面点 S(u,v)**  
`[[nodiscard]] Point3D evaluate(double u, double v) const`  

| 参数 | 说明 |
|------|------|
| `u` | u 参数 |
| `v` | v 参数 |

**返回**: 曲面上对应 (u,v) 的 3D 点  


**u 向偏导数**  
`[[nodiscard]] Vector3D derivative_u(double u, double v) const`  

| 参数 | 说明 |
|------|------|
| `u` | u 参数 |
| `v` | v 参数 |

**返回**: ∂S/∂u  


**v 向偏导数**  
`[[nodiscard]] Vector3D derivative_v(double u, double v) const`  

| 参数 | 说明 |
|------|------|
| `u` | u 参数 |
| `v` | v 参数 |

**返回**: ∂S/∂v  


**单位法向量**  
`[[nodiscard]] Vector3D normal(double u, double v) const`  

| 参数 | 说明 |
|------|------|
| `u` | u 参数 |
| `v` | v 参数 |

**返回**: N(u,v) = normalize(∂S/∂u × ∂S/∂v)  


**u 向阶次**  
`[[nodiscard]] int degree_u() const { return degree_u_; }`  

**返回**: pu  


**v 向阶次**  
`[[nodiscard]] int degree_v() const { return degree_v_; }`  

**返回**: pv  


**控制点数量**  
`[[nodiscard]] std::array<int, 2> num_control_points() const {`  

**返回**: {nu+1, nv+1}，即网格的行数和列数  


**u 向节点向量**  
`[[nodiscard]] const std::vector<double>& knots_u() const { return knots_u_; }`  

**返回**: 只读引用  


**v 向节点向量**  
`[[nodiscard]] const std::vector<double>& knots_v() const { return knots_v_; }`  

**返回**: 只读引用  


**控制点网格访问**  
`[[nodiscard]] const std::vector<std::vector<Point3D>>& control_points() const { return cp_; }`  

**返回**: 只读引用  


**权重网格访问**  
`[[nodiscard]] const std::vector<std::vector<double>>& weights() const { return weights_; }`  

**返回**: 只读引用  


**由两条 NURBS 曲线创建直纹面**  
`static NurbsSurface ruled(const NurbsCurve& c1, const NurbsCurve& c2)`  

| 参数 | 说明 |
|------|------|
| `c1` | 起始曲线（v=0 边界） |
| `c2` | 终止曲线（v=1 边界） |

**返回**: 直纹 NURBS 曲面  
> 两条曲线需具有兼容的阶次和节点结构（内部做升阶和节点精化对齐）  

**参见**: `blend_surfaces ruled_surface`  


**由截面曲线旋转生成旋转曲面**  
`static NurbsSurface revolve(const NurbsCurve& profile, const Point3D& axis_origin,`  

| 参数 | 说明 |
|------|------|
| `profile` | 截面 NURBS 曲线 |
| `axis_origin` | 旋转轴上一点 |
| `axis_dir` | 旋转轴方向 |
| `angle_rad` | 旋转角度（弧度），≤ 2π |

**返回**: 旋转 NURBS 曲面  
> 使用 NURBS 表示圆弧的权重方案；完整旋转生成闭曲面  


**将 NURBS 曲面三角化**  
`[[nodiscard]] std::pair<std::vector<Point3D>, std::vector<std::array<int,3>>>`  

| 参数 | 说明 |
|------|------|
| `res_u` | u 方向采样分辨率 |
| `res_v` | v 方向采样分辨率 |

**返回**: {顶点数组, 三角形索引数组}，每个三角形为 {i0,i1,i2}  
> 生成 res_u×res_v 均匀网格，每个单元格拆为两个三角形  

**参见**: `tessellate`  



### `tessellation.h`

**均匀参数化曲面三角化**  
`std::pair<std::vector<Point3D>, std::vector<std::array<int, 3>>>`  

| 参数 | 说明 |
|------|------|
| `eval` |  曲面求值函数 eval(u,v) -> Point3D，参数 (u,v) ∈ [0,1]×[0,1] |
| `res_u` | u 方向子分段数（≥ 1） |
| `res_v` | v 方向子分段数（≥ 1） |

**返回**: {顶点数组, 三角形索引数组}，三角形为 {i0,i1,i2}  
> 总顶点数 = (res_u+1)×(res_v+1)，三角形数 = 2×res_u×res_v  

**参见**: `adaptive_tessellate`  


**自适应曲面三角化**  
`std::pair<std::vector<Point3D>, std::vector<std::array<int, 3>>>`  

| 参数 | 说明 |
|------|------|
| `eval` |       曲面求值函数 eval(u,v) -> Point3D |
| `normal_fn` |  单位法向函数 normal_fn(u,v) -> Vector3D |
| `min_res` |    初始每向子分段数（≥ 1），默认 2 |
| `max_depth` |  最大递归深度，限制总面数，默认 6 |
| `angle_threshold_deg` |  法向角度偏差阈值（度），默认 5.0 |

**返回**: {顶点数组, 三角形索引数组}  
> 最终面数上限约为 2·min_res²·4^max_depth（实际远小于此上限）  

**参见**: `tessellate`  



## 网格处理 (`vde::mesh`)


### `alpha_shapes.h`

**Alpha Shapes 点云表面重建**  
`TetrahedronMesh alpha_shapes(const std::vector<Point3D>& points, double alpha)`  

| 参数 | 说明 |
|------|------|
| `points` | 输入 3D 点云 |
| `alpha` | α 半径阈值，通常取平均点间距的 1~3 倍 |

**返回**: TetrahedronMesh 保留的四面体网格  

**参见**: `alpha_shapes_surface delaunay_3d`  


**将 Alpha Shapes 四面体网格的表面提取为三角形网格**  
`std::pair<std::vector<Point3D>, std::vector<std::array<int,3>>>`  

| 参数 | 说明 |
|------|------|
| `tet_mesh` | Alpha Shapes 输出的四面体网格 |

**返回**: {顶点数组, 三角形索引数组}  
> 表面三角形法向指向四面体外部（右手定则）  

**参见**: `alpha_shapes`  



### `cdt_2d.h`

**约束 Delaunay 三角化（CDT）**  
`DelaunayResult constrained_delaunay_2d(`  

| 参数 | 说明 |
|------|------|
| `points` | 输入 2D 点集 |
| `constraints` | 约束边列表，每项为 {起点索引, 终点索引} |

**返回**: DelaunayResult 含约束边的三角化结果  
> 约束边不能相交（否则行为未定义）；自相交约束需先分割交点  

**参见**: `delaunay_2d`  



### `delaunay_2d.h`

**2D Delaunay 三角化结果**  
`struct DelaunayResult {`  


**2D Delaunay 三角化（Bowyer-Watson 增量算法）**  
`DelaunayResult delaunay_2d(const std::vector<Point2D>& points)`  

| 参数 | 说明 |
|------|------|
| `points` | 输入 2D 点集（至少 3 个不共线点） |

**返回**: DelaunayResult 三角化结果  
> 时间复杂度：平均 O(n log n)，最坏 O(n²)  

**参见**: `constrained_delaunay_2d`  



### `delaunay_3d.h`

**四面体网格结构**  
`struct TetrahedronMesh {`  


**3D Delaunay 四面体化（Bowyer-Watson 增量算法）**  
`TetrahedronMesh delaunay_3d(const std::vector<Point3D>& points)`  

| 参数 | 说明 |
|------|------|
| `points` | 输入 3D 点集（至少 4 个不共面点） |

**返回**: TetrahedronMesh 四面体网格  
> 时间复杂度与 2D 类似：平均 O(n log n)，最坏 O(n²)  
> 输出包括内部和边界四面体；通过 alpha_shapes 可提取表面  

**参见**: `alpha_shapes`  



### `geodesic.h`

**热方法（Heat Method）计算测地距离**  
`std::vector<double> geodesic_distance(const HalfedgeMesh& mesh,`  

| 参数 | 说明 |
|------|------|
| `mesh` |     输入三角网格 |
| `sources` |  源顶点索引列表（距离为 0 的顶点） |
| `t` |        时间步长，< 0 时自动设为平均边长平方 |

**返回**: 每顶点到最近源点的测地距离  
> 要求网格为连通流形；时间步长 t 越小精度越高但数值越不稳定  



### `halfedge_mesh.h`

**半边数据结构元素**  
`struct Halfedge {`  


**面元素**  
`struct Face {`  


**半边数据结构三角网格**  


**清空所有数据**  
`void clear()`  


**添加顶点**  
`int add_vertex(const Point3D& p)`  

| 参数 | 说明 |
|------|------|
| `p` | 3D 坐标 |

**返回**: 新顶点的索引（0-based）  


**添加面**  
`int add_face(const std::vector<int>& vertex_indices)`  

| 参数 | 说明 |
|------|------|
| `vertex_indices` | 按逆时针顺序排列的顶点索引（至少 3 个） |

**返回**: 新面的索引，失败返回 -1  
> 自动创建/查找半边并设置对侧关系；面法向遵循右手定则  


**从三角形列表批量构建半边形网格**  
`void build_from_triangles(const std::vector<Point3D>& verts,`  

| 参数 | 说明 |
|------|------|
| `verts` | 顶点位置数组 |
| `tris` | 三角形索引数组，每个 {i0,i1,i2} |
> 等价于反复调用 add_vertex + add_face，但内部做批处理优化  


**顶点数量**  
`[[nodiscard]] size_t num_vertices() const { return vertices_.size(); }`  

**返回**: vertices_ 大小  


**面数量**  
`[[nodiscard]] size_t num_faces() const { return faces_.size(); }`  

**返回**: faces_ 大小  


**边数量**  
`[[nodiscard]] size_t num_edges() const { return halfedges_.size() / 2; }`  

**返回**: halfedges_.size() / 2  


**访问顶点**  
`[[nodiscard]] const Point3D& vertex(size_t idx) const { return vertices_[idx]; }`  

| 参数 | 说明 |
|------|------|
| `idx` | 顶点索引，0 ≤ idx < num_vertices() |

**返回**: 顶点坐标只读引用  


**访问面**  
`[[nodiscard]] const Face& face(size_t idx) const { return faces_[idx]; }`  

| 参数 | 说明 |
|------|------|
| `idx` | 面索引 |

**返回**: Face 只读引用  


**访问半边**  
`[[nodiscard]] const Halfedge& halfedge(size_t idx) const { return halfedges_[idx]; }`  

| 参数 | 说明 |
|------|------|
| `idx` | 半边索引 |

**返回**: Halfedge 只读引用  


**更新顶点位置**  
`void set_vertex(size_t idx, const Point3D& p) { vertices_[idx] = p; normals_dirty_ = true; }`  

| 参数 | 说明 |
|------|------|
| `idx` | 顶点索引 |
| `p` | 新坐标 |
> 标记法向缓存为脏，下次查询时重新计算  


**获取面的所有顶点索引（按环绕顺序）**  
`[[nodiscard]] std::vector<int> face_vertices(int fi) const`  

| 参数 | 说明 |
|------|------|
| `fi` | 面索引 |

**返回**: 顶点索引序列  


**获取顶点的邻面索引环**  
`[[nodiscard]] std::vector<int> vertex_faces(int vi) const`  

| 参数 | 说明 |
|------|------|
| `vi` | 顶点索引 |

**返回**: 所有以 vi 为顶点的面索引  


**是否为边界半边**  
`[[nodiscard]] bool is_boundary_edge(int hei) const { return halfedges_[hei].face_index < 0; }`  

| 参数 | 说明 |
|------|------|
| `hei` | 半边索引 |

**返回**: 没有所属面时为 true  


**是否为边界顶点**  
`[[nodiscard]] bool is_boundary_vertex(int vi) const`  

| 参数 | 说明 |
|------|------|
| `vi` | 顶点索引 |

**返回**: 邻接任何边界半边时为 true  


**面法向（几何法向，非归一化？由实现决定）**  
`[[nodiscard]] Vector3D face_normal(int fi) const`  

| 参数 | 说明 |
|------|------|
| `fi` | 面索引 |

**返回**: (v1-v0)×(v2-v0) 归一化结果  


**顶点法向（邻面法向的面积加权平均）**  
`[[nodiscard]] Vector3D vertex_normal(int vi) const`  

| 参数 | 说明 |
|------|------|
| `vi` | 顶点索引 |

**返回**: 归一化顶点法向  


**重新计算所有面法向和顶点法向**  
`void update_normals()`  
> 修改顶点位置后自动标记脏位，调用此方法触发重新计算  


**网格包围盒**  
`[[nodiscard]] AABB3D bounds() const`  

**返回**: AABB3D 轴对齐包围盒  


**面迭代器范围（支持 for-range）**  


**顶点单邻环迭代器**  


**获取所有面范围（range-based for 支持）**  
`[[nodiscard]] FaceRange faces_range() const`  

**返回**: FaceRange 对象  


**获取顶点的 1-ring 邻域迭代器**  
`[[nodiscard]] VertexOneRing vertex_one_ring(int vi) const`  

| 参数 | 说明 |
|------|------|
| `vi` | 顶点索引 |

**返回**: VertexOneRing 对象  


**查找或创建半边 (v0→v1)**  
`int find_or_create_edge(int v0, int v1)`  

| 参数 | 说明 |
|------|------|
| `v0` | 起点顶点索引 |
| `v1` | 终点顶点索引 |

**返回**: 半边索引  



### `marching_cubes.h`

**Marching Cubes 输出网格**  
`struct MCMesh {`  


**Marching Cubes 等值面提取**  
`MCMesh marching_cubes(const std::function<double(double,double,double)>& f,`  

| 参数 | 说明 |
|------|------|
| `f` |           标量场函数 f(x,y,z) → double |
| `iso_level` |   等值面值（默认 0） |
| `bmin` |        包围盒最小角 |
| `bmax` |        包围盒最大角 |
| `resolution` |  每轴采样分辨率（≥ 1），总网格 = resolution³ 个立方体 |

**返回**: MCMesh 三角形网格  
> 使用经典的 256 查表法（Lorensen & Cline 1987）  

**参见**: `sdf_sphere sdf_box`  


**SDF 球体函数**  
`inline double sdf_sphere(double x, double y, double z, double cx, double cy, double cz, double r) {`  

| 参数 | 说明 |
|------|------|
| `x,y,z` | 采样点坐标 |
| `cx,cy,cz` | 球心坐标 |
| `r` | 半径 |

**返回**: 有符号距离：内部 < 0，表面 = 0，外部 > 0  


**SDF 立方体函数（轴对齐，中心在原点）**  
`inline double sdf_box(double x, double y, double z, double hx, double hy, double hz) {`  

| 参数 | 说明 |
|------|------|
| `x,y,z` | 采样点坐标 |
| `hx,hy,hz` | 半边长 |

**返回**: 有符号距离  


**SDF 平滑并集（Smooth Union）**  

| 参数 | 说明 |
|------|------|
| `d1,d2` | 两个 SDF 值 |
| `k` | 平滑宽度（> 0），值越大过渡越平滑 |

**返回**: 混合后的 SDF 值  


**SDF 平滑差集（Smooth Subtraction）**  
`inline double sdf_smooth_subtraction(double d1, double d2, double k) {`  

| 参数 | 说明 |
|------|------|
| `d1,d2` | 两个 SDF 值 |
| `k` | 平滑宽度（> 0） |

**返回**: 混合后的 SDF 值  



### `mesh_boolean.h`

**布尔运算类型（CSG 组合）**  
`enum class BooleanOp {`  


**三角网格布尔运算**  
`HalfedgeMesh mesh_boolean(const HalfedgeMesh& a, const HalfedgeMesh& b, BooleanOp op)`  

| 参数 | 说明 |
|------|------|
| `a` |  第一个三角网格（必须为封闭流形） |
| `b` |  第二个三角网格（必须为封闭流形） |
| `op` | 布尔运算类型 |

**返回**: 结果三角网格  
> 要求输入网格为封闭流形（watertight），否则分类不可靠  



### `mesh_curvature.h`

**离散曲率计算结果**  
`struct CurvatureResult {`  


**离散曲率计算（Cotan 公式，Meyer et al. 2003）**  
`CurvatureResult compute_curvature(const HalfedgeMesh& mesh)`  

| 参数 | 说明 |
|------|------|
| `mesh` | 输入三角网格 |

**返回**: CurvatureResult 每顶点曲率  
> 要求网格为流形；边界顶点曲率使用近似公式  



### `mesh_parameterize.h`

**Tutte 参数化（调和参数化）**  
`[[nodiscard]] std::vector<Point2D> tutte_parameterization(const HalfedgeMesh& mesh)`  

| 参数 | 说明 |
|------|------|
| `mesh` | 输入三角网格（需含边界） |

**返回**: 每顶点 UV 坐标（Point2D），顺序与 mesh 顶点一致  
> 网格必须有边界（开网格）；闭曲面需先切割为拓扑圆盘  

**参见**: `lscm_parameterization`  


**LSCM（Least Squares Conformal Maps）参数化**  
`[[nodiscard]] std::vector<Point2D> lscm_parameterization(const HalfedgeMesh& mesh)`  

| 参数 | 说明 |
|------|------|
| `mesh` | 输入三角网格 |

**返回**: 每顶点 UV 坐标（Point2D）  
> 简化实现，不包含完整 Lévy 论文中所有的退化处理  

**参见**: `tutte_parameterization`  



### `mesh_quality.h`

**三角网格质量指标**  
`struct MeshQuality {`  


**评估三角网格质量**  
`MeshQuality evaluate_mesh_quality(const HalfedgeMesh& mesh)`  

| 参数 | 说明 |
|------|------|
| `mesh` | 输入三角网格 |

**返回**: MeshQuality 质量指标汇总  


**四面体网格质量指标**  
`struct TetQuality {`  


**评估三角网格作为四面体边界的质量**  
`TetQuality evaluate_tet_quality(const HalfedgeMesh& mesh)`  

| 参数 | 说明 |
|------|------|
| `mesh` | 封闭三角网格（volume boundary） |

**返回**: TetQuality 四面体质量指标  
> 这不是真正的四面体网格质量评估——仅用于表面网格的代理指标  


**单元类型枚举**  
`enum class ElementType {`  


**通用单元质量指标**  
`struct ElemQuality {`  


**按单元类型分派的网格质量评估**  
`ElemQuality evaluate_element_quality(const HalfedgeMesh& mesh, ElementType type)`  

| 参数 | 说明 |
|------|------|
| `mesh` | 输入网格 |
| `type` | 单元类型 |

**返回**: ElemQuality 质量指标  
> 目前仅 Tri 和 Tet 完整实现；Quad / Hex 返回 stub（全零）  


**详细质量报告**  
`struct QualityReport {`  


**生成三角网格的完整质量报告**  
`QualityReport mesh_quality_report(const HalfedgeMesh& mesh)`  

| 参数 | 说明 |
|------|------|
| `mesh` | 输入三角网格 |

**返回**: QualityReport 完整质量报告  


**生成四面体网格的完整质量报告**  
`QualityReport mesh_quality_report_tet(const HalfedgeMesh& mesh)`  

| 参数 | 说明 |
|------|------|
| `mesh` | 封闭三角网格 |

**返回**: QualityReport 完整质量报告  


**三角形归一化 Jacobian**  
`double tri_scaled_jacobian(const Point3D& a, const Point3D& b, const Point3D& c)`  

| 参数 | 说明 |
|------|------|
| `a,b,c` | 三角形三个顶点 |

**返回**: 归一化 Jacobian [-1, 1]  


**四面体归一化 Jacobian**  
`double tet_scaled_jacobian(const Point3D& a, const Point3D& b,`  

| 参数 | 说明 |
|------|------|
| `a,b,c,d` | 四面体四个顶点 |

**返回**: 归一化 Jacobian [0, 1]  



### `mesh_repair.h`

**网格修复选项**  
`struct RepairOptions {`  


**自动网格修复**  
`HalfedgeMesh repair_mesh(const HalfedgeMesh& mesh, const RepairOptions& opts = {})`  

| 参数 | 说明 |
|------|------|
| `mesh` | 输入网格（可能有缺陷） |
| `opts` | 修复选项（默认全部启用） |

**返回**: 修复后的网格  
> 修复为启发式算法，不保证 100% 成功；孔洞过大或非流形边可能仍有残留问题  



### `mesh_simplify.h`

**网格简化选项**  
`struct SimplifyOptions {`  


**QEM（Quadric Error Metrics）网格简化**  
`HalfedgeMesh simplify_mesh(const HalfedgeMesh& mesh, const SimplifyOptions& opts = {})`  

| 参数 | 说明 |
|------|------|
| `mesh` | 输入三角网格 |
| `opts` | 简化选项 |

**返回**: 简化后的网格  
> preserve_boundary 模式下，边界边通过惩罚项（大代价）被保护  



### `mesh_smooth.h`

**网格光顺方法**  
`enum class SmoothMethod {`  


**网格光顺参数**  
`struct SmoothOptions {`  


**网格光顺（通用分发器）**  
`HalfedgeMesh smooth_mesh(const HalfedgeMesh& mesh, const SmoothOptions& opts = {})`  

| 参数 | 说明 |
|------|------|
| `mesh` | 输入三角网格 |
| `opts` | 光顺选项 |

**返回**: 光顺后的网格（顶点位置更新，拓扑不变）  


**标准拉普拉斯光顺**  
`HalfedgeMesh smooth_laplacian(const HalfedgeMesh& mesh, int iterations, double lambda)`  

| 参数 | 说明 |
|------|------|
| `mesh` | 输入网格 |
| `iterations` | 迭代次数 |
| `lambda` | 步长系数 (0, 1] |

**返回**: 光顺后的网格  
> 迭代过多会导致网格坍塌；对于体积关键的应用优先选 Taubin 或 HC  

**参见**: `smooth_taubin smooth_hc_laplacian`  


**Taubin λ|μ 光顺（体积保持）**  
`HalfedgeMesh smooth_taubin(const HalfedgeMesh& mesh, int iterations, double lambda, double mu)`  

| 参数 | 说明 |
|------|------|
| `mesh` | 输入网格 |
| `iterations` | 完整 λ/μ 循环次数 |
| `lambda` | 正步系数 (0, 1] |
| `mu` | 负步系数，需满足 mu < 0 且 |mu| > lambda |

**返回**: 光顺后的网格  
> 典型值：λ = 0.5, μ = -0.53；|mu| 过大可能导致不稳定振荡  


**HC 拉普拉斯光顺（Humphrey's Classes）**  
`HalfedgeMesh smooth_hc_laplacian(const HalfedgeMesh& mesh, const SmoothOptions& opts = {})`  

| 参数 | 说明 |
|------|------|
| `mesh` | 输入网格 |
| `opts` | 光顺选项（使用 hc_alpha 和 hc_beta 字段） |

**返回**: 光顺后的网格  


**双边网格滤波**  
`HalfedgeMesh smooth_bilateral(const HalfedgeMesh& mesh, const SmoothOptions& opts = {})`  

| 参数 | 说明 |
|------|------|
| `mesh` | 输入网格 |
| `opts` | 光顺选项（使用 bilateral_ 前缀字段） |

**返回**: 光顺后的网格  



## 空间索引 (`vde::spatial`)


### `bvh.h`

**包围盒层次结构 (Bounding Volume Hierarchy)**  


**BVH 构建分裂策略**  
`enum class BVHSplitStrategy {`  


**< 按最长轴中点分裂**  
`Equal,   /**< 按数量均等分裂 */`  


**< 按数量均等分裂**  
`SAH      /**< Surface Area Heuristic — 最小化射线击中概率期望 */`  


**< Surface Area Heuristic — 最小化射线击中概率期望**  
`}`  


**BVH 构建选项**  
`struct BVHBuildOptions {`  


**< 分裂策略**  
`int leaf_size = 4;     /**< 叶节点最大图元数 */`  


**< 叶节点最大图元数**  
`int max_depth = 64;    /**< 树的最大深度 */`  


**< 树的最大深度**  
`}`  


**包围盒层次结构 — 三角形网格加速结构**  

**参见**: `SpatialIndex, Octree, KDTree, RTree`  


**构造 BVH 并指定构建选项**  
`explicit BVH(const BVHBuildOptions& opts = {}) : opts_(opts) {}`  

| 参数 | 说明 |
|------|------|
| `opts` | 构建选项（分裂策略、叶节点大小、最大深度） |


**清除已有数据并重建 BVH**  
`void build(const std::vector<Triangle3D>& tris) override`  

| 参数 | 说明 |
|------|------|
| `tris` | 三角形数组 |


**插入单个三角形**  
`void insert(const Triangle3D& tri) override`  

| 参数 | 说明 |
|------|------|
| `tri` | 要插入的三角形 |


**删除三角形**  
`bool remove(const Triangle3D& tri) override`  

| 参数 | 说明 |
|------|------|
| `tri` | 要删除的三角形 |

**返回**: 删除成功返回 true  


**AABB 范围查询**  
`std::vector<Triangle3D> query_range(const AABB3D& range) const override`  

| 参数 | 说明 |
|------|------|
| `range` | 查询包围盒 |

**返回**: 与 range 相交的三角形列表  


**K 近邻查询**  
`std::vector<Triangle3D> query_knn(const Point3D& point, size_t k) const override`  

| 参数 | 说明 |
|------|------|
| `point` | 查询点 |
| `k` | 返回数量 |

**返回**: 最近的 k 个三角形  


**射线查询：返回所有命中的三角形**  
`std::vector<Triangle3D> query_ray(const Ray3Dd& ray) const override`  

| 参数 | 说明 |
|------|------|
| `ray` | 查询射线 |

**返回**: 按命中顺序排列的三角形列表  


**清空 BVH 树和所有三角形**  
`void clear() override`  


**三角形数量**  
`size_t size() const override { return primitives_.size(); }`  

**返回**: 当前索引的三角形总数  


**射线最近命中查询结果**  
`struct HitResult {`  


**< 沿射线的参数 t**  
`Triangle3D tri;    /**< 命中的三角形 */`  


**< 命中的三角形**  
`Point3D point;     /**< 命中点的世界坐标 = origin + t * dir */`  


**< 命中点的世界坐标 = origin + t * dir**  
`}`  


**射线最近命中查询**  
`std::optional<HitResult> query_ray_nearest(const Ray3Dd& ray) const`  

| 参数 | 说明 |
|------|------|
| `ray` | 查询射线 |

**返回**: 最近命中结果（若无命中则返回空）  
> 比 query_ray() 更高效，仅返回最近命中  


**BVH 节点**  
`struct Node {`  


**< 节点的包围盒（所有子节点/图元的并集）**  
`int left = -1;          /**< 左子节点索引，叶节点为 -1 */`  


**< 左子节点索引，叶节点为 -1**  
`int right = -1;         /**< 右子节点索引，叶节点为 -1 */`  


**< 右子节点索引，叶节点为 -1**  
`int first_prim = 0;     /**< 叶节点第一个图元的索引 */`  


**< 叶节点第一个图元的索引**  
`int prim_count = 0;     /**< 叶节点图元数量 */`  


**< 叶节点图元数量**  
`/** @brief 判断是否为叶节点 */`  


**判断是否为叶节点**  
`bool leaf() const { return left < 0; }`  


**< 节点数组（根节点为 nodes_[0]）**  
`std::vector<Triangle3D> primitives_;    /**< 图元数组 */`  


**< 图元数组**  
`BVHBuildOptions opts_;                  /**< 构建选项 */`  


**< 构建选项**  
`/**`  


**递归构建 BVH 子树**  
`void build_recursive(int node, int first, int count, int depth)`  

| 参数 | 说明 |
|------|------|
| `node` | 当前节点索引 |
| `first` | 图元范围的起始索引 |
| `count` | 图元数量 |
| `depth` | 当前递归深度 |


**计算 SAH 分裂代价**  
`double sah_cost(int n_left, int n_right, const AABB3D& left, const AABB3D& right) const`  

| 参数 | 说明 |
|------|------|
| `n_left` | 左子树图元数 |
| `n_right` | 右子树图元数 |
| `left` | 左子树包围盒 |
| `right` | 右子树包围盒 |

**返回**: SAH 代价估值  



### `kd_tree.h`

**k-d 树 (K-Dimensional Tree) 空间划分结构**  


**k-d 树空间索引**  
`template <typename T>`  
> k-d 树在维度约 2~6 时效率最佳。三维场景中，  

**参见**: `SpatialIndex, BVH, Octree`  


**批量构建 k-d 树**  
`void build(const std::vector<T>& items) override`  

| 参数 | 说明 |
|------|------|
| `items` | 待索引的对象数组 |


**插入单个对象**  
`void insert(const T& item) override`  

| 参数 | 说明 |
|------|------|
| `item` | 待插入的空间对象 |


**删除对象**  
`bool remove(const T& item) override`  

| 参数 | 说明 |
|------|------|
| `item` | 待删除的空间对象 |

**返回**: 删除成功返回 true  


**范围查询**  
`std::vector<T> query_range(const AABB3D& range) const override`  

| 参数 | 说明 |
|------|------|
| `range` | 查询包围盒 |

**返回**: 与 range 相交的对象列表  


**K 近邻查询**  
`std::vector<T> query_knn(const Point3D& point, size_t k) const override`  

| 参数 | 说明 |
|------|------|
| `point` | 查询点 |
| `k` | 返回数量 |

**返回**: 最近的 k 个对象  


**射线查询**  
`std::vector<T> query_ray(const Ray3Dd& ray) const override`  

| 参数 | 说明 |
|------|------|
| `ray` | 查询射线 |

**返回**: 与射线相交的对象列表  


**清空 k-d 树**  
`void clear() override`  


**对象数量**  
`size_t size() const override { return items_.size(); }`  

**返回**: 当前索引的对象总数  


**k-d 树节点**  
`struct Node {`  


**< 节点包围盒**  
`int item_idx = -1;   /**< 叶节点对应的对象索引（-1 表示内部节点） */`  


**< 叶节点对应的对象索引（-1 表示内部节点）**  
`int split_axis = 0;  /**< 分裂轴：0=x, 1=y, 2=z */`  


**< 分裂轴：0=x, 1=y, 2=z**  
`int left = -1;       /**< 左子节点索引 */`  


**< 左子节点索引**  
`int right = -1;      /**< 右子节点索引 */`  


**< 右子节点索引**  
`}`  


**< 对象数组**  
`std::vector<Node> nodes_;         /**< 节点数组 */`  


**< 节点数组**  
`int root_ = -1;                   /**< 根节点索引 */`  


**< 根节点索引**  
`/**`  


**获取对象代表位置（用于空间排序）**  
`static Point3D get_position(const T& item)`  

| 参数 | 说明 |
|------|------|
| `item` | 空间对象 |

**返回**: 对象的三维代表点  


**获取对象的轴对齐包围盒**  
`static AABB3D get_aabb(const T& item)`  

| 参数 | 说明 |
|------|------|
| `item` | 空间对象 |

**返回**: 包围盒  


**判断对象是否与射线相交**  
`static bool ray_hits_item(const T& item, const Ray3Dd& ray)`  

| 参数 | 说明 |
|------|------|
| `item` | 空间对象 |
| `ray` | 查询射线 |

**返回**: 相交返回 true  


**递归构建 k-d 树**  
`int build_recursive(int start, int end)`  

| 参数 | 说明 |
|------|------|
| `start` | items_ 中当前范围起始索引 |
| `end` | items_ 中当前范围结束索引 |

**返回**: 新节点的索引  


**递归范围查询**  
`void query_range_recursive(int node_idx, const AABB3D& range,`  

| 参数 | 说明 |
|------|------|
| `node_idx` | 当前节点索引 |
| `range` | 查询包围盒 |
| `result` | 累积结果 |


**递归射线查询**  
`void query_ray_recursive(int node_idx, const Ray3Dd& ray,`  

| 参数 | 说明 |
|------|------|
| `node_idx` | 当前节点索引 |
| `ray` | 查询射线 |
| `result` | 累积结果 |



### `octree.h`

**八叉树 (Octree) 空间划分结构**  


**八叉树空间索引**  
`template <typename T>`  
> 适用于体积数据、粒子系统、空间哈希等场景。  

**参见**: `SpatialIndex, BVH, KDTree`  


**构造八叉树**  
`explicit Octree(int max_depth = 8, int max_items = 16)`  

| 参数 | 说明 |
|------|------|
| `max_depth` | 最大递归深度（默认 8，对应 256³ 分辨率） |
| `max_items` | 节点剖分前可容纳的最大对象数（默认 16） |


**批量构建八叉树**  
`void build(const std::vector<T>& items) override`  

| 参数 | 说明 |
|------|------|
| `items` | 待索引的对象数组 |


**增量插入对象**  
`void insert(const T& item) override`  

| 参数 | 说明 |
|------|------|
| `item` | 待插入的空间对象 |


**删除对象**  
`bool remove(const T& item) override`  

| 参数 | 说明 |
|------|------|
| `item` | 待删除的空间对象 |

**返回**: 删除成功返回 true；对象不存在返回 false  


**范围查询**  
`std::vector<T> query_range(const AABB3D& range) const override`  

| 参数 | 说明 |
|------|------|
| `range` | 查询包围盒 |

**返回**: 与 range 相交的对象列表  


**K 近邻查询**  
`std::vector<T> query_knn(const Point3D& point, size_t k) const override`  

| 参数 | 说明 |
|------|------|
| `point` | 查询点 |
| `k` | 返回数量 |

**返回**: 最近的 k 个对象  


**射线查询**  
`std::vector<T> query_ray(const Ray3Dd& ray) const override`  

| 参数 | 说明 |
|------|------|
| `ray` | 查询射线 |

**返回**: 按命中顺序排列的相交对象列表  


**清空八叉树**  
`void clear() override`  


**当前索引中的对象数量**  
`size_t size() const override`  

**返回**: 对象总数  


**递归插入对象到指定节点**  
`void insert_recursive(int node_idx, const T& item, int depth)`  

| 参数 | 说明 |
|------|------|
| `node_idx` | 目标节点索引 |
| `item` | 待插入的对象 |
| `depth` | 当前递归深度 |


**递归剖分节点**  
`void subdivide_recursive(int node_idx, int depth)`  

| 参数 | 说明 |
|------|------|
| `node_idx` | 当前节点索引 |
| `depth` | 当前深度 |


**递归范围查询**  
`void query_range_recursive(int node_idx, const AABB3D& range,`  

| 参数 | 说明 |
|------|------|
| `node_idx` | 当前节点索引 |
| `range` | 查询包围盒 |
| `result` | 累积结果 |


**递归射线查询**  
`void query_ray_recursive(int node_idx, const Ray3Dd& ray,`  

| 参数 | 说明 |
|------|------|
| `node_idx` | 当前节点索引 |
| `ray` | 查询射线 |
| `result` | 累积结果 |


**获取对象空间位置（用于剖分分配）**  
`static Point3D get_position(const T& item)`  

| 参数 | 说明 |
|------|------|
| `item` | 空间对象 |

**返回**: 对象的代表点  


**< 八叉树内部数据**  
`int max_depth_;    /**< 最大递归深度 */`  


**< 最大递归深度**  
`int max_items_;    /**< 节点剖分阈值 */`  


**< 节点剖分阈值**  
`}`  



### `r_tree.h`

**R 树 (R-Tree) 动态空间索引**  


**R 树节点**  
`template <typename T>`  


**< 节点包围盒（子节点/对象 MBR 的并集）**  
`bool is_leaf = true;               /**< 是否为叶节点 */`  


**< 是否为叶节点**  
`std::vector<size_t> children;      /**< 内部节点：子节点索引列表 */`  


**< 内部节点：子节点索引列表**  
`std::vector<size_t> item_indices;  /**< 叶节点：对象索引列表 */`  


**< 叶节点：对象索引列表**  
`size_t parent = static_cast<size_t>(-1);  /**< 父节点索引 */`  


**< 父节点索引**  
`}`  


**R 树动态空间索引**  
`template <typename T>`  
> R 树在动态场景（如编辑中的几何体）中比 BVH 更合适。  

**参见**: `SpatialIndex, BVH, RStarTree`  


**批量构建 R 树**  
`void build(const std::vector<T>& items) override`  

| 参数 | 说明 |
|------|------|
| `items` | 待索引的对象数组 |


**增量插入对象**  
`void insert(const T& item) override`  

| 参数 | 说明 |
|------|------|
| `item` | 待插入的空间对象 |


**删除对象**  
`bool remove(const T& item) override`  

| 参数 | 说明 |
|------|------|
| `item` | 待删除的空间对象 |

**返回**: 删除成功返回 true  


**范围查询**  
`std::vector<T> query_range(const AABB3D& range) const override`  

| 参数 | 说明 |
|------|------|
| `range` | 查询包围盒 |

**返回**: 与 range 相交的对象列表  


**K 近邻查询**  
`std::vector<T> query_knn(const Point3D& point, size_t k) const override`  

| 参数 | 说明 |
|------|------|
| `point` | 查询点 |
| `k` | 返回数量 |

**返回**: 最近的 k 个对象  


**射线查询**  
`std::vector<T> query_ray(const Ray3Dd& ray) const override`  

| 参数 | 说明 |
|------|------|
| `ray` | 查询射线 |

**返回**: 与射线相交的对象列表  


**清空 R 树**  
`void clear() override`  


**对象数量**  
`size_t size() const override { return count_; }`  

**返回**: 当前索引的对象总数  


**R 树节点总数**  
`size_t node_count() const { return nodes_.size(); }`  

**返回**: 内部节点 + 叶节点数量  


**递归范围查询**  
`void query_range_recursive(size_t node_idx, const AABB3D& range,`  

| 参数 | 说明 |
|------|------|
| `node_idx` | 当前节点索引 |
| `range` | 查询包围盒 |
| `result` | 累积结果 |


**< 对象数组**  
`std::vector<AABB3D> item_bounds_;    /**< 对象包围盒数组 */`  


**< 对象包围盒数组**  
`std::vector<RTreeNode<T>> nodes_;    /**< R 树节点数组 */`  


**< R 树节点数组**  
`size_t root_idx_ = 0;               /**< 根节点索引 */`  


**< 根节点索引**  
`size_t count_ = 0;                   /**< 对象计数 */`  


**< 对象计数**  
`}`  



### `spatial_index.h`

**空间索引抽象基类**  


**空间索引抽象基类**  
`template <typename T>`  
> 本类为纯虚接口，不可直接实例化  


**批量构建索引**  
`virtual void build(const std::vector<T>& items) = 0`  

| 参数 | 说明 |
|------|------|
| `items` | 待索引的对象数组 |


**插入单个对象**  
`virtual void insert(const T& item) = 0`  

| 参数 | 说明 |
|------|------|
| `item` | 待插入的空间对象 |


**删除单个对象**  
`virtual bool remove(const T& item) = 0`  

| 参数 | 说明 |
|------|------|
| `item` | 待删除的空间对象 |

**返回**: true 删除成功；false 对象不存在  


**范围查询：返回与 AABB 相交的所有对象**  
`virtual std::vector<T> query_range(const AABB3D& range) const = 0`  

| 参数 | 说明 |
|------|------|
| `range` | 查询的轴对齐包围盒 |

**返回**: 与 range 相交的对象列表  


**K 近邻查询：返回距 point 最近的 k 个对象**  
`virtual std::vector<T> query_knn(const Point3D& point, size_t k) const = 0`  

| 参数 | 说明 |
|------|------|
| `point` | 查询点 |
| `k` | 需要返回的对象数量 |

**返回**: 按距离升序排列的 k 个最近对象  


**射线查询：返回与射线相交的所有对象**  
`virtual std::vector<T> query_ray(const Ray3Dd& ray) const = 0`  

| 参数 | 说明 |
|------|------|
| `ray` | 查询射线 |

**返回**: 按命中距离升序排列的相交对象列表  


**清空索引中所有数据**  
`virtual void clear() = 0`  


**当前索引中的对象数量**  
`virtual size_t size() const = 0`  

**返回**: 对象计数  



## 布尔运算 (`vde::boolean`)


### `boolean_2d.h`

**二维多边形布尔运算**  


**布尔运算类型**  
`enum class BooleanOp {`  


**< 并集 A ∪ B**  
`Intersection,  /**< 交集 A ∩ B */`  


**< 交集 A ∩ B**  
`Difference,    /**< 差集 A − B */`  


**< 差集 A − B**  
`SymDiff        /**< 对称差 (A − B) ∪ (B − A) */`  


**< 对称差 (A − B) ∪ (B − A)**  
`}`  


**二维多边形布尔运算**  
`std::vector<Polygon2D> boolean_2d(const Polygon2D& a, const Polygon2D& b, BooleanOp op)`  

| 参数 | 说明 |
|------|------|
| `a` | 第一个多边形 |
| `b` | 第二个多边形 |
| `op` | 布尔操作类型 |

**返回**: 结果多边形列表（可能有多个分离的组件）  
> 当前版本优化了凸多边形路径。对于带孔洞或自交的  

**参见**: `BooleanOp, mesh_boolean, polygon_offset`  



### `boolean_mesh.h`

**三维网格布尔运算**  


**网格并集 A ∪ B**  
`HalfedgeMesh mesh_union(const HalfedgeMesh& a, const HalfedgeMesh& b)`  

| 参数 | 说明 |
|------|------|
| `a` | 网格 A |
| `b` | 网格 B |

**返回**: A ∪ B 的合并网格  

**参见**: `mesh_intersection, mesh_difference, is_point_inside_mesh`  


**网格交集 A ∩ B**  
`HalfedgeMesh mesh_intersection(const HalfedgeMesh& a, const HalfedgeMesh& b)`  

| 参数 | 说明 |
|------|------|
| `a` | 网格 A |
| `b` | 网格 B |

**返回**: A ∩ B 的交集网格  
> 结果体积为两网格公共区域  

**参见**: `mesh_union, mesh_difference`  


**网格差集 A − B**  
`HalfedgeMesh mesh_difference(const HalfedgeMesh& a, const HalfedgeMesh& b)`  

| 参数 | 说明 |
|------|------|
| `a` | 网格 A |
| `b` | 网格 B |

**返回**: A − B 的差集网格  
> 结果中来自 B 的面片会被翻转法线以保持内-外一致性  

**参见**: `mesh_union, mesh_intersection, mesh_sym_diff`  


**网格对称差 (A − B) ∪ (B − A)**  
`HalfedgeMesh mesh_sym_diff(const HalfedgeMesh& a, const HalfedgeMesh& b)`  

| 参数 | 说明 |
|------|------|
| `a` | 网格 A |
| `b` | 网格 B |

**返回**: 对称差网格  

**参见**: `mesh_difference, mesh_union`  


**用网格 B 裁剪网格 A**  
`HalfedgeMesh clip_mesh(const HalfedgeMesh& a, const HalfedgeMesh& b,`  

| 参数 | 说明 |
|------|------|
| `a` | 待裁剪网格 |
| `b` | 裁剪体网格 |
| `invert_b` | 若为 true，将 B 的内外判定取反（裁剪外部） |

**返回**: 裁剪后的网格（仅包含 A 的面片）  

**参见**: `mesh_difference, is_point_inside_mesh`  


**翻转网格所有面片的法线方向**  
`HalfedgeMesh invert_mesh(const HalfedgeMesh& m)`  

| 参数 | 说明 |
|------|------|
| `m` | 原始网格 |

**返回**: 法线翻转后的网格  

**参见**: `mesh_difference`  


**合并两个网格**  
`HalfedgeMesh merge_meshes(const HalfedgeMesh& a, const HalfedgeMesh& b)`  

| 参数 | 说明 |
|------|------|
| `a` | 网格 A |
| `b` | 网格 B |

**返回**: 包含 A 和 B 全部顶点和面片的合并网格  
> 不处理重叠区域；仅做纯几何拼接  

**参见**: `mesh_union（做布尔合并）`  


**网格布尔运算统一接口**  
`HalfedgeMesh mesh_boolean(const HalfedgeMesh& a, const HalfedgeMesh& b, BooleanOp op)`  

| 参数 | 说明 |
|------|------|
| `a` | 网格 A |
| `b` | 网格 B |
| `op` | 布尔操作类型 |

**返回**: 结果网格  

**参见**: `BooleanOp, mesh_union, mesh_intersection, mesh_difference, mesh_sym_diff`  


**判断三维点是否在封闭网格内部**  
`bool is_point_inside_mesh(const core::Point3D& p, const HalfedgeMesh& mesh)`  

| 参数 | 说明 |
|------|------|
| `p` | 待判定点 |
| `mesh` | 封闭网格 |

**返回**: 点在网格内部返回 true  
> 网格必须是封闭（水密）的，否则结果不可靠。  

**参见**: `clip_mesh, mesh_difference`  



### `polygon_offset.h`

**多边形等距偏移 (Polygon Offset / Inset)**  


**多边形等距偏移**  
`std::vector<Polygon2D> polygon_offset(const Polygon2D& poly, double distance)`  

| 参数 | 说明 |
|------|------|
| `poly` | 原始多边形 |
| `distance` | 偏移距离（正=外扩，负=内缩） |

**返回**: 偏移后的多边形列表（内缩或自交可能产生多个碎片）  
> 使用直骨架近似而非精确圆弧偏移，转角处为斜角连接。  

**参见**: `boolean_2d`  



## 碰撞检测 (`vde::collision`)


### `gjk.h`

**GJK (Gilbert–Johnson–Keerthi) 碰撞检测算法**  


**支撑函数类型**  
`using SupportFunc = std::function<Point3D(const Vector3D&)>`  


**GJK 完整检测结果**  
`struct GJKResult {`  


**< 两凸体是否相交**  
`double distance;   /**< 最近距离（不相交时 >0，相交时为 0） */`  


**< 最近距离（不相交时 >0，相交时为 0）**  
`Point3D point_a;   /**< 形状 A 上的最近点 */`  


**< 形状 A 上的最近点**  
`Point3D point_b;   /**< 形状 B 上的最近点 */`  


**< 形状 B 上的最近点**  
`}`  


**GJK 相交检测（仅判断是否碰撞）**  
`bool gjk_intersect(const SupportFunc& shape_a, const SupportFunc& shape_b)`  

| 参数 | 说明 |
|------|------|
| `shape_a` | 形状 A 的支撑函数 |
| `shape_b` | 形状 B 的支撑函数 |

**返回**: 相交返回 true  

**参见**: `gjk_distance, gjk_full, SupportFunc`  


**GJK 最近距离查询**  
`double gjk_distance(const SupportFunc& shape_a, const SupportFunc& shape_b)`  

| 参数 | 说明 |
|------|------|
| `shape_a` | 形状 A 的支撑函数 |
| `shape_b` | 形状 B 的支撑函数 |

**返回**: 最近距离（相交时返回 0），始终 ≥ 0  

**参见**: `gjk_intersect, gjk_full`  


**GJK 完整检测：碰撞状态、距离、最近点对**  
`GJKResult gjk_full(const SupportFunc& shape_a, const SupportFunc& shape_b)`  

| 参数 | 说明 |
|------|------|
| `shape_a` | 形状 A 的支撑函数 |
| `shape_b` | 形状 B 的支撑函数 |

**返回**: GJKResult 包含碰撞状态、距离、最近点对  
> 对于连续碰撞检测 (CCD) 或需要分离向量的场景，  

**参见**: `gjk_intersect, gjk_distance`  



### `ray_intersect.h`

**射线求交工具集**  


**射线-三角形求交结果**  
`struct RayTriResult {`  


**< 沿射线的参数：hit_point = origin + t * dir**  
`double u, v;    /**< 三角形重心坐标：hit_point = (1−u−v)*v0 + u*v1 + v*v2 */`  


**< 三角形重心坐标：hit_point = (1−u−v)*v0 + u*v1 + v*v2**  
`Point3D point;  /**< 命中点的世界坐标 */`  


**< 命中点的世界坐标**  
`}`  


**射线-三角形求交（Möller-Trumbore 算法）**  
`std::optional<RayTriResult> ray_triangle_intersect(`  

| 参数 | 说明 |
|------|------|
| `origin` | 射线起点 |
| `dir` | 射线方向（需归一化以获得正确 t 值） |
| `tri` | 三角形 |

**返回**: 命中返回 RayTriResult；未命中返回空  

**参见**: `ray_mesh_intersect`  


**射线-三角形求交（Ray3Dd 重载）**  
`inline std::optional<RayTriResult> ray_triangle_intersect(`  

| 参数 | 说明 |
|------|------|
| `ray` | 射线 |
| `tri` | 三角形 |

**返回**: 命中返回 RayTriResult；未命中返回空  

**参见**: `ray_triangle_intersect(origin, dir, tri)`  


**射线-AABB 求交（slab 方法）**  
`bool ray_aabb_intersect(const Ray3Dd& ray, const AABB3D& box,`  

| 参数 | 说明 |
|------|------|
| `ray` | 射线 |
| `box` | 轴对齐包围盒 |
| `tmin_out` | [输出] 进入包围盒的参数 t |
| `tmax_out` | [输出] 离开包围盒的参数 t |

**返回**: 命中返回 true  
> 常用于 BVH 遍历节点的快速 rejection test  

**参见**: `ray_triangle_intersect`  


**射线-球体求交结果**  
`struct RaySphereResult {`  


**< 命中参数（通常取较小的 t）**  
`Point3D point;  /**< 命中点世界坐标 */`  


**< 命中点世界坐标**  
`}`  


**射线-球体求交（解析法）**  
`std::optional<RaySphereResult> ray_sphere_intersect(`  

| 参数 | 说明 |
|------|------|
| `origin` | 射线起点 |
| `dir` | 射线方向 |
| `center` | 球心 |
| `radius` | 球半径 |

**返回**: 命中返回 RaySphereResult（最近交点）；未命中返回空  

**参见**: `ray_sphere_intersect(ray, center, radius)`  


**射线-球体求交（Ray3Dd 重载）**  
`inline std::optional<RaySphereResult> ray_sphere_intersect(`  

| 参数 | 说明 |
|------|------|
| `ray` | 射线 |
| `center` | 球心 |
| `radius` | 球半径 |

**返回**: 命中返回 RaySphereResult；未命中返回空  


**射线-平面求交**  
`std::optional<double> ray_plane_intersect(`  

| 参数 | 说明 |
|------|------|
| `origin` | 射线起点 |
| `dir` | 射线方向 |
| `plane_point` | 平面上一点 |
| `plane_normal` | 平面法线（需归一化以获得正确 t） |

**返回**: 命中返回参数 t；未命中（平行或反向）返回空  


**射线-平面求交（Ray3Dd 重载）**  
`inline std::optional<double> ray_plane_intersect(`  

| 参数 | 说明 |
|------|------|
| `ray` | 射线 |
| `plane_point` | 平面上一点 |
| `plane_normal` | 平面法线 |

**返回**: 命中返回参数 t；未命中返回空  


**射线-网格求交（暴力遍历）**  
`std::optional<RayTriResult> ray_mesh_intersect(`  

| 参数 | 说明 |
|------|------|
| `origin` | 射线起点 |
| `dir` | 射线方向 |
| `triangles` | 三角形列表 |

**返回**: 最近命中结果；无命中返回空  
> 对于大型网格建议配合 BVH 使用：  

**参见**: `ray_tri_intersect.h, query_ray_nearest (BVH)`  


**射线-网格求交（Ray3Dd 重载）**  
`inline std::optional<RayTriResult> ray_mesh_intersect(`  

| 参数 | 说明 |
|------|------|
| `ray` | 射线 |
| `triangles` | 三角形列表 |

**返回**: 最近命中结果；无命中返回空  



### `sat.h`

**SAT (Separating Axis Theorem) 碰撞检测**  


**SAT 凸多面体相交检测**  
`bool sat_intersect(const std::vector<Point3D>& verts_a,`  

| 参数 | 说明 |
|------|------|
| `verts_a` | 多面体 A 的顶点数组 |
| `faces_a` | 多面体 A 的面索引数组（每个面为 {v0, v1, v2}） |
| `verts_b` | 多面体 B 的顶点数组 |
| `faces_b` | 多面体 B 的面索引数组 |

**返回**: 相交返回 true  
> 适用于任意凸多面体。对于胶囊/球等光滑形状，GJK 更合适。  

**参见**: `gjk_intersect, tri_tri_intersect`  



### `tri_intersect.h`

**三角形-三角形 / 三角形-AABB 相交检测**  


**三角形-三角形相交检测（布尔测试）**  
`bool tri_tri_intersect(const Triangle3D& t1, const Triangle3D& t2)`  

| 参数 | 说明 |
|------|------|
| `t1` | 三角形 1 |
| `t2` | 三角形 2 |

**返回**: 相交返回 true  

**参见**: `tri_tri_intersect_detailed, sat_intersect`  


**三角形-三角形相交线段**  
`struct TriTriIntersection {`  


**< 是否相交**  
`Point3D p0;       /**< 交点段起点 */`  


**< 交点段起点**  
`Point3D p1;       /**< 交点段终点 */`  


**< 交点段终点**  
`}`  


**三角形-三角形详细相交检测**  
`TriTriIntersection tri_tri_intersect_detailed(const Triangle3D& t1,`  

| 参数 | 说明 |
|------|------|
| `t1` | 三角形 1 |
| `t2` | 三角形 2 |

**返回**: TriTriIntersection：相交标志 + 交点段端点  
> 共面情况交集段可能退化为单点（p0 == p1）  

**参见**: `tri_tri_intersect`  


**三角形-AABB 快速相交测试**  
`bool tri_aabb_overlap(const Triangle3D& tri, const AABB3D& box)`  

| 参数 | 说明 |
|------|------|
| `tri` | 三角形 |
| `box` | 轴对齐包围盒 |

**返回**: 相交返回 true  
> AABB 碰撞比三角剖分后的三角-三角检测更高效，  

**参见**: `tri_tri_intersect, ray_aabb_intersect`  



## B-Rep建模 (`vde::brep`)


### `assembly.h`

**装配体节点**  
`struct AssemblyNode {`  


**装配体**  
`struct Assembly {`  



### `brep.h`

**边界表示（B-Rep）核心数据结构**  


**边曲线类型枚举**  
`enum class CurveType { Line, Circle, Bezier, BSpline, Nurbs }`  


**拓扑顶点**  
`struct TopoVertex {`  


**拓扑边**  
`struct TopoEdge {`  


**拓扑环（Loop）**  
`struct TopoLoop {`  


**拓扑面**  
`struct TopoFace {`  


**拓扑壳**  
`struct TopoShell {`  


**拓扑体**  
`struct TopoBody {`  


**B-Rep 模型**  

**参见**: `brep_validate.h 验证`, `modeling.h 高层建模 API`, `brep_boolean.h 布尔运算`  


**添加顶点**  
`int add_vertex(const Point3D& p)`  

| 参数 | 说明 |
|------|------|
| `p` | 顶点坐标 |

**返回**: 新顶点的 ID  


**添加直线边**  
`int add_edge(int v0, int v1)`  

| 参数 | 说明 |
|------|------|
| `v0` | 起点顶点 ID |
| `v1` | 终点顶点 ID |

**返回**: 新边的 ID  


**添加曲线边**  
`int add_edge(int v0, int v1, const curves::NurbsCurve& curve)`  

| 参数 | 说明 |
|------|------|
| `v0` | 起点顶点 ID |
| `v1` | 终点顶点 ID |
| `curve` | 边的几何曲线 |

**返回**: 新边的 ID  


**添加环**  
`int add_loop(const std::vector<int>& edges, bool outer = true)`  

| 参数 | 说明 |
|------|------|
| `edges` | 环中边的 ID 序列（顺序连接） |
| `outer` | true = 外环, false = 内环 |

**返回**: 新环的 ID  


**添加面**  
`int add_face(int surface_id, const std::vector<int>& loops)`  

| 参数 | 说明 |
|------|------|
| `surface_id` | 关联曲面 ID |
| `loops` | 环 ID 列表 |

**返回**: 新面的 ID  


**添加壳**  
`int add_shell(const std::vector<int>& faces, bool closed = true)`  

| 参数 | 说明 |
|------|------|
| `faces` | 面 ID 列表 |
| `closed` | 是否为封闭壳 |

**返回**: 新壳的 ID  


**添加体**  
`int add_body(const std::vector<int>& shells, const std::string& name = "")`  

| 参数 | 说明 |
|------|------|
| `shells` | 壳 ID 列表 |
| `name` | 体名称 |

**返回**: 新体的 ID  


**添加 NURBS 曲面**  
`int add_surface(const curves::NurbsSurface& surf)`  

| 参数 | 说明 |
|------|------|
| `surf` | NURBS 曲面定义 |

**返回**: 新曲面的 ID  


**顶点数量**  
`[[nodiscard]] size_t num_vertices() const { return vertices_.size(); }`  


**边数量**  
`[[nodiscard]] size_t num_edges() const { return edges_.size(); }`  


**面数量**  
`[[nodiscard]] size_t num_faces() const { return faces_.size(); }`  


**体数量**  
`[[nodiscard]] size_t num_bodies() const { return bodies_.size(); }`  


**曲面数量**  
`[[nodiscard]] size_t num_surfaces() const { return surfaces_.size(); }`  


**按数组索引访问顶点**  
`[[nodiscard]] const TopoVertex& vertex(int id) const { return vertices_[id]; }`  


**按唯一 ID 访问顶点（适用于边数据中的 ID 引用）**  
`[[nodiscard]] const TopoVertex& vertex_by_id(int id) const`  


**按数组索引访问边**  
`[[nodiscard]] const TopoEdge& edge(int id) const { return edges_[id]; }`  


**按数组索引访问面**  
`[[nodiscard]] const TopoFace& face(int id) const { return faces_[id]; }`  


**按数组索引访问曲面**  
`[[nodiscard]] const curves::NurbsSurface& surface(int id) const { return surfaces_[id]; }`  


**按唯一 ID 访问环**  
`[[nodiscard]] const TopoLoop& loop_by_id(int id) const`  


**获取所有环的只读引用**  
`[[nodiscard]] const std::vector<TopoLoop>& all_loops() const { return loops_; }`  


**计算模型的轴对齐包围盒**  
`[[nodiscard]] core::AABB3D bounds() const`  

**返回**: 包围盒（AABB）  


**检查模型有效性（快速版本）**  
`[[nodiscard]] bool is_valid() const`  

**返回**: true 如果模型通过基本检查  

**参见**: `validate() 完整验证（水密性、方向一致性等）`  


**将 B-Rep 模型 tessellate 为三角网格**  
`[[nodiscard]] mesh::HalfedgeMesh to_mesh(double deflection = 0.01) const`  

| 参数 | 说明 |
|------|------|
| `deflection` | 弦高误差（控制 tessellation 精度，默认 0.01） |

**返回**: HalfedgeMesh 三角网格  
> deflection 越小网格越精细，但三角形数量显著增加。  


**获取面的所有边**  
`[[nodiscard]] std::vector<int> face_edges(int face_id) const`  

| 参数 | 说明 |
|------|------|
| `face_id` | 面 ID |

**返回**: 边 ID 列表（去重）  


**获取边的所有相邻面**  
`[[nodiscard]] std::vector<int> edge_faces(int edge_id) const`  

| 参数 | 说明 |
|------|------|
| `edge_id` | 边 ID |

**返回**: 相邻面 ID 列表  


**获取顶点的所有相邻边**  
`[[nodiscard]] std::vector<int> vertex_edges(int vertex_id) const`  

| 参数 | 说明 |
|------|------|
| `vertex_id` | 顶点 ID |

**返回**: 相邻边 ID 列表  



### `brep_boolean.h`

**B-Rep 级别的布尔运算**  


**B-Rep 布尔并集: A ∪ B**  
`[[nodiscard]] BrepModel brep_union(const BrepModel& a, const BrepModel& b)`  

| 参数 | 说明 |
|------|------|
| `a` | 第一个 B-Rep 实体 |
| `b` | 第二个 B-Rep 实体 |

**返回**: 新的 B-Rep 实体（a ∪ b）  

**参见**: `brep_intersection 交集`, `brep_difference 差集`  


**B-Rep 布尔交集: A ∩ B**  
`[[nodiscard]] BrepModel brep_intersection(const BrepModel& a, const BrepModel& b)`  

| 参数 | 说明 |
|------|------|
| `a` | 第一个 B-Rep 实体 |
| `b` | 第二个 B-Rep 实体 |

**返回**: 新的 B-Rep 实体（a ∩ b）  

**参见**: `brep_union 并集`, `brep_difference 差集`  


**B-Rep 布尔差集: A \ B**  
`[[nodiscard]] BrepModel brep_difference(const BrepModel& a, const BrepModel& b)`  

| 参数 | 说明 |
|------|------|
| `a` | 被减实体 A |
| `b` | 减去实体 B |

**返回**: 新的 B-Rep 实体（a \ b）  

**参见**: `brep_union 并集`, `brep_intersection 交集`  



### `brep_validate.h`

**B-Rep 模型综合验证**  


**B-Rep 模型的综合验证结果**  
`struct ValidationResult {`  


**是否通过所有必要检查**  
`bool valid = true`  


**错误信息列表（导致 valid = false）**  
`std::vector<std::string> errors`  


**警告信息列表（不影响 valid）**  
`std::vector<std::string> warnings`  


**水密性比率：恰好有 2 个相邻面的边的比例（1.0 = 完美水密）**  
`double watertightness = 1.0`  


**无自交比率：不与其他面内部相交的面对比例（1.0 = 无自交）**  
`double self_intersection_free = 1.0`  


**最短边的长度（用于检测退化边）**  
`double min_edge_length = std::numeric_limits<double>::max()`  


**最长边的长度（用于检测超长边）**  
`double max_edge_length = 0.0`  


**非流形边数（相邻面 ≠ 2 的边）**  
`size_t non_manifold_edges = 0`  


**悬挂边数（无相邻面的边）**  
`size_t dangling_edges = 0`  


**方向不一致的面数**  
`size_t inconsistent_orientations = 0`  


**总边数**  
`size_t total_edges = 0`  


**总面数**  
`size_t total_faces = 0`  


**对 BrepModel 执行综合验证**  
`[[nodiscard]] ValidationResult validate(const BrepModel& body)`  

| 参数 | 说明 |
|------|------|
| `body` | 待验证的 B-Rep 模型 |

**返回**: ValidationResult 包含所有检查结果的详细报告  
> 自交检测是最昂贵的检查项（O(n²) 面对数），  

**参见**: `BrepModel::is_valid() 快速有效性检查（无详细报告）`  



### `iges_export.h`

**IGES 文件导出（版本 5.3）**  


**将 B-Rep 体导出为 IGES 格式字符串（版本 5.3）**  
`[[nodiscard]] std::string export_iges(const std::vector<BrepModel>& bodies)`  

| 参数 | 说明 |
|------|------|
| `bodies` | B-Rep 体列表 |

**返回**: IGES 5.3 格式字符串  

**参见**: `export_iges_file 直接写入文件`, `export_step STEP 格式导出`  


**将 B-Rep 体导出为 IGES 文件**  
`void export_iges_file(const std::string& filepath, const std::vector<BrepModel>& bodies)`  

| 参数 | 说明 |
|------|------|
| `filepath` | 输出文件路径（建议扩展名 .igs 或 .iges） |
| `bodies` | B-Rep 体列表 |

**参见**: `export_iges 获取字符串输出`  



### `iges_import.h`

**IGES 文件导入（ANSI Y14.26M）**  


**IGES 导入错误码**  
`enum class IgesError {`  


**从文件导入 IGES**  
`[[nodiscard]] std::vector<BrepModel> import_iges(const std::string& filepath)`  

| 参数 | 说明 |
|------|------|
| `filepath` | .igs 或 .iges 文件路径 |

**返回**: B-Rep 体列表  
> IGES 格式较为宽松，不同 CAD 系统的实现差异很大。  

**参见**: `import_iges_from_string 从字符串导入`, `iges_last_error 获取错误码`  


**从字符串导入 IGES（用于测试）**  
`[[nodiscard]] std::vector<BrepModel> import_iges_from_string(const std::string& data)`  

| 参数 | 说明 |
|------|------|
| `data` | IGES 文件完整内容（字符串形式） |

**返回**: B-Rep 体列表  

**参见**: `import_iges 从文件导入`  


**获取最近一次 IGES 导入的错误码**  
`[[nodiscard]] IgesError iges_last_error()`  

**返回**: IgesError 枚举值  

**参见**: `iges_last_error_message 获取可读描述`  


**获取最近一次 IGES 导入的可读错误描述**  
`[[nodiscard]] const std::string& iges_last_error_message()`  

**返回**: 错误描述字符串  

**参见**: `iges_last_error 获取枚举错误码`  



### `modeling.h`

**高层 B-Rep 建模 API**  


**沿方向挤出平面轮廓**  
`[[nodiscard]] BrepModel extrude(const curves::NurbsCurve& profile, const Vector3D& dir)`  

| 参数 | 说明 |
|------|------|
| `profile` | 轮廓曲线（必须位于一个平面内） |
| `dir` | 挤出方向向量（其长度决定挤出距离） |

**返回**: 挤出后的 B-Rep 实体  

**参见**: `revolve 旋转扫掠`, `sweep 沿任意路径扫掠`  


**绕轴旋转平面轮廓**  
`[[nodiscard]] BrepModel revolve(const curves::NurbsCurve& profile,`  

| 参数 | 说明 |
|------|------|
| `profile` | 轮廓曲线（通常位于轴的半平面中） |
| `axis_origin` | 旋转轴上的一个点 |
| `axis_dir` | 旋转轴方向（单位向量） |
| `angle_rad` | 旋转角度（弧度，默认 2π = 完整的旋转体） |

**返回**: 旋转后的 B-Rep 实体  

**参见**: `extrude 线性挤出`, `make_sphere 直接创建球体`  


**沿任意路径扫掠轮廓**  
`[[nodiscard]] BrepModel sweep(const curves::NurbsCurve& profile,`  

| 参数 | 说明 |
|------|------|
| `profile` | 截面轮廓（需位于路径起点的垂直平面内） |
| `path` | 扫掠路径曲线 |

**返回**: 扫掠后的 B-Rep 实体  
> 路径曲率过大处可能出现自交，需要控制路径的光滑性。  

**参见**: `extrude 直线挤出`, `revolve 旋转扫掠`  


**在两个或多个轮廓曲线之间放样**  
`[[nodiscard]] BrepModel loft(const std::vector<curves::NurbsCurve>& profiles)`  

| 参数 | 说明 |
|------|------|
| `profiles` | 轮廓曲线列表（至少 2 条） |

**返回**: 放样后的 B-Rep 实体  

**参见**: `extrude 单轮廓挤出`  


**创建立方体**  
`[[nodiscard]] BrepModel make_box(double w, double h, double d)`  

| 参数 | 说明 |
|------|------|
| `w` | 宽度（X 方向），必须 > 0 |
| `h` | 高度（Y 方向），必须 > 0 |
| `d` | 深度（Z 方向），必须 > 0 |

**返回**: 实心立方体 B-Rep  

**参见**: `make_cylinder 圆柱体`, `make_sphere 球体`  


**创建圆柱体**  
`[[nodiscard]] BrepModel make_cylinder(double radius, double height, int segments = 32)`  

| 参数 | 说明 |
|------|------|
| `radius` | 截面半径，必须 > 0 |
| `height` | 总高度，沿 Y 轴从 -h/2 到 +h/2 |
| `segments` | 截面分段数（边数，默认 32） |

**返回**: 实心圆柱体 B-Rep  
> segments 越大圆柱越光滑，但面和边数增加。  

**参见**: `make_box 立方体`, `make_sphere 球体`  


**创建球体**  
`[[nodiscard]] BrepModel make_sphere(double radius, int segments_u = 32, int segments_v = 16)`  

| 参数 | 说明 |
|------|------|
| `radius` | 球半径，必须 > 0 |
| `segments_u` | 经度方向分段数（默认 32） |
| `segments_v` | 纬度方向分段数（默认 16） |

**返回**: 实心球体 B-Rep  

**参见**: `make_cylinder 圆柱体`  


**对边做圆角处理**  
`[[nodiscard]] BrepModel fillet(const BrepModel& body, int edge_id, double radius)`  

| 参数 | 说明 |
|------|------|
| `body` | 输入实体 |
| `edge_id` | 要倒圆的边 ID |
| `radius` | 圆角半径，必须 > 0 |

**返回**: 圆角后的新实体  
> 圆角半径不能超过相邻面的最小宽度，否则会产生自交。  
> 只支持恒定半径圆角。变半径圆角尚未实现。  

**参见**: `chamfer 倒角`, `shell 抽壳`  


**对边做倒角**  
`[[nodiscard]] BrepModel chamfer(const BrepModel& body, int edge_id, double distance)`  

| 参数 | 说明 |
|------|------|
| `body` | 输入实体 |
| `edge_id` | 要倒角的边 ID |
| `distance` | 倒角距离（从原边沿两个面各偏移的距离） |

**返回**: 倒角后的新实体  

**参见**: `fillet 圆角`  


**抽壳（挖空实体）**  
`[[nodiscard]] BrepModel shell(const BrepModel& body, int face_id, double thickness)`  

| 参数 | 说明 |
|------|------|
| `body` | 输入实心实体 |
| `face_id` | 要移除的面 ID（形成开口），-1 表示封闭壳（不开口） |
| `thickness` | 壁厚（正值 = 向外偏移，负值 = 向内偏移） |

**返回**: 抽壳后的新实体  
> 壁厚不应超过实体最小尺寸的一半。  
> 当 face_id = -1 时，结果是一个封闭的壳（中空但没有开口）。  

**参见**: `fillet 圆角`  



### `step_export.h`

**STEP 文件导出（ISO 10303-214）**  


**将 B-Rep 体导出为 STEP AP214 字符串**  
`[[nodiscard]] std::string export_step(const std::vector<BrepModel>& bodies)`  

| 参数 | 说明 |
|------|------|
| `bodies` | B-Rep 体列表（每个体对应一个 PRODUCT） |

**返回**: STEP AP214 格式字符串  
> 输出包含所有必要的 ISO 10303-21 头部信息。  

**参见**: `export_step_file 直接写入文件`, `export_iges IGES 格式导出`  


**将 B-Rep 体导出为 STEP 文件**  
`void export_step_file(const std::string& filepath, const std::vector<BrepModel>& bodies)`  

| 参数 | 说明 |
|------|------|
| `filepath` | 输出文件路径（建议扩展名 .step 或 .stp） |
| `bodies` | B-Rep 体列表 |

**参见**: `export_step 获取字符串输出`  



### `step_import.h`

**STEP 文件导入（ISO 10303）**  


**STEP 导入错误码**  
`enum class StepError {`  


**从文件导入 STEP（AP203/AP214）**  
`[[nodiscard]] std::vector<BrepModel> import_step(const std::string& filepath)`  

| 参数 | 说明 |
|------|------|
| `filepath` | .step 或 .stp 文件路径 |

**返回**: B-Rep 体列表（每个文件中的 PRODUCT 一个）  
> 大型 STEP 文件（> 100 MB）可能需要数秒到数十秒进行解析。  

**参见**: `import_step_from_string 从内存字符串导入（测试用）`, `step_last_error 获取错误码`  


**从字符串导入 STEP（用于测试和嵌入式场景）**  
`[[nodiscard]] std::vector<BrepModel> import_step_from_string(const std::string& step_data)`  

| 参数 | 说明 |
|------|------|
| `step_data` | 完整的 STEP 文件内容（字符串形式） |

**返回**: B-Rep 体列表  

**参见**: `import_step 从文件导入`  


**获取最近一次 STEP 导入的错误码**  
`[[nodiscard]] StepError step_last_error()`  

**返回**: StepError 枚举值  

**参见**: `step_last_error_message 获取可读的错误描述`  


**获取最近一次 STEP 导入的可读错误描述**  
`[[nodiscard]] const std::string& step_last_error_message()`  

**返回**: 错误描述字符串（如 "Missing entity reference #42"）  

**参见**: `step_last_error 获取枚举错误码`  



## SDF隐式建模 (`vde::sdf`)


### `sdf_gradient.h`

**SDF 梯度计算（数值微分、解析梯度、链式法则）**  


**SDF 的空间梯度（中心差分近似）**  
`[[nodiscard]] inline Vector3D gradient(`  

| 参数 | 说明 |
|------|------|
| `f` | SDF 函数（接受 Point3D 参数） |
| `p` | 求值点 |
| `h` | 差分步长（默认 1e-6） |

**返回**: 梯度向量 ∇f(p)  
> 步长太小会导致舍入误差主导，太大导致截断误差主导。  
> 对于含不连续性的 SDF（如 sharp CSG），有限差分可能在边界产生错误梯度。  

**参见**: `evaluate_with_gradient 一次性获取值和梯度`  


**前向模梯度结果: SDF 值 + 梯度**  
`struct GradResult {`  


**同时计算 SDF 值和梯度的便捷函数**  
`[[nodiscard]] inline GradResult evaluate_with_gradient(`  

| 参数 | 说明 |
|------|------|
| `f` | SDF 函数 |
| `p` | 求值点 |
| `h` | 差分步长 |

**返回**: value + grad 结构  

**参见**: `gradient 仅计算梯度`  


**球体 SDF 对半径的参数梯度 ∂f/∂r**  
`[[nodiscard]] inline double sphere_radius_gradient(const Point3D& p, double radius, double h = 1e-6)`  

| 参数 | 说明 |
|------|------|
| `p` | 采样点 |
| `radius` | 球体半径 |
| `h` | 差分步长（默认 1e-6） |

**返回**: ∂f/∂radius  
> 对于球体，解析梯度为 -1（球面上），但此函数提供与实现无关的数值验证。  

**参见**: `sphere_param_grad 封装版本`  


**长方体 SDF 对各轴半尺寸的参数梯度 ∂f/∂extent[i]**  
`[[nodiscard]] inline double box_extent_gradient(const Point3D& p, const Point3D& extents,`  

| 参数 | 说明 |
|------|------|
| `p` | 采样点 |
| `extents` | 半边长 |
| `axis` | 轴索引: 0=x, 1=y, 2=z |
| `h` | 差分步长 |

**返回**: ∂f/∂extent[axis]  

**参见**: `box_param_grad 封装版本`  


**圆环 SDF 对主半径的参数梯度 ∂f/∂major_r**  
`[[nodiscard]] inline double torus_major_gradient(const Point3D& p, double major_r, double minor_r,`  

| 参数 | 说明 |
|------|------|
| `p` | 采样点 |
| `major_r` | 主半径 |
| `minor_r` | 副半径 |
| `h` | 差分步长 |

**返回**: 参数梯度  


**圆环 SDF 对副半径的参数梯度 ∂f/∂minor_r**  
`[[nodiscard]] inline double torus_minor_gradient(const Point3D& p, double major_r, double minor_r,`  

**返回**: 参数梯度  


**圆柱 SDF 对高度的参数梯度 ∂f/∂height**  
`[[nodiscard]] inline double cylinder_height_gradient(const Point3D& p, double radius, double height,`  

| 参数 | 说明 |
|------|------|
| `p` | 采样点 |
| `radius` | 圆柱半径 |
| `height` | 圆柱高度 |
| `h` | 差分步长 |

**返回**: 参数梯度  


**圆柱 SDF 对半径的参数梯度 ∂f/∂radius**  
`[[nodiscard]] inline double cylinder_radius_gradient(const Point3D& p, double radius, double height,`  

**返回**: 参数梯度  


**球体 SDF 的解析梯度**  
`[[nodiscard]] inline Vector3D sphere_gradient_analytic(const Point3D& p, double /*radius*/)`  

| 参数 | 说明 |
|------|------|
| `p` | 采样点 |
| `radius` | 球半径（当前未使用，保留以保持接口一致） |

**返回**: 解析梯度（单位向量）  
> 在表面上 (|p| = radius)，梯度即为外法向量。  


**长方体 SDF 的解析梯度**  
`[[nodiscard]] inline Vector3D box_gradient_analytic(const Point3D& p, const Point3D& half_extents)`  

| 参数 | 说明 |
|------|------|
| `p` | 采样点 |
| `half_extents` | 半边长 |

**返回**: 解析梯度  


**圆环 SDF 的解析梯度**  
`[[nodiscard]] inline Vector3D torus_gradient_analytic(const Point3D& p, double major_r, double minor_r)`  

| 参数 | 说明 |
|------|------|
| `p` | 采样点 |
| `major_r` | 主半径 |
| `minor_r` | 副半径 |

**返回**: 解析梯度  


**无限圆柱（沿 Y 轴）的解析梯度**  
`[[nodiscard]] inline Vector3D cylinder_gradient_analytic(const Point3D& p, double /*radius*/)`  

| 参数 | 说明 |
|------|------|
| `p` | 采样点 |
| `radius` | 圆柱半径（未使用，保留接口一致） |

**返回**: 解析梯度  


**平面的解析梯度**  
`[[nodiscard]] inline Vector3D plane_gradient_analytic(const Vector3D& normal)`  

| 参数 | 说明 |
|------|------|
| `normal` | 单位法向量 |

**返回**: 梯度（等于 normal）  
> 这是最简单的解析梯度，因为平面 SDF 是线性的。  


**胶囊体 SDF 的解析梯度**  
`[[nodiscard]] inline Vector3D capsule_gradient_analytic(const Point3D& p,`  

| 参数 | 说明 |
|------|------|
| `p` | 采样点 |
| `a` | 线段起点 |
| `b` | 线段终点 |
| `radius` | 扫掠球半径 |

**返回**: 解析梯度  


**并集操作后的梯度传递**  
`[[nodiscard]] inline Vector3D chain_union(const Vector3D& grad_a, const Vector3D& grad_b,`  

| 参数 | 说明 |
|------|------|
| `grad_a` | 子对象 A 的梯度 |
| `grad_b` | 子对象 B 的梯度 |
| `d1` | A 的 SDF 值 |
| `d2` | B 的 SDF 值 |

**返回**: 合并后的梯度  

**参见**: `chain_smooth_union 避免不连续的平滑版本`  


**交集操作后的梯度传递**  
`[[nodiscard]] inline Vector3D chain_intersection(const Vector3D& grad_a, const Vector3D& grad_b,`  

**返回**: 合并后的梯度  


**差集操作后的梯度传递**  
`[[nodiscard]] inline Vector3D chain_difference(const Vector3D& grad_a, const Vector3D& grad_b,`  

| 参数 | 说明 |
|------|------|
| `grad_a` | 子对象 A 的梯度 |
| `grad_b` | 子对象 B 的梯度 |
| `d1` | f_A |
| `d2` | f_B |

**返回**: 合并后的梯度  


**平滑并集操作的梯度传递（含完整链式法则）**  
`[[nodiscard]] inline Vector3D chain_smooth_union(const Vector3D& grad_a, const Vector3D& grad_b,`  

| 参数 | 说明 |
|------|------|
| `grad_a` | 子对象 A 的梯度 |
| `grad_b` | 子对象 B 的梯度 |
| `d1` | f_A |
| `d2` | f_B |
| `k` | 混合参数 |

**返回**: 平滑合并后的梯度  

**参见**: `op_smooth_union 对应的平滑并集 SDF 操作`, `chain_union 硬切换版本`  


**平移变换后的梯度传递（梯度不变）**  
`[[nodiscard]] inline GradResult chain_translate(const GradResult& child_result, const Point3D& /*offset*/)`  

| 参数 | 说明 |
|------|------|
| `child_result` | 变换空间中的子对象求值结果 |
| `offset` | 平移量（仅接口保留） |

**返回**: 相同梯度  


**绕 Y 轴旋转后的梯度传递**  
`[[nodiscard]] inline GradResult chain_rotate(const GradResult& child_result, double angle_rad)`  

| 参数 | 说明 |
|------|------|
| `child_result` | 旋转后坐标系中的子对象求值 |
| `angle_rad` | 旋转角度 |

**返回**: 世界坐标系的梯度  

**参见**: `op_rotate 对应的域变形操作`  


**非均匀缩放后的梯度传递**  
`[[nodiscard]] inline GradResult chain_scale(const GradResult& child_result, const Point3D& factors)`  

| 参数 | 说明 |
|------|------|
| `child_result` | 缩放后坐标系中的子对象求值 |
| `factors` | 缩放因子 |

**返回**: 世界坐标系的梯度  
> 缩放后梯度不再是单位长度，除非是均匀缩放。  


**扭曲变换后的梯度传递（含完整雅可比）**  
`[[nodiscard]] inline GradResult chain_twist(const GradResult& child_result,`  

| 参数 | 说明 |
|------|------|
| `child_result` | 扭曲空间中的子对象求值 |
| `amount` | 单位高度的旋转量 |
| `p` | 原始采样点 |

**返回**: 世界坐标系的梯度  

**参见**: `op_twist 对应的域变形操作`, `chain_rotate 不含 Y 依赖的简化旋转梯度传递`  


**周期重复后的梯度传递（梯度不变）**  
`[[nodiscard]] inline GradResult chain_repeat(const GradResult& child_result,`  

| 参数 | 说明 |
|------|------|
| `child_result` | 中心晶格内的子对象求值 |
| `cell` | 晶格尺寸（仅接口保留） |
| `p` | 原始采样点（仅接口保留） |

**返回**: 相同梯度  


**参数梯度结构体**  
`struct ParamGrad {`  

**参见**: `sphere_param_grad, box_param_grad, cylinder_param_grad`  


**球体所有参数的梯度（当前仅 radius 有意义）**  
`[[nodiscard]] inline ParamGrad sphere_param_grad(const Point3D& p, double radius, double h = 1e-6)`  

| 参数 | 说明 |
|------|------|
| `p` | 采样点 |
| `radius` | 球体半径 |
| `h` | 差分步长 |

**返回**: 参数梯度（仅 d_radius 非零）  

**参见**: `sphere_radius_gradient 底层数值差分`  


**长方体所有参数的梯度**  
`[[nodiscard]] inline ParamGrad box_param_grad(const Point3D& p, const Point3D& half_extents,`  

| 参数 | 说明 |
|------|------|
| `p` | 采样点 |
| `half_extents` | 半边长 |
| `h` | 差分步长 |

**返回**: 参数梯度（d_extents 分量填充）  

**参见**: `box_extent_gradient 底层数值差分`  


**圆柱所有参数的梯度**  
`[[nodiscard]] inline ParamGrad cylinder_param_grad(const Point3D& p, double radius, double height,`  

| 参数 | 说明 |
|------|------|
| `p` | 采样点 |
| `radius` | 圆柱半径 |
| `height` | 圆柱高度 |
| `h` | 差分步长 |

**返回**: 参数梯度（d_radius, d_height 填充）  



### `sdf_operations.h`

**SDF 布尔运算、修饰算子与域变形**  


**布尔并集: A ∪ B**  
`[[nodiscard]] inline double op_union(double d1, double d2) {`  

| 参数 | 说明 |
|------|------|
| `d1` | 第一个对象的 SDF 值 |
| `d2` | 第二个对象的 SDF 值 |

**返回**: 并集的 SDF 值  

**参见**: `op_smooth_union 带平滑过渡的并集`, `op_intersection 交集`  


**布尔交集: A ∩ B**  
`[[nodiscard]] inline double op_intersection(double d1, double d2) {`  

| 参数 | 说明 |
|------|------|
| `d1` | 第一个对象的 SDF 值 |
| `d2` | 第二个对象的 SDF 值 |

**返回**: 交集的 SDF 值  

**参见**: `op_smooth_intersection 带平滑过渡的交集`  


**布尔差集: A \ B**  
`[[nodiscard]] inline double op_difference(double d1, double d2) {`  

| 参数 | 说明 |
|------|------|
| `d1` | 被减对象 A 的 SDF 值 |
| `d2` | 减去对象 B 的 SDF 值 |

**返回**: 差集的 SDF 值  

**参见**: `op_smooth_difference 带平滑过渡的差集`  


**平滑并集（带混合过渡）**  
`[[nodiscard]] inline double op_smooth_union(double d1, double d2, double k) {`  

| 参数 | 说明 |
|------|------|
| `d1` | 第一个对象的 SDF 值 |
| `d2` | 第二个对象的 SDF 值 |
| `k` | 混合强度参数（> 0 时平滑过渡；≤ 0 时退化为普通并集） |

**返回**: 平滑混合后的 SDF 值  
> 多项式混合是函数 f(x)=x 在 [0,k] 区间的平滑近似。在 d1=d2 处，f 向下偏移 k/4。  

**参见**: `op_union 无平滑的标准并集`, `op_smooth_intersection 平滑交集`, `op_smooth_difference 平滑差集`  


**平滑交集（带混合过渡）**  
`[[nodiscard]] inline double op_smooth_intersection(double d1, double d2, double k) {`  

| 参数 | 说明 |
|------|------|
| `d1` | 第一个对象的 SDF 值 |
| `d2` | 第二个对象的 SDF 值 |
| `k` | 混合强度参数 |

**返回**: 平滑混合后的 SDF 值  

**参见**: `op_intersection 无平滑的标准交集`, `op_smooth_union 平滑并集`  


**平滑差集（带混合过渡）**  
`[[nodiscard]] inline double op_smooth_difference(double d1, double d2, double k) {`  

| 参数 | 说明 |
|------|------|
| `d1` | 被减对象 A 的 SDF 值 |
| `d2` | 减去对象 B 的 SDF 值 |
| `k` | 混合强度参数 |

**返回**: 平滑混合后的 SDF 值  

**参见**: `op_difference 无平滑的标准差集`, `op_smooth_union 平滑并集`  


**圆角偏移: 将等值面向外扩展 r 单位**  
`[[nodiscard]] inline double op_round(double d, double r) {`  

| 参数 | 说明 |
|------|------|
| `d` | SDF 值 |
| `r` | 偏移距离（正值 = 膨胀，负值 = 收缩） |

**返回**: 偏移后的 SDF 值  

**参见**: `op_onion 壳层修饰`, `round_box 特例化的圆角立方体`  


**洋葱皮/壳层修饰: 取绝对值后减去厚度**  
`[[nodiscard]] inline double op_onion(double d, double thickness) {`  

| 参数 | 说明 |
|------|------|
| `d` | SDF 值 |
| `thickness` | 壳层半厚度，必须 > 0 |

**返回**: 壳层的 SDF 值  

**参见**: `op_round 圆角偏移`  


**无限重复（周期复制）**  
`[[nodiscard]] inline Point3D op_repeat(const Point3D& p, const Point3D& cell) {`  

| 参数 | 说明 |
|------|------|
| `p` | 原始采样点 |
| `cell` | 晶格尺寸 (cx, cy, cz)，各分量必须 > 0 才生效 |

**返回**: 映射到中心晶格内的点  
> 边界处 SDF 可能不连续，需要确保各晶格间映射是连续的。  


**镜像对称（X=0 平面），可选偏移**  
`[[nodiscard]] inline Point3D op_mirror_x(const Point3D& p, double offset = 0.0) {`  

| 参数 | 说明 |
|------|------|
| `p` | 原始采样点 |
| `offset` | 镜像平面沿 X 轴的偏移量（默认 0 = X=0 平面） |

**返回**: 映射到镜像半空间的点  

**参见**: `op_mirror_y YZ 平面镜像`, `op_mirror_z XY 平面镜像`  


**镜像对称（Y=0 平面）**  
`[[nodiscard]] inline Point3D op_mirror_y(const Point3D& p) {`  

| 参数 | 说明 |
|------|------|
| `p` | 原始采样点 |

**返回**: 映射到上半空间的点  


**镜像对称（Z=0 平面）**  
`[[nodiscard]] inline Point3D op_mirror_z(const Point3D& p) {`  

| 参数 | 说明 |
|------|------|
| `p` | 原始采样点 |

**返回**: 映射到前半空间的点  


**空间平移（逆变换）**  
`[[nodiscard]] inline Point3D op_translate(const Point3D& p, const Point3D& offset) {`  

| 参数 | 说明 |
|------|------|
| `p` | 原始采样点 |
| `offset` | 平移量（对象正向移动的方向） |

**返回**: 逆平移后的采样点  

**参见**: `op_rotate 旋转变换`, `op_scale 缩放变换`  


**绕 Y 轴旋转（逆变换）**  
`[[nodiscard]] inline Point3D op_rotate(const Point3D& p, double angle_rad) {`  

| 参数 | 说明 |
|------|------|
| `p` | 原始采样点 |
| `angle_rad` | 旋转角度（弧度），正值 = 逆时针（从上往下看） |

**返回**: 逆旋转后的采样点  

**参见**: `op_twist 绕 Y 轴的扭曲变换`, `op_bend 弯曲变换`  


**非均匀缩放（逆变换）**  
`[[nodiscard]] inline Point3D op_scale(const Point3D& p, const Point3D& s) {`  

| 参数 | 说明 |
|------|------|
| `p` | 原始采样点 |
| `s` | 各轴缩放因子 (sx, sy, sz)，均必须 ≠ 0 |

**返回**: 缩放后的采样点  

**参见**: `op_translate 平移（等距变换）`, `op_rotate 旋转（等距变换）`  


**绕 Y 轴的扭曲变换**  
`[[nodiscard]] inline Point3D op_twist(const Point3D& p, double amount) {`  

| 参数 | 说明 |
|------|------|
| `p` | 原始采样点 |
| `amount` | 单位高度上的旋转量（弧度/单位长度） |

**返回**: 扭曲后的采样点  

**参见**: `op_rotate 恒定角度旋转`, `op_bend 弯曲变换`  


**弯曲变换（绕 Z 轴弯曲 XZ 平面）**  
`[[nodiscard]] inline Point3D op_bend(const Point3D& p, double k) {`  

| 参数 | 说明 |
|------|------|
| `p` | 原始采样点 |
| `k` | 弯曲曲率参数（k 越大弯曲越剧烈） |

**返回**: 弯曲后的采样点  

**参见**: `op_cheap_bend 简化版弯曲（仅绕 X 轴）`, `op_twist 扭曲变换`  


**拉伸/压扁域变形（消除拉伸方向上的内部体积）**  
`[[nodiscard]] inline Point3D op_elongate(const Point3D& p, const Point3D& h) {`  

| 参数 | 说明 |
|------|------|
| `p` | 原始采样点 |
| `h` | 各轴的拉伸阈值 (hx, hy, hz)，均 ≥ 0 |

**返回**: 变形后的采样点  

**参见**: `op_repeat 周期重复`  


**简化弯曲变换（绕 X 轴弯曲 YZ 平面）**  
`[[nodiscard]] inline Point3D op_cheap_bend(const Point3D& p, double k) {`  

| 参数 | 说明 |
|------|------|
| `p` | 原始采样点 |
| `k` | 弯曲曲率参数 |

**返回**: 弯曲后的采样点  
> 使用场景：不需要精确物理弯曲，仅需视觉效果时优先用此函数以节省计算。  

**参见**: `op_bend 完整弯曲变换`  


**正弦波位移扰动**  
`[[nodiscard]] inline double op_displace(double d, const Point3D& p,`  

| 参数 | 说明 |
|------|------|
| `d` | 原始 SDF 值 |
| `p` | 采样点（用于扰动计算） |
| `amplitude` | 扰动幅值 |
| `frequency` | 空间频率 |

**返回**: 扰动后的 SDF 值  



### `sdf_optimize.h`

**基于梯度的 SDF 形状优化**  


**优化结果**  
`struct OptimizeResult {`  


**损失函数类型**  
`using LossFn = std::function<double(const std::function<double(const Point3D&)>&)>`  

**参见**: `fit_to_point_cloud 使用该类型的内置实现`  


**将参数化形状拟合到目标点云**  
`[[nodiscard]] OptimizeResult fit_to_point_cloud(`  

| 参数 | 说明 |
|------|------|
| `initial` | 初始形状（sphere, box, cylinder 等），其参数将被优化 |
| `target_points` | 目标点云（表面采样点） |
| `learning_rate` | 梯度下降步长（默认 0.01） |
| `max_iterations` | 最大迭代次数（默认 100） |

**返回**: 优化结果（含优化后的形状和收敛信息）  
> 损失函数为 L = mean(|sdf(p_i)|)，即点到表面的平均绝对距离。  
> initial 的共享子节点不会被复制——返回的 optimize_shape 共享未修改的子树。  

**参见**: `fit_surface_to_points 类似但仅最小化 |sdf| 而非有符号距离`, `fit_to_sdf 拟合到另一个 SDF`  


**将形状表面移动到目标采样点**  
`[[nodiscard]] OptimizeResult fit_surface_to_points(`  

| 参数 | 说明 |
|------|------|
| `initial` | 初始形状 |
| `surface_points` | 目标表面点 |
| `learning_rate` | 学习率 |
| `max_iterations` | 最大迭代次数 |

**返回**: 优化结果  

**参见**: `fit_to_point_cloud 更通用的点云拟合（可包含内部/外部点）`  


**拟合一个 SDF 形状以匹配另一个目标 SDF**  
`[[nodiscard]] OptimizeResult fit_to_sdf(`  

| 参数 | 说明 |
|------|------|
| `source` | 被优化的参数化形状 |
| `target_sdf` | 目标 SDF 函数 |
| `bmin` | 采样网格最小角点 |
| `bmax` | 采样网格最大角点 |
| `grid_resolution` | 采样网格分辨率（默认 16） |
| `learning_rate` | 学习率 |
| `max_iterations` | 最大迭代次数 |

**返回**: 优化结果  

**参见**: `fit_to_point_cloud 拟合到点云`  


**通过平移解决两个形状之间的穿透**  
`[[nodiscard]] bool resolve_collision(`  

| 参数 | 说明 |
|------|------|
| `shape_a` | 形状 A（原地修改） |
| `shape_b` | 形状 B（原地修改） |
| `step_size` | 每次迭代的平移步长（默认 0.1） |
| `max_iterations` | 最大迭代次数（默认 50） |

**返回**: true 如果碰撞被成功解决；false 如果在迭代次数内未能解决  

**参见**: `penetration_depth 估算穿透深度`  


**估算两个形状之间的最小穿透距离**  
`[[nodiscard]] double penetration_depth(`  

| 参数 | 说明 |
|------|------|
| `shape_a` | 形状 A |
| `shape_b` | 形状 B |
| `bmin` | 公共包围盒最小角点 |
| `bmax` | 公共包围盒最大角点 |
| `samples` | 蒙地卡罗采样数（默认 1000） |

**返回**: 最大穿透深度（负值表示不重叠时的最小间距）  

**参见**: `resolve_collision 解决穿透`  


**计算形状表面上点的可及性分数**  
`[[nodiscard]] double accessibility(`  

| 参数 | 说明 |
|------|------|
| `shape` | SDF 形状 |
| `p` | 表面点（应满足 |sdf(p)| < ε） |
| `direction` | 接近方向 |
| `hemisphere_samples` | 半球采样光线数量（默认 64） |

**返回**: 可及性分数 [0, 1]  
> 采样数越多越精确，但线性增加计算量。  

**参见**: `find_accessible_point 找到最大可及性的表面点`  


**找到给定接近方向下具有最大可及性的表面点**  
`[[nodiscard]] Point3D find_accessible_point(`  

| 参数 | 说明 |
|------|------|
| `shape` | SDF 形状 |
| `approach_dir` | 接近方向（如工具接近方向） |
| `bmin` | 搜索包围盒最小角点 |
| `bmax` | 搜索包围盒最大角点 |
| `grid_res` | 搜索网格分辨率（默认 32） |

**返回**: 最大可及性的表面点  

**参见**: `accessibility 单点可及性计算`  


**检测形状在给定方向上的反射对称性**  
`[[nodiscard]] double symmetry_score(`  

| 参数 | 说明 |
|------|------|
| `shape` | SDF 形状 |
| `bmin` | 包围盒最小角点 |
| `bmax` | 包围盒最大角点 |
| `plane_normal` | 反射平面的法向量 |
| `plane_offset` | 反射平面的偏移量（沿法向量方向，默认 0） |
| `samples` | 采样点对数（默认 1000） |

**返回**: 对称性分数 [0, 1]（0 = 完全不对称，1 = 完美对称）  

**参见**: `find_symmetry_plane 自动寻找最佳对称平面`  


**对称检测结果**  
`struct SymmetryResult {`  


**自动找到形状的最佳反射对称平面**  
`[[nodiscard]] SymmetryResult find_symmetry_plane(`  

| 参数 | 说明 |
|------|------|
| `shape` | SDF 形状 |
| `bmin` | 包围盒最小角点 |
| `bmax` | 包围盒最大角点 |
| `samples` | 每个候选方向的采样数（默认 1000） |

**返回**: 最佳对称平面及其分数  

**参见**: `symmetry_score 给定方向的对称性检测`  


**通过蒙地卡罗法估算隐式形状的体积**  
`[[nodiscard]] double estimate_volume(`  

| 参数 | 说明 |
|------|------|
| `shape` | SDF 形状 |
| `bmin` | 采样包围盒最小角点 |
| `bmax` | 采样包围盒最大角点 |
| `samples` | 蒙地卡罗采样数（默认 10000） |

**返回**: 近似体积  
> 精度与 √samples 成正比。10000 采样 ≈ 1% 相对误差。  
> 包围盒应尽可能紧致以减小方差。  

**参见**: `center_of_mass 蒙地卡罗质心估算`  


**通过蒙地卡罗法估算形状的质心**  
`[[nodiscard]] Point3D center_of_mass(`  

| 参数 | 说明 |
|------|------|
| `shape` | SDF 形状 |
| `bmin` | 采样包围盒最小角点 |
| `bmax` | 采样包围盒最大角点 |
| `samples` | 蒙地卡罗采样数（默认 10000） |

**返回**: 近似质心坐标  

**参见**: `estimate_volume 体积估算`  


**SDF 树中可变参数的引用**  
`struct ParamRef {`  


**从叶节点收集所有可变数值参数**  
`[[nodiscard]] std::vector<ParamRef> collect_params(SdfNodePtr& root)`  

| 参数 | 说明 |
|------|------|
| `root` | SDF 树根节点（可写引用，因为参数将被原地修改） |

**返回**: 可变参数引用列表  

**参见**: `numerical_gradient 计算损失对参数的数值梯度`  


**计算标量损失对收集到的参数的数值梯度**  
`[[nodiscard]] std::vector<double> numerical_gradient(`  

| 参数 | 说明 |
|------|------|
| `params` | collect_params() 返回的参数引用列表 |
| `loss_fn` | 损失函数（无参数的可调用对象） |
| `eps` | 差分步长（默认 1e-6） |

**返回**: 梯度向量 grad_loss，grad_loss[i] = ∂loss / ∂params[i].value  

**参见**: `collect_params 收集参数`, `GradientDescent 梯度下降优化器`  


**固定学习率的简单梯度下降优化器**  


**构造优化器**  
`explicit GradientDescent(double lr) : lr_(lr) {}`  

| 参数 | 说明 |
|------|------|
| `lr` | 学习率（步长因子） |


**执行单步梯度下降**  
`double step(std::vector<double>& params,`  

| 参数 | 说明 |
|------|------|
| `params` | 参数向量（原地修改） |
| `grad_fn` | 梯度计算函数，签名为 |

**返回**: 当前损失值  


**设置学习率**  
`void set_learning_rate(double lr) { lr_ = lr; }`  


**获取学习率**  
`[[nodiscard]] double learning_rate() const { return lr_; }`  


**获取当前迭代次数**  
`[[nodiscard]] int iteration() const { return iteration_; }`  



### `sdf_primitives.h`

**有符号距离函数（SDF）基础图元**  
> 所有图元假设未施加变换——坐标系原点即图元中心/基点。  


**球体的 SDF**  
`[[nodiscard]] inline double sphere(const Point3D& p, double radius) {`  

| 参数 | 说明 |
|------|------|
| `p` | 采样点（三维坐标） |
| `radius` | 球半径，必须 > 0 |

**返回**: 有符号距离  
> 球位于原点。如需其他位置，使用 op_translate 对采样点做反向平移。  

**参见**: `ellipsoid 各轴半径不同的椭球`, `cylinder 沿 Y 轴的圆柱`  


**轴对齐立方体的 SDF**  
`[[nodiscard]] inline double box(const Point3D& p, const Point3D& half_extents) {`  

| 参数 | 说明 |
|------|------|
| `p` | 采样点 |
| `half_extents` | 半边长 (hx, hy, hz)，均必须 ≥ 0 |

**返回**: 有符号距离  

**参见**: `round_box 带圆角的盒子`, `wedge 对角切割的半盒子`  


**圆角立方体的 SDF**  
`[[nodiscard]] inline double round_box(const Point3D& p, const Point3D& half_extents, double r) {`  

| 参数 | 说明 |
|------|------|
| `p` | 采样点 |
| `half_extents` | 半边长 (hx, hy, hz) |
| `r` | 圆角半径，必须 < min(half_extents) 否则整体形态改变 |

**返回**: 有符号距离  

**参见**: `box 无圆角的长方体`, `op_round 对任意 SDF 做圆角偏移`  


**圆环面的 SDF**  
`[[nodiscard]] inline double torus(const Point3D& p, double major_radius, double minor_radius) {`  

| 参数 | 说明 |
|------|------|
| `p` | 采样点 |
| `major_radius` | 主半径（环的半径），必须 > 0 |
| `minor_radius` | 副半径（管的粗细），必须 > 0 |

**返回**: 有符号距离  

**参见**: `link 双环连接体（两个并行圆环的组合）`  


**胶囊体的 SDF**  
`[[nodiscard]] inline double capsule(const Point3D& p, const Point3D& a, const Point3D& b, double radius) {`  

| 参数 | 说明 |
|------|------|
| `p` | 采样点 |
| `a` | 线段起点 |
| `b` | 线段终点 |
| `radius` | 扫掠球半径，必须 > 0 |

**返回**: 有符号距离  

**参见**: `cylinder 两端平头的圆柱（非球形端盖）`  


**带平端盖的圆柱体 SDF**  
`[[nodiscard]] inline double cylinder(const Point3D& p, double radius, double height) {`  

| 参数 | 说明 |
|------|------|
| `p` | 采样点 |
| `radius` | 圆柱截面半径，必须 > 0 |
| `height` | 圆柱总高度（从 -h/2 到 +h/2），必须 > 0 |

**返回**: 有符号距离  

**参见**: `capsule 两端球形端盖的圆柱`, `infinite_cylinder 无限长圆柱`, `cone 圆锥台`  


**平面的 SDF**  
`[[nodiscard]] inline double plane(const Point3D& p, const Vector3D& normal, double offset) {`  

| 参数 | 说明 |
|------|------|
| `p` | 采样点 |
| `normal` | 单位法向量（必须已归一化） |
| `offset` | 沿法向量正方向的偏移量 |

**返回**: 有符号距离  

**参见**: `wedge 两个平面+盒子的组合（对角切割）`  


**椭球体的 SDF（有界梯度近似）**  
`[[nodiscard]] inline double ellipsoid(const Point3D& p, const Point3D& radii) {`  

| 参数 | 说明 |
|------|------|
| `p` | 采样点 |
| `radii` | 半轴长 (rx, ry, rz)，均必须 > 0 |

**返回**: 有符号距离（近似）  
> 当三个半径相等时退化为球体，此时使用 sphere() 更精确高效。  
> 当点到原点距离远大于最大半径时，近似精度下降。  

**参见**: `sphere 精确球体（rx=ry=rz 时的特例）`  


**正六棱柱的 SDF**  
`[[nodiscard]] inline double hex_prism(const Point3D& p, double radius, double height) {`  

| 参数 | 说明 |
|------|------|
| `p` | 采样点 |
| `radius` | 六边形外接圆半径（中心到顶点），必须 > 0 |
| `height` | 挤出总高度（±h/2 沿 Y 轴），必须 > 0 |

**返回**: 有符号距离  

**参见**: `extrusion_bounded 通用 bounded extrusion 算子`  


**无限长圆柱的 SDF**  
`[[nodiscard]] inline double infinite_cylinder(const Point3D& p, const Vector3D& axis, double radius) {`  

| 参数 | 说明 |
|------|------|
| `p` | 采样点 |
| `axis` | 圆柱轴线方向（必须归一化，|axis| = 1） |
| `radius` | 截面半径，必须 > 0 |

**返回**: 有符号距离  

**参见**: `cylinder 有限长圆柱（带平端盖）`  


**楔形体的 SDF**  
`[[nodiscard]] inline double wedge(const Point3D& p, double w, double h, double d) {`  

| 参数 | 说明 |
|------|------|
| `p` | 采样点 |
| `w` | 宽度（X 方向） |
| `h` | 高度（Y 方向） |
| `d` | 深度（Z 方向） |

**返回**: 有符号距离  

**参见**: `box 完整立方体`, `plane 独立平面 SDF`  


**二维 SDF 沿 Z 轴的无限挤出**  
`[[nodiscard]] inline double extrusion(const Point3D& /*p*/, double sdf_2d) {`  

| 参数 | 说明 |
|------|------|
| `p` | 三维采样点（仅 x,y 分量被隐式使用——通过 sdf_2d 参数间接） |
| `sdf_2d` | 预计算的二维 SDF 值（在 (p.x, p.y) 处求值） |

**返回**: 三维有符号距离（等于 sdf_2d）  
> p 参数仅保持接口一致，实际不影响结果。  
> 对于有限长度的挤出，使用 extrusion_bounded()。  

**参见**: `extrusion_bounded 有限长度的挤出`, `revolution 二维轮廓绕 Y 轴旋转`  


**二维 SDF 的有限长度挤出**  
`[[nodiscard]] inline double extrusion_bounded(const Point3D& p, double sdf_2d, double half_height) {`  

| 参数 | 说明 |
|------|------|
| `p` | 三维采样点 |
| `sdf_2d` | 预计算的二维 SDF 值（在 (p.x, p.y) 处求值） |
| `half_height` | 挤出半高度（Z 方向），必须 ≥ 0 |

**返回**: 有符号距离  

**参见**: `extrusion 无限挤出`, `hex_prism 六棱柱（特例化 bounded extrusion 实现）`  


**二维轮廓绕 Y 轴的旋转体 SDF**  
`[[nodiscard]] inline double revolution(const Point3D& /*p*/, double sdf_2d, double /*offset*/) {`  

| 参数 | 说明 |
|------|------|
| `p` | 三维采样点（接口保留，不直接使用） |
| `sdf_2d` | 预计算的二维 SDF（在 (√(pₓ²+p𝓏²)-offset, p.y) 处求值） |
| `offset` | 径向偏移量（从 Y 轴的起点距离） |

**返回**: 有符号距离  

**参见**: `torus 圆环（revolution 的特例：截面为圆）`  


**圆锥台的 SDF（非内联实现）**  
`[[nodiscard]] double cone(const Point3D& p, double angle_rad, double height)`  

| 参数 | 说明 |
|------|------|
| `p` | 采样点 |
| `angle_rad` | 半锥角（弧度），决定底面半径 |
| `height` | 锥体总高度，必须 > 0 |

**返回**: 有符号距离  

**参见**: `cylinder 半锥角为 0 时的退化情况`, `infinite_cone 无限圆锥`  


**三角棱柱的 SDF（非内联实现）**  
`[[nodiscard]] double triangular_prism(const Point3D& p, const Point3D& a, const Point3D& b,`  

| 参数 | 说明 |
|------|------|
| `p` | 采样点 |
| `a` | 三角形顶点 A（XY 平面内） |
| `b` | 三角形顶点 B（XY 平面内） |
| `c` | 三角形顶点 C（XY 平面内） |
| `height` | 挤出总高度（沿 Z 轴），必须 > 0 |

**返回**: 有符号距离  

**参见**: `wedge 直角三角形楔形体`  


**双环链接体的 SDF（非内联实现）**  
`[[nodiscard]] double link(const Point3D& p, double length, double major_r, double minor_r)`  

| 参数 | 说明 |
|------|------|
| `p` | 采样点 |
| `length` | 两个环心沿 X 轴的距离 |
| `major_r` | 每个环的主半径（环的半径） |
| `minor_r` | 每个环的管半径（截面的粗细） |

**返回**: 有符号距离  

**参见**: `torus 单个圆环`  


**无限圆锥的 SDF（非内联实现）**  
`[[nodiscard]] double infinite_cone(const Point3D& p, const Point3D& apex,`  

| 参数 | 说明 |
|------|------|
| `p` | 采样点 |
| `apex` | 锥顶位置 |
| `axis` | 锥轴方向（必须归一化），锥体沿此方向扩展 |
| `angle_rad` | 半锥角（弧度） |

**返回**: 有符号距离  

**参见**: `cone 有限高圆锥台`  



### `sdf_to_mesh.h`

**SDF 到三角网格的转换**  


**将 SDF 表达式树转换为三角网格**  
`[[nodiscard]] mesh::MCMesh sdf_to_mesh(const SdfNodePtr& root,`  

| 参数 | 说明 |
|------|------|
| `root` | SDF 表达式树的根节点 |
| `resolution` | 每轴的网格分辨率（例如 64 表示 64³ 体素网格） |
| `iso_level` | 等值面水平（0.0 = 隐式表面） |

**返回**: 包含顶点和三角形索引的 MCMesh  
> 分辨率推荐为 2 的幂（32, 64, 128, 256）以获得最佳缓存性能。  
> 对于大尺寸但细节少的几何体，使用较低的 resolution 即可获得光滑结果。  

**参见**: `sdf_to_mesh_lambda Lambda 版本的 SDF 转网格（Python 友好）`, `estimate_bbox 包围盒估算`  


**将 Lambda SDF 函数转换为三角网格**  
`[[nodiscard]] mesh::MCMesh sdf_to_mesh_lambda(`  

| 参数 | 说明 |
|------|------|
| `f` | SDF 函数，签名为 double(double x, double y, double z) → 有符号距离 |
| `bmin` | 采样包围盒最小角点 |
| `bmax` | 采样包围盒最大角点 |
| `resolution` | 每轴分辨率 |
| `iso_level` | 等值面水平（默认 0.0） |

**返回**: MCMesh 三角网格  

**参见**: `sdf_to_mesh 基于 SDF 树的网格转换`  



### `sdf_torch.h`

**SDF 批量求值与梯度计算（CPU 后端）**  


**在批处理模式下求值 SDF**  
`void evaluate_batch(const SdfNodePtr& root,`  

| 参数 | 说明 |
|------|------|
| `root` | SDF 表达式树根节点 |
| `points` | 点数组，length = 3·n，x,y,z 交替存储 |
| `n` | 点数 |
| `distances` | 输出数组，length = n，写入有符号距离值 |

**参见**: `evaluate 单点求值`, `gradient_batch 批量梯度计算`  


**在批处理模式下求值 SDF 的空间梯度**  
`void gradient_batch(const SdfNodePtr& root,`  

| 参数 | 说明 |
|------|------|
| `root` | SDF 表达式树根节点 |
| `points` | 点数组，length = 3·n |
| `n` | 点数 |
| `gradients` | 输出数组，length = 3·n，x,y,z 梯度分量交替存储 |

**参见**: `evaluate_batch 批量距离求值`, `evaluate_with_gradient_batch 同时获取距离和梯度（减少重复采样）`  


**一次遍历同时求值 SDF 值和梯度**  
`void evaluate_with_gradient_batch(const SdfNodePtr& root,`  

| 参数 | 说明 |
|------|------|
| `root` | SDF 表达式树根节点 |
| `points` | 点数组，length = 3·n |
| `n` | 点数 |
| `distances` | 输出距离数组，length = n |
| `gradients` | 输出梯度数组，length = 3·n |
> 对于大量点的场景（n > 1000），推荐使用本函数以获得 ~2× 速度提升。  

**参见**: `evaluate_batch 仅求距离`, `gradient_batch 仅求梯度`  



### `sdf_tree.h`

**SDF 表达式树结构**  


**CSG 树的所有节点类型**  
`enum class SdfOp : uint8_t {`  

**参见**: `SdfParams 对应的参数结构`  


**SDF 节点参数联合体**  
`struct SdfParams {`  


**SDF 表达式树节点**  
> 树是不可变的——节点创建后 op 和子节点关系不变，但 params 可被外部修改以支持参数优化。  


**创建球体节点**  
`static SdfNodePtr sphere(double r)`  


**创建轴对齐长方体节点**  
`static SdfNodePtr box(const Point3D& half_extents)`  


**创建圆角长方体节点**  
`static SdfNodePtr round_box(const Point3D& half_extents, double r)`  


**创建圆柱体节点**  
`static SdfNodePtr cylinder(double r, double h)`  


**创建圆环体节点**  
`static SdfNodePtr torus(double major_r, double minor_r)`  


**创建胶囊体节点**  
`static SdfNodePtr capsule(const Point3D& a, const Point3D& b, double r)`  


**创建圆锥台节点**  
`static SdfNodePtr cone(double angle_rad, double h)`  


**创建平面节点**  
`static SdfNodePtr plane(const Vector3D& normal, double offset)`  


**创建椭球体节点**  
`static SdfNodePtr ellipsoid(const Point3D& radii)`  


**创建三角棱柱节点**  
`static SdfNodePtr triangular_prism(double h)`  


**创建六棱柱节点**  
`static SdfNodePtr hex_prism(double h)`  


**创建双环链接节点**  
`static SdfNodePtr link(double r, double length, double thickness)`  


**创建楔形体节点**  
`static SdfNodePtr wedge(const Point3D& extents)`  


**创建并集节点: A ∪ B**  
`static SdfNodePtr op_union(SdfNodePtr a, SdfNodePtr b)`  


**创建交集节点: A ∩ B**  
`static SdfNodePtr op_intersection(SdfNodePtr a, SdfNodePtr b)`  


**创建差集节点: A \ B**  
`static SdfNodePtr op_difference(SdfNodePtr a, SdfNodePtr b)`  


**创建平滑并集节点**  
`static SdfNodePtr smooth_union(SdfNodePtr a, SdfNodePtr b, double k)`  


**创建平滑交集节点**  
`static SdfNodePtr smooth_intersection(SdfNodePtr a, SdfNodePtr b, double k)`  


**创建平滑差集节点**  
`static SdfNodePtr smooth_difference(SdfNodePtr a, SdfNodePtr b, double k)`  


**创建圆角偏移节点**  
`static SdfNodePtr round(SdfNodePtr child, double r)`  


**创建壳层修饰节点**  
`static SdfNodePtr onion(SdfNodePtr child, double thickness)`  


**创建周期重复节点**  
`static SdfNodePtr repeat(SdfNodePtr child, const Point3D& cell)`  


**创建 X 镜像节点**  
`static SdfNodePtr mirror_x(SdfNodePtr child)`  


**创建 Y 镜像节点**  
`static SdfNodePtr mirror_y(SdfNodePtr child)`  


**创建 Z 镜像节点**  
`static SdfNodePtr mirror_z(SdfNodePtr child)`  


**创建平移节点**  
`static SdfNodePtr translate(SdfNodePtr child, const Point3D& offset)`  


**创建旋转节点（绕 Y 轴）**  
`static SdfNodePtr rotate(SdfNodePtr child, double angle_rad)`  


**创建缩放节点**  
`static SdfNodePtr scale(SdfNodePtr child, const Point3D& factors)`  


**创建扭曲节点**  
`static SdfNodePtr twist(SdfNodePtr child, double amount)`  


**创建弯曲节点**  
`static SdfNodePtr bend(SdfNodePtr child, double amount)`  


**创建拉伸节点**  
`static SdfNodePtr elongate(SdfNodePtr child, const Point3D& h)`  


**创建简化弯曲节点**  
`static SdfNodePtr cheap_bend(SdfNodePtr child, double amount)`  


**创建位移扰动节点**  
`static SdfNodePtr displace(SdfNodePtr child, double amplitude, double frequency)`  


**前序遍历所有节点**  
`template <typename Fn>`  


**前序遍历（const 版本）**  
`template <typename Fn>`  

**参见**: `visit(Fn&&)`  


**构造 SDF 节点**  
`explicit SdfNode(SdfOp o) : op(o) {}`  

| 参数 | 说明 |
|------|------|
| `o` | 操作类型 |


**在空间点 p 处求值 SDF 树**  
`[[nodiscard]] double evaluate(const SdfNodePtr& root, const Point3D& p)`  

| 参数 | 说明 |
|------|------|
| `root` | SDF 表达式树的根节点 |
| `p` | 世界空间中的采样点 |

**返回**: 有符号距离（负 = 内部，零 = 表面，正 = 外部）  

**参见**: `estimate_bounds 估计树的包围盒`  


**估算 SDF 树的包围半尺寸**  
`[[nodiscard]] Point3D estimate_bounds(const SdfNodePtr& root, double margin = 1.0)`  

| 参数 | 说明 |
|------|------|
| `root` | SDF 树的根节点 |
| `margin` | 额外安全边距（默认 1.0） |

**返回**: 包围半边长 (hx, hy, hz)  
> 变形节点（旋转/弯曲/扭曲等）会使包围盒放大，以保守估计覆盖变形后区域。  

**参见**: `estimate_bbox 完整 AABB 结果`  


**SDF 树的包围盒（AABB）**  
`struct SdfBBox {`  


**估算 SDF 树的完整轴对齐包围盒**  
`[[nodiscard]] SdfBBox estimate_bbox(const SdfNodePtr& root, double margin = 1.0)`  

| 参数 | 说明 |
|------|------|
| `root` | SDF 树的根节点 |
| `margin` | 额外安全边距 |

**返回**: AABB 包围盒  



## 草图约束 (`vde::sketch`)


### `constraint_solver.h`

**草图点元素**  
`struct SketchPoint {`  


**草图线段元素**  
`struct SketchLine {`  


**草图圆元素**  
`struct SketchCircle {`  


**约束类型枚举**  
`enum class ConstraintType {`  


**约束实例**  
`struct Constraint {`  


**求解器返回结果**  
`struct SolverResult {`  


**二维几何约束求解器**  


**添加自由点**  
`int add_point(double x, double y, bool fixed = false)`  

| 参数 | 说明 |
|------|------|
| `x` | X 坐标 |
| `y` | Y 坐标 |
| `fixed` | 是否固定（true 则排除变量） |

**返回**: 点 ID  


**添加线段**  
`int add_line(int p0, int p1)`  

| 参数 | 说明 |
|------|------|
| `p0` | 起点 ID |
| `p1` | 终点 ID |

**返回**: 线段 ID  


**添加圆**  
`int add_circle(int center, double radius)`  

| 参数 | 说明 |
|------|------|
| `center` | 圆心点 ID |
| `radius` | 半径 |

**返回**: 圆 ID  


**添加约束**  
`void add_constraint(ConstraintType type, const std::vector<int>& elements, double val = 0.0)`  

| 参数 | 说明 |
|------|------|
| `type` | 约束类型 |
| `elements` | 约束涉及的元素 ID 列表 |
| `val` | 约束值（距离、角度等），默认 0 |
> 不同类型 elements 的语义：  


**标记点为固定（硬约束）**  
`void fix_point(int pid) {`  

| 参数 | 说明 |
|------|------|
| `pid` | 点 ID |
> 固定点不参与变量优化，从自由度中排除  


**执行约束求解**  
`[[nodiscard]] SolverResult solve(int max_iter = 100, double tol = 1e-8)`  

| 参数 | 说明 |
|------|------|
| `max_iter` | 最大 Gauss-Newton 迭代次数，默认 100 |
| `tol` | 收敛容差（梯度范数 < tol 时停止），默认 1e-8 |

**返回**: SolverResult 求解结果  
> 收敛判断：||J^T r|| < tol  
> 欠约束时（DOF > 0）解不唯一；过约束时（DOF < 0）为最小二乘解  


**计算自由度**  
`[[nodiscard]] int degrees_of_freedom() const`  

**返回**: DOF = 2·N_free - Σ(约束方程数)  
> DOF < 0 时系统过约束，求解器仍然工作但解非精确满足所有约束  


**当前点集访问**  
`[[nodiscard]] const std::vector<SketchPoint>& points() const { return points_; }`  

**返回**: SketchPoint 数组只读引用  


**查询点坐标**  
`[[nodiscard]] Point2D get_point(int id) const`  

| 参数 | 说明 |
|------|------|
| `id` | 点 ID |

**返回**: Point2D 当前坐标  


**将求解器变量向量同步回 points_（用于 Jacobian 数值计算）**  
`void sync_from_vars(const double* vars, int nv)`  

| 参数 | 说明 |
|------|------|
| `vars` | 变量数组（长度为 2·N_free） |
| `nv` | 变量数 |


**评估单个约束的残差值**  
`double eval_constraint(const Constraint& c) const`  

| 参数 | 说明 |
|------|------|
| `c` | 约束 |

**返回**: 残差（方程 → 0 表示约束满足）  


**计算单个约束的方程数**  
`int count_equations(const Constraint& c) const`  

| 参数 | 说明 |
|------|------|
| `c` | 约束 |

**返回**: Coincident/Fixed → 2，其余 → 1  


**填充 Jacobian 矩阵中对应约束 ci 的行**  
`void fill_jacobian_rows(const Constraint& c, int ci,`  

| 参数 | 说明 |
|------|------|
| `c` | 约束 |
| `ci` | 约束索引 |
| `row_map` | 方程行映射 |
| `J_data` | Jacobian 矩阵数据（行优先） |
| `nv` | 变量数 |
| `stride` | 行跨度 |



## C API (`vde::capi`)


### `vde_capi.h`

**ViewDesignEngine C API — 跨语言边界接口**  
`extern "C" {`  

**参见**: `vde.h C++ 等价接口`  


**引擎上下文句柄 — 管理错误状态和内部资源**  
`typedef struct VdeContext* VdeHandle`  


**三角网格句柄 — 顶点+面集合**  
`typedef struct VdeMesh* VdeMeshHandle`  


**参数曲线句柄 — NURBS 曲线**  
`typedef struct VdeCurve* VdeCurveHandle`  


**约束求解器句柄 — 二维草图约束**  
`typedef struct VdeSolver* VdeSolverHandle`  


**B-Rep 实体句柄 — 边界表示模型**  
`typedef struct VdeBody* VdeBodyHandle`  


**创建 ViewDesignEngine 上下文**  
`VdeHandle vde_create(void)`  

**返回**: 新的引擎句柄，不需要时通过 vde_destroy() 释放  

**参见**: `vde_destroy 释放上下文`  


**销毁引擎上下文**  
`void vde_destroy(VdeHandle ctx)`  

| 参数 | 说明 |
|------|------|
| `ctx` | 引擎上下文句柄 |

**参见**: `vde_create`  


**获取引擎版本字符串**  
`const char* vde_version(void)`  

**返回**: 语义版本号字符串（如 "0.5.0"），静态生命周期，无需释放  


**获取最后一次操作的错误描述**  
`const char* vde_last_error(VdeHandle ctx)`  

| 参数 | 说明 |
|------|------|
| `ctx` | 引擎上下文句柄 |

**返回**: 错误描述字符串（上下文的内部缓冲区，静态生命周期）  
> 每次新的失败操作会覆盖此描述。成功操作不会清除它。  


**从文件加载三角网格**  
`VdeMeshHandle vde_load_mesh(VdeHandle ctx, const char* path)`  

| 参数 | 说明 |
|------|------|
| `ctx` | 引擎上下文句柄 |
| `path` | 文件路径（UTF-8 编码） |

**返回**: 网格句柄，失败时返回 NULL（通过 vde_last_error() 获取原因）  

**参见**: `vde_mesh_free 释放网格`, `vde_save_mesh 保存网格`  


**将三角网格保存为文件**  
`int vde_save_mesh(VdeHandle ctx, VdeMeshHandle mesh, const char* path, const char* format)`  

| 参数 | 说明 |
|------|------|
| `ctx` | 引擎上下文句柄 |
| `mesh` | 网格句柄 |
| `path` | 输出文件路径 |
| `format` | 输出格式（当前仅 "obj" 有效） |

**返回**: 成功返回 1，失败返回 0  

**参见**: `vde_load_mesh 加载网格`  


**获取网格的顶点数量**  
`size_t vde_mesh_num_vertices(VdeMeshHandle mesh)`  

| 参数 | 说明 |
|------|------|
| `mesh` | 网格句柄（必须有效且非 NULL） |

**返回**: 顶点数  

**参见**: `vde_mesh_num_faces 面数`  


**获取网格的三角面数量**  
`size_t vde_mesh_num_faces(VdeMeshHandle mesh)`  

| 参数 | 说明 |
|------|------|
| `mesh` | 网格句柄 |

**返回**: 面数  

**参见**: `vde_mesh_num_vertices 顶点数`  


**获取指定索引的顶点坐标**  
`void vde_mesh_get_vertex(VdeMeshHandle mesh, size_t idx,`  

| 参数 | 说明 |
|------|------|
| `mesh` | 网格句柄 |
| `idx` | 顶点索引 [0, num_vertices) |
| `out_x` | [out] 顶点 X 坐标 |
| `out_y` | [out] 顶点 Y 坐标 |
| `out_z` | [out] 顶点 Z 坐标 |


**获取网格的轴对齐包围盒**  
`void vde_mesh_get_bounds(VdeMeshHandle mesh,`  

| 参数 | 说明 |
|------|------|
| `mesh` | 网格句柄 |
| `out_min_x` | [out] 最小 X 坐标 |
| `out_min_y` | [out] 最小 Y 坐标 |
| `out_min_z` | [out] 最小 Z 坐标 |
| `out_max_x` | [out] 最大 X 坐标 |
| `out_max_y` | [out] 最大 Y 坐标 |
| `out_max_z` | [out] 最大 Z 坐标 |


**释放网格句柄及其资源**  
`void vde_mesh_free(VdeMeshHandle mesh)`  

| 参数 | 说明 |
|------|------|
| `mesh` | 网格句柄 |


**网格简化**  
`VdeMeshHandle vde_mesh_simplify(VdeHandle ctx, VdeMeshHandle mesh, double target_ratio)`  

| 参数 | 说明 |
|------|------|
| `ctx` | 引擎上下文句柄 |
| `mesh` | 输入网格句柄（不修改输入） |
| `target_ratio` | 目标简化比率 [0, 1]（0 = 不变，1 = 最大简化） |

**返回**: 简化后的新网格句柄  

**参见**: `vde_mesh_smooth 网格平滑`  


**网格平滑（Laplacian 或 Taubin 平滑）**  
`VdeMeshHandle vde_mesh_smooth(VdeHandle ctx, VdeMeshHandle mesh, int iterations)`  

| 参数 | 说明 |
|------|------|
| `ctx` | 引擎上下文句柄 |
| `mesh` | 输入网格句柄 |
| `iterations` | 平滑迭代次数 |

**返回**: 平滑后的新网格句柄  

**参见**: `vde_mesh_simplify 网格简化`  


**网格布尔运算**  
`VdeMeshHandle vde_mesh_boolean(VdeHandle ctx, VdeMeshHandle a, VdeMeshHandle b, int operation)`  

| 参数 | 说明 |
|------|------|
| `ctx` | 引擎上下文句柄 |
| `a` | 网格 A |
| `b` | 网格 B |
| `operation` | 布尔操作类型: 0 = 并集, 1 = 交集, 2 = 差集 (A \ B) |

**返回**: 布尔结果的新网格句柄  


**创建 Bézier 曲线**  
`VdeCurveHandle vde_curve_create_bezier(VdeHandle ctx, const double* control_points,`  

| 参数 | 说明 |
|------|------|
| `ctx` | 引擎上下文句柄 |
| `control_points` | 控制点数组，每 3 个 double 表示一个三维点 (x,y,z) |
| `num_points` | 控制点数量（次数 = num_points - 1） |
| `dim` | 维度（固定为 3） |

**返回**: 曲线句柄  

**参见**: `vde_curve_evaluate 求值`, `vde_curve_free 释放`  


**在参数 t 处求值曲线**  
`void vde_curve_evaluate(VdeCurveHandle curve, double t,`  

| 参数 | 说明 |
|------|------|
| `curve` | 曲线句柄 |
| `t` | 参数值 [0, 1] |
| `out_x` | [out] 曲线上点的 X 坐标 |
| `out_y` | [out] 曲线上点的 Y 坐标 |
| `out_z` | [out] 曲线上点的 Z 坐标 |


**获取曲线的次数**  
`int vde_curve_degree(VdeCurveHandle curve)`  

| 参数 | 说明 |
|------|------|
| `curve` | 曲线句柄 |

**返回**: 曲线次数  


**释放曲线句柄**  
`void vde_curve_free(VdeCurveHandle curve)`  

| 参数 | 说明 |
|------|------|
| `curve` | 曲线句柄 |


**两球体碰撞检测（GJK 算法）**  
`int vde_collision_gjk_spheres(VdeHandle ctx,`  

| 参数 | 说明 |
|------|------|
| `ctx` | 引擎上下文句柄 |
| `cx1,` | cy1, cz1 第一个球体的球心坐标 |
| `r1` | 第一个球体的半径 |
| `cx2,` | cy2, cz2 第二个球体的球心坐标 |
| `r2` | 第二个球体的半径 |

**返回**: 碰撞返回 1，不碰撞返回 0  

**参见**: `vde_collision_ray_mesh 射线-网格相交`  


**射线与网格的最近交点查询**  
`int vde_collision_ray_mesh(VdeHandle ctx, VdeMeshHandle mesh,`  

| 参数 | 说明 |
|------|------|
| `ctx` | 引擎上下文句柄 |
| `mesh` | 目标网格句柄 |
| `ox,` | oy, oz 射线起点 |
| `dx,` | dy, dz 射线方向（无需归一化） |
| `out_t` | [out] 交点参数 t（沿射线的距离） |
| `out_x,` | out_y, out_z [out] 交点坐标 |

**返回**: 命中返回 1，未命中返回 0  

**参见**: `vde_collision_gjk_spheres GJK 球体碰撞`  


**创建二维约束求解器**  
`VdeSolverHandle vde_solver_create(void)`  

**返回**: 求解器句柄  

**参见**: `vde_solver_free 释放`  


**向求解器添加点**  
`int vde_solver_add_point(VdeSolverHandle solver, double x, double y, int fixed)`  

| 参数 | 说明 |
|------|------|
| `solver` | 求解器句柄 |
| `x` | 初始 X 坐标 |
| `y` | 初始 Y 坐标 |
| `fixed` | 固定点标记（1 = 固定不移动） |

**返回**: 点的 ID（用于后续约束引用）  

**参见**: `vde_solver_add_line 添加线段`  


**向求解器添加线段（由两个点定义）**  
`int vde_solver_add_line(VdeSolverHandle solver, int p0, int p1)`  

| 参数 | 说明 |
|------|------|
| `solver` | 求解器句柄 |
| `p0` | 起点 ID |
| `p1` | 终点 ID |

**返回**: 线段的 ID  

**参见**: `vde_solver_add_point 添加点`, `vde_solver_add_horizontal 添加水平约束`, `vde_solver_add_vertical 添加垂直约束`  


**添加距离约束（两点之间）**  
`void vde_solver_add_distance_constraint(VdeSolverHandle solver, int p0, int p1, double d)`  

| 参数 | 说明 |
|------|------|
| `solver` | 求解器句柄 |
| `p0` | 第一个点的 ID |
| `p1` | 第二个点的 ID |
| `d` | 目标距离（必须 > 0） |

**参见**: `vde_solver_add_horizontal 水平约束`  


**添加水平约束（线段水平）**  
`void vde_solver_add_horizontal(VdeSolverHandle solver, int line_id)`  

| 参数 | 说明 |
|------|------|
| `solver` | 求解器句柄 |
| `line_id` | 线段 ID |

**参见**: `vde_solver_add_vertical 垂直约束`, `vde_solver_add_line 添加线段`  


**添加垂直约束（线段垂直）**  
`void vde_solver_add_vertical(VdeSolverHandle solver, int line_id)`  

| 参数 | 说明 |
|------|------|
| `solver` | 求解器句柄 |
| `line_id` | 线段 ID |

**参见**: `vde_solver_add_horizontal 水平约束`  


**求解约束系统**  
`int vde_solver_solve(VdeSolverHandle solver, int max_iter, double tol)`  

| 参数 | 说明 |
|------|------|
| `solver` | 求解器句柄 |
| `max_iter` | 最大迭代次数 |
| `tol` | 收敛容差 |

**返回**: 收敛返回 1，未收敛返回 0  

**参见**: `vde_solver_get_point 获取求解后的点坐标`  


**获取求解后的点坐标**  
`void vde_solver_get_point(VdeSolverHandle solver, int idx, double* out_x, double* out_y)`  

| 参数 | 说明 |
|------|------|
| `solver` | 求解器句柄 |
| `idx` | 点 ID |
| `out_x` | [out] 求解后 X 坐标 |
| `out_y` | [out] 求解后 Y 坐标 |


**释放求解器句柄**  
`void vde_solver_free(VdeSolverHandle solver)`  

| 参数 | 说明 |
|------|------|
| `solver` | 求解器句柄 |


**创建实心立方体 B-Rep**  
`VdeBodyHandle vde_body_create_box(VdeHandle ctx, double w, double h, double d)`  

| 参数 | 说明 |
|------|------|
| `ctx` | 引擎上下文句柄 |
| `w` | 宽度（X 方向），> 0 |
| `h` | 高度（Y 方向），> 0 |
| `d` | 深度（Z 方向），> 0 |

**返回**: B-Rep 实体句柄  

**参见**: `vde_body_create_cylinder 圆柱体`, `vde_body_create_sphere 球体`  


**创建实心圆柱体 B-Rep**  
`VdeBodyHandle vde_body_create_cylinder(VdeHandle ctx, double r, double h, int segs)`  

| 参数 | 说明 |
|------|------|
| `ctx` | 引擎上下文句柄 |
| `r` | 截面半径，> 0 |
| `h` | 总高度（从 -h/2 到 +h/2） |
| `segs` | 截面分段数（边数） |

**返回**: B-Rep 实体句柄  

**参见**: `vde_body_create_box 立方体`  


**创建球体 B-Rep**  
`VdeBodyHandle vde_body_create_sphere(VdeHandle ctx, double r, int su, int sv)`  

| 参数 | 说明 |
|------|------|
| `ctx` | 引擎上下文句柄 |
| `r` | 球半径，> 0 |
| `su` | 经度方向分段数 |
| `sv` | 纬度方向分段数 |

**返回**: B-Rep 实体句柄  


**将 B-Rep 实体转换为三角网格**  
`VdeMeshHandle vde_body_to_mesh(VdeHandle ctx, VdeBodyHandle body, double deflection)`  

| 参数 | 说明 |
|------|------|
| `ctx` | 引擎上下文句柄 |
| `body` | B-Rep 实体句柄 |
| `deflection` | 弦高误差（越小 = 越精细，推荐 0.01） |

**返回**: 三角网格句柄  

**参见**: `vde_body_free 释放 B-Rep 实体`  


**释放 B-Rep 实体句柄**  
`void vde_body_free(VdeBodyHandle body)`  

| 参数 | 说明 |
|------|------|
| `body` | B-Rep 实体句柄 |


**将网格序列化为二进制字节流**  
`size_t vde_serialize_mesh(VdeHandle ctx, VdeMeshHandle mesh, uint8_t** out_data)`  

| 参数 | 说明 |
|------|------|
| `ctx` | 引擎上下文句柄 |
| `mesh` | 网格句柄 |
| `out_data` | [out] 指向序列化字节数组的指针 |

**返回**: 字节数  
> 输出的缓冲区由库管理，调用方不得直接 free/delete。  

**参见**: `vde_deserialize_mesh 反序列化`, `vde_free_buffer 释放序列化缓冲区`  


**从二进制字节流反序列化为网格**  
`VdeMeshHandle vde_deserialize_mesh(VdeHandle ctx, const uint8_t* data, size_t len)`  

| 参数 | 说明 |
|------|------|
| `ctx` | 引擎上下文句柄 |
| `data` | 序列化数据缓冲区 |
| `len` | 数据长度（字节数） |

**返回**: 反序列化后的网格句柄  

**参见**: `vde_serialize_mesh 序列化`  


**释放由 vde_serialize_mesh 分配的缓冲区**  
`void vde_free_buffer(uint8_t* ptr)`  

| 参数 | 说明 |
|------|------|
| `ptr` | 由 vde_serialize_mesh 返回的缓冲区指针 |