# API 参考

## 目录

1. [命名空间](#1-命名空间)
2. [core 模块](#2-core-模块)
3. [curves 模块](#3-curves-模块)
4. [mesh 模块](#4-mesh-模块)
5. [spatial 模块](#5-spatial-模块)
6. [boolean 模块](#6-boolean-模块)
7. [collision 模块](#7-collision-模块)
8. [foundation 模块](#8-foundation-模块)
9. [错误码](#9-错误码)

---

## 1. 命名空间

```cpp
namespace vde::foundation { ... }   // 基础设施
namespace vde::core { ... }         // 几何核心
namespace vde::curves { ... }       // 曲线曲面
namespace vde::mesh { ... }         // 网格处理
namespace vde::spatial { ... }      // 空间索引
namespace vde::boolean { ... }      // 布尔运算
namespace vde::collision { ... }    // 碰撞检测
```

---

## 2. core 模块

### 基本类型

| 类型 | 说明 |
|------|------|
| `Point2D`, `Point3D` | 二维/三维点 |
| `Vector2D`, `Vector3D` | 二维/三维向量 |
| `Line3Dd` | 三维无限直线 |
| `Ray3Dd` | 三维射线 |
| `Segment3Dd` | 三维线段 |
| `Plane3D` | 三维平面 |
| `Triangle3D` | 三维三角形 |
| `AABB3D` | 轴对齐包围盒 |

### 变换

```cpp
Transform3D translate(double x, double y, double z);
Transform3D rotate(const Vector3D& axis, double rad);
Transform3D scale(double sx, double sy, double sz);

// 组合
Matrix4D m = rotate_x(90_deg) * translate(1, 0, 0);
Point3D p2 = m * p1;
```

### 凸包与距离

```cpp
// 2D 凸包（Graham Scan）
std::vector<Point2D> convex_hull_2d(const std::vector<Point2D>& pts);

// 距离计算
double distance(const Point3D& a, const Point3D& b);
double distance(const Point3D& p, const Plane3D& plane);
double distance(const Point3D& p, const Triangle3D& tri);
Point3D closest_point(const Point3D& p, const Triangle3D& tri);
```

---

## 3. curves 模块

```cpp
// 曲线构造
BezierCurve bezier(control_points);
NurbsCurve nurbs(control_points, knots, weights, degree);

// 求值与求导
Point3D p = curve.evaluate(t);
Vector3D d1 = curve.derivative(t, 1);

// 曲面
NurbsSurface surface(grid, knots_u, knots_v, weights, deg_u, deg_v);
Point3D p = surface.evaluate(u, v);

// 离散化
auto [verts, tris] = tessellate(eval_func, res_u, res_v);
```

---

## 4. mesh 模块

```cpp
HalfedgeMesh mesh;

// 查询
size_t nv = mesh.num_vertices();
const Point3D& v = mesh.vertex(idx);

// Delaunay
auto [verts, tris] = delaunay_2d(points);

// 简化与平滑
auto simplified = simplify_mesh(mesh, {.target_ratio = 0.5});
auto smoothed = smooth_mesh(mesh, {.iterations = 10});

// 质量评估
auto quality = evaluate_mesh_quality(mesh);
```

---

## 5. spatial 模块

```cpp
BVH bvh;
bvh.build(triangles);

auto hits = bvh.query_ray(ray);           // 所有命中
auto nearest = bvh.query_ray_nearest(ray); // 最近命中
auto in_box = bvh.query_range(aabb);       // 范围查询
auto knn = bvh.query_knn(point, 5);        // K 近邻
```

---

## 6. boolean 模块

```cpp
// 2D 多边形布尔
auto result = boolean_2d(poly_a, poly_b, BooleanOp::Union);
auto result = boolean_2d(poly_a, poly_b, BooleanOp::Intersection);
auto result = boolean_2d(poly_a, poly_b, BooleanOp::Difference);
```

---

## 7. collision 模块

```cpp
// GJK 碰撞检测
bool hit = gjk_intersect(convex_a, convex_b);

// 射线-三角形相交（Möller-Trumbore）
auto hit = ray_triangle_intersect(ray, tri);
// hit->t, hit->point, hit->u, hit->v

// 三角形-三角形相交
bool hit = tri_tri_intersect(t1, t2);
```

---

## 8. foundation 模块

### 公差系统

```cpp
Tolerance tol(/* absolute */ 1e-6, /* relative */ 1e-8);
bool eq = tol.points_equal(a, b);
bool zero = tol.is_zero(value);
```

### 精确谓词

```cpp
auto orient = exact::orient_2d(a, b, c);
auto in = exact::in_circle(a, b, c, d);
```

### I/O

```cpp
auto mesh = read_obj("model.obj");
write_obj(mesh, "output.obj");
auto tris = read_stl("model.stl");
```

---

## 9. 错误码

| 错误码 | 说明 |
|--------|------|
| `kSuccess` | 操作成功 |
| `kInvalidArgument` | 非法参数 |
| `kInvalidGeometry` | 非法几何（退化/非流形） |
| `kDegenerateCase` | 退化情况 |
| `kNotImplemented` | 未实现 |
| `kNumericalError` | 数值计算错误 |
| `kOutOfMemory` | 内存不足 |