ViewDesignEngine/docs/guides/api-usage.md

# API 使用手册

> 常用 API 速查与代码示例

## 命名约定

```cpp
namespace vde::brep   { /* B-Rep 建模 */ }
namespace vde::curves { /* 曲线曲面 */ }
namespace vde::mesh   { /* 网格处理 */ }
namespace vde::core   { /* 基础类型 */ }
namespace vde::foundation { /* IO格式 */ }

// 基础类型
using core::Point3D;    // 3D点，.x() .y() .z()
using core::Vector3D;   // 3D向量，.dot() .cross() .norm() .normalized()
using core::AABB3D;     // 包围盒，.min() .max() .extent() .intersects() .expand()
```

---

## B-Rep 建模

### 创建基本体

```cpp
#include <vde/brep/modeling.h>
using namespace vde::brep;

auto box     = make_box(2, 3, 4);         // 宽×深×高
auto cyl     = make_cylinder(1.5, 6, 32); // 半径, 高度, 分段
auto sphere  = make_sphere(2, 32, 16);    // 半径, u分段, v分段

// 查询
size_t n_faces = box.num_faces();
auto bb = box.bounds();                   // AABB3D
auto mesh = box.to_mesh(0.01);            // HalfedgeMesh
```

### 布尔运算

```cpp
#include <vde/brep/brep_boolean.h>

auto result_union        = brep_union(a, b);
auto result_intersection = brep_intersection(a, b);
auto result_difference   = brep_difference(a, b);
```

### 拓扑修复与验证

```cpp
#include <vde/brep/brep_heal.h>
#include <vde/brep/brep_validate.h>

heal_topology(body);           // 一站式修复
heal_gaps(body, 1e-6);        // 合并临近顶点
heal_orientation(body);       // 统一面方向

auto report = validate(body);  // 验证
// report.valid, report.errors, report.warnings
```

### 直接建模

```cpp
#include <vde/brep/direct_modeling.h>

push_pull(body, face_id, 5.0);   // 挤出5mm
tweak_face(body, face_id, 2.0);  // 面偏移2mm
move_face(body, face_id, transform);
scale_body(body, {2, 1, 1});     // X方向放大2倍
mirror_body(body, plane);        // 镜像
```

---

## 曲线曲面

### NURBS 曲面操作

```cpp
#include <vde/curves/nurbs_surface.h>
#include <vde/curves/generative_surfaces.h>
using namespace vde::curves;

// 创建
auto ruled  = NurbsSurface::ruled(curve1, curve2);
auto rev    = NurbsSurface::revolve(profile, origin, axis, M_PI);

// 求值
Point3D p = surf.evaluate(0.5, 0.5);
Vector3D n = surf.normal(0.5, 0.5);

// 生成曲面
auto swept = sweep_surface(profile, path, SweepMode::Explicit);
auto lofted = loft_surface(sections);       // 放样
auto netted = net_surface(u_curves, v_curves); // 网格面
```

### 曲面编辑

```cpp
#include <vde/curves/surface_editing.h>

auto matched = match_surface(target, reference, edge, Continuity::G2);
auto edited  = control_point_edit(surf, {0,0}, new_pos);
```

### 曲面分析

```cpp
#include <vde/curves/surface_analysis.h>
#include <vde/curves/surface_continuity.h>

auto cmap = curvature_map(surf, 64, 64);     // 曲率图
auto zebra = zebra_stripe(surf, light_dir);   // 斑马纹
auto cont = surface_continuity(a, b, edge);   // 连续性分析
```

---

## 格式 IO

### STEP/IGES

```cpp
#include <vde/foundation/io_step.h>
#include <vde/foundation/io_iges.h>

auto body = import_step_file("input.step");
auto body = import_step_string(step_data);
export_step_file(body, "output.step");

auto body = import_iges_file("input.igs");
export_iges_file(body, "output.igs");
```

### 工业格式

```cpp
#include <vde/foundation/industrial_formats.h>
using namespace vde::io;

auto body  = import_parasolid_xt("model.x_t");  // Parasolid XT
auto body  = import_acis_sat("model.sat");       // ACIS SAT
auto body  = import_jt("model.jt");              // JT
auto body  = import_ifc("building.ifc");         // IFC
export_jt(body, "output.jt");
```

### 网格格式

```cpp
// STL/OBJ/PLY/glTF/3MF 均在 foundation 模块
#include <vde/foundation/io_stl.h>
#include <vde/foundation/io_gltf.h>

export_stl_binary(mesh, "output.stl");
export_gltf(mesh, "output.glb");   // glTF Binary
```

---

## CAM 加工

```cpp
#include <vde/core/cam_strategies.h>
#include <vde/core/cam_5axis.h>
using namespace vde::core;

Tool tool{ToolType::ENDMILL, 10.0, 4, 50.0};  // 直径10mm 4刃

// 3轴
auto rough = roughing_toolpath(body, tool, RoughingParams{});
auto finish = finishing_toolpath(body, tool, FinishingParams{});
auto drill = drilling_toolpath(points, tool, {5, 10, 15});

// 5轴
auto swarf = swarf_machining(surface, tool, SwarfParams{});
auto m5 = multi_axis_finishing(surface, tool, MultiAxisParams{});

// 后处理
FanucPost post;
auto gcode = post.generate(toolpath);
```

---

## 装配体

```cpp
#include <vde/brep/assembly.h>
#include <vde/brep/constraint_solver.h>

Assembly assy{"robot_arm"};
assy.root().add_part("base", make_box(10, 10, 2));
auto* arm = assy.root().add_subassembly("arm", Transform3D::Translation(0,0,2));
arm->add_part("link", make_cylinder(0.5, 8));

// 约束
ConstraintGraph graph;
graph.add_constraint("base", "arm", ConstraintType::Coincident, ...);
solve_constraints(graph);
```

---

## 网格处理

```cpp
#include <vde/mesh/halfedge_mesh.h>
#include <vde/mesh/mesh_simplify.h>
#include <vde/mesh/marching_cubes.h>

// 简化
auto simplified = simplify_mesh(mesh, 0.5);  // 保留50%面

// 平滑
auto smoothed = laplacian_smooth(mesh, 10);

// SDF → Mesh
auto mesh = marching_cubes(sdf_function, bounds, 64);

// FEA网格
auto tets = tetrahedral_mesh(body, TetraParams{});
auto hex = mapped_hex_mesh(body, source_face, target_face);
```

---

## 点云/逆向工程

```cpp
#include <vde/mesh/point_cloud.h>
#include <vde/mesh/reverse_engineering.h>

PointCloud cloud;
cloud.load_ply("scan.ply");
cloud.voxel_downsample(0.5);
cloud.estimate_normals(16);

auto mesh = point_cloud_to_mesh(cloud);
auto surf = mesh_to_nurbs_surface(mesh);
```

---

## 性能调优

```cpp
#include <vde/core/performance_tuning.h>

// 设置线程数
set_parallel_threads(8);

// 使用内存池
ObjectPool<Point3D> pool;
auto* p = pool.acquire();
pool.release(p);

// 事务
Transaction txn;
txn.begin();
// ... 操作 ...
txn.commit();  // 或 txn.rollback();
```