茂之钳
486a0fe011
New structure: - docs/index.md — main navigation - docs/getting-started.md — 5-minute quick start - docs/guides/module-manual.md — all 11 modules with file listing - docs/guides/api-usage.md — API reference with code examples - docs/guides/ — architecture, building, testing, contributing - docs/reference/ — competitive analysis, gap analysis, versioning - docs/api/ — Doxygen generated HTML - docs/archive/ — historical development plans Old development plans archived. Clean 4-directory layout.
298 lines
14 KiB
Markdown
298 lines
14 KiB
Markdown
# API 总览
|
||
|
||
ViewDesignEngine 提供 C++17 头文件 API，所有公开接口位于 `include/vde/` 目录下。
|
||
|
||
## 模块 API 概览
|
||
|
||
### foundation — 基础设施 (`vde::foundation`)
|
||
|
||
```cpp
|
||
// 数学类型
|
||
#include <vde/foundation/point.h> // Point2D, Point3D, Vector2D, Vector3D
|
||
#include <vde/foundation/matrix.h> // Matrix3x3, Matrix4x4, Transform3D
|
||
#include <vde/foundation/aabb.h> // AABB2D, AABB3D
|
||
|
||
// 公差与精确谓词
|
||
#include <vde/foundation/tolerance.h> // Tolerance, is_zero(), is_equal()
|
||
#include <vde/foundation/exact_predicates.h> // orient2d, orient3d, incircle
|
||
|
||
// 格式 I/O
|
||
#include <vde/foundation/io_obj.h> // load_obj(), export_obj()
|
||
#include <vde/foundation/io_stl.h> // load_stl(), export_stl()
|
||
#include <vde/foundation/io_ply.h> // load_ply(), export_ply()
|
||
#include <vde/foundation/io_gltf.h> // export_gltf(), export_glb()
|
||
#include <vde/foundation/io_3mf.h> // load_3mf(), export_3mf()
|
||
#include <vde/foundation/industrial_formats.h> // STEP/IGES 导入导出
|
||
```
|
||
|
||
### core — 几何核心 (`vde::core`)
|
||
|
||
```cpp
|
||
#include <vde/core/polygon.h> // Polygon2D, triangulate(), simplify()
|
||
#include <vde/core/voronoi.h> // VoronoiDiagram2D
|
||
#include <vde/core/convex_hull.h> // convex_hull_2d(), convex_hull_3d()
|
||
#include <vde/core/distance.h> // point_to_line(), point_to_triangle()
|
||
#include <vde/core/icp.h> // icp_align()
|
||
#include <vde/core/cam_toolpath.h> // ToolPath, GCode, CLData
|
||
#include <vde/core/cam_strategies.h> // contour_toolpath, pocket_toolpath
|
||
#include <vde/core/cam_5axis.h> // 5轴联动: swarf, multi_axis_roughing
|
||
#include <vde/core/object_pool.h> // ObjectPool<T> 内存池
|
||
```
|
||
|
||
### curves — 曲线曲面 (`vde::curves`)
|
||
|
||
```cpp
|
||
#include <vde/curves/bezier_curve.h> // BezierCurve
|
||
#include <vde/curves/bspline_curve.h> // BSplineCurve
|
||
#include <vde/curves/nurbs_curve.h> // NurbsCurve
|
||
#include <vde/curves/bezier_surface.h> // BezierSurface
|
||
#include <vde/curves/bspline_surface.h> // BSplineSurface
|
||
#include <vde/curves/nurbs_surface.h> // NurbsSurface
|
||
#include <vde/curves/nurbs_operations.h> // offset, trim, blend, ruled, coons, extrude
|
||
#include <vde/curves/tessellation.h> // adaptive_tessellate()
|
||
#include <vde/curves/surface_intersection.h> // surface_intersect()
|
||
#include <vde/curves/surface_analysis.h> // curvature_analysis()
|
||
#include <vde/curves/surface_continuity.h>// G0/G1/G2 continuity check
|
||
#include <vde/curves/surface_fairing.h> // surface_fairing()
|
||
#include <vde/curves/exact_offset.h> // exact_offset_curve()
|
||
#include <vde/curves/surface_extension.h> // extend_surface()
|
||
#include <vde/curves/parallel_intersection.h> // parallel_intersect()
|
||
```
|
||
|
||
### mesh — 网格处理 (`vde::mesh`)
|
||
|
||
```cpp
|
||
#include <vde/mesh/halfedge_mesh.h> // HalfedgeMesh
|
||
#include <vde/mesh/delaunay_2d.h> // delaunay_2d(), cdt_2d()
|
||
#include <vde/mesh/delaunay_3d.h> // delaunay_3d()
|
||
#include <vde/mesh/mesh_simplify.h> // qem_simplify()
|
||
#include <vde/mesh/mesh_smooth.h> // laplacian_smooth(), hc_smooth(), bilateral_smooth()
|
||
#include <vde/mesh/mesh_boolean.h> // mesh_union(), mesh_intersection(), mesh_difference()
|
||
#include <vde/mesh/mesh_quality.h> // mesh_quality_report()
|
||
#include <vde/mesh/mesh_repair.h> // repair_non_manifold()
|
||
#include <vde/mesh/alpha_shapes.h> // alpha_shape()
|
||
#include <vde/mesh/mesh_parameterize.h> // parameterize()
|
||
#include <vde/mesh/geodesic.h> // geodesic_distance()
|
||
#include <vde/mesh/mesh_curvature.h> // curvature()
|
||
#include <vde/mesh/marching_cubes.h> // marching_cubes()
|
||
#include <vde/mesh/parallel_mc.h> // parallel_marching_cubes()
|
||
#include <vde/mesh/mesh_lod.h> // generate_lod()
|
||
#include <vde/mesh/reverse_engineering.h> // reverse_engineering pipeline
|
||
#include <vde/mesh/point_cloud.h> // PointCloud processing
|
||
#include <vde/mesh/fea_mesh.h> // FEA mesh generation
|
||
```
|
||
|
||
### spatial — 空间索引 (`vde::spatial`)
|
||
|
||
```cpp
|
||
#include <vde/spatial/bvh.h> // BVH<Triangle>
|
||
#include <vde/spatial/octree.h> // Octree<Point3D>
|
||
#include <vde/spatial/kd_tree.h> // KDTree<Point3D>
|
||
#include <vde/spatial/r_tree.h> // RTree<AABB3D>
|
||
#include <vde/spatial/incremental_bvh.h> // IncrementalBVH
|
||
```
|
||
|
||
### boolean — 布尔运算 (`vde::boolean`)
|
||
|
||
```cpp
|
||
#include <vde/boolean/boolean_2d.h> // clip_polygon(), boolean_2d()
|
||
#include <vde/boolean/boolean_mesh.h> // mesh_union(), mesh_difference(), mesh_intersection()
|
||
#include <vde/boolean/polygon_offset.h> // offset_polygon()
|
||
```
|
||
|
||
### collision — 碰撞检测 (`vde::collision`)
|
||
|
||
```cpp
|
||
#include <vde/collision/gjk.h> // gjk_distance(), gjk_intersect()
|
||
#include <vde/collision/sat.h> // sat_intersect()
|
||
#include <vde/collision/ray_intersect.h> // ray_triangle(), ray_aabb(), ray_mesh()
|
||
#include <vde/collision/tri_intersect.h> // tri_tri_intersection()
|
||
```
|
||
|
||
### brep — B-Rep 建模 (`vde::brep`)
|
||
|
||
```cpp
|
||
#include <vde/brep/brep.h> // BrepModel, TopoVertex, TopoEdge, TopoFace
|
||
#include <vde/brep/modeling.h> // make_box, make_sphere, fillet, chamfer, shell
|
||
#include <vde/brep/brep_boolean.h> // brep_union, brep_intersection, brep_difference
|
||
#include <vde/brep/brep_validate.h> // validate()
|
||
#include <vde/brep/brep_heal.h> // heal()
|
||
#include <vde/brep/tolerance.h> // Tolerance settings
|
||
#include <vde/brep/trimmed_surface.h> // TrimmedSurface
|
||
#include <vde/brep/ssi_boolean.h> // Surface-surface intersection boolean
|
||
#include <vde/brep/format_io.h> // STEP/IGES import/export
|
||
#include <vde/brep/measure.h> // distance, surface_area, volume, centroid
|
||
#include <vde/brep/brep_drawing.h> // Drawing generation
|
||
#include <vde/brep/auto_dimensioning.h> // Automatic dimensioning
|
||
#include <vde/brep/pmi_mbd.h> // PMI/MBD annotations
|
||
#include <vde/brep/gdt.h> // GD&T annotations
|
||
#include <vde/brep/euler_op.h> // Euler operators
|
||
#include <vde/brep/draft_analysis.h> // Draft angle analysis
|
||
#include <vde/brep/feature_recognition.h> // Feature recognition
|
||
#include <vde/brep/defeature.h> // Defeaturing
|
||
#include <vde/brep/advanced_blend.h> // Advanced blending
|
||
#include <vde/brep/ffd_deformation.h> // Free-form deformation
|
||
#include <vde/brep/constraint_solver.h> // Assembly constraint solving
|
||
#include <vde/brep/direct_modeling.h> // Direct modeling
|
||
#include <vde/brep/kinematic_chain.h> // Kinematic chains
|
||
#include <vde/brep/motion_simulation.h> // Motion simulation
|
||
#include <vde/brep/assembly_lod.h> // Assembly LOD
|
||
#include <vde/brep/fastener_library.h> // Fastener library
|
||
```
|
||
|
||
### sdf — 隐式建模 (`vde::sdf`)
|
||
|
||
```cpp
|
||
#include <vde/sdf/sdf_primitives.h> // sphere, box, cylinder, torus, cone, etc.
|
||
#include <vde/sdf/sdf_operations.h> // union, intersection, difference, smooth_union
|
||
#include <vde/sdf/sdf_tree.h> // SdfNode, evaluate()
|
||
#include <vde/sdf/sdf_to_mesh.h> // sdf_to_mesh()
|
||
#include <vde/sdf/sdf_gradient.h> // gradient()
|
||
#include <vde/sdf/sdf_optimize.h> // fit_to_point_cloud(), optimize()
|
||
```
|
||
|
||
### sketch — 草图约束 (`vde::sketch`)
|
||
|
||
```cpp
|
||
#include <vde/sketch/constraint_solver.h> // ConstraintSolver
|
||
```
|
||
|
||
### plugin — 插件系统 (`vde::plugin`, v6.0+)
|
||
|
||
```cpp
|
||
#include <vde/plugin/plugin_system.h> // PluginInterface, PluginManager, PluginManifest
|
||
```
|
||
|
||
详见 [插件系统设计](plugin-system.md)。
|
||
|
||
## 模块间依赖关系
|
||
|
||
ViewDesignEngine 采用分层架构，模块间依赖严格单向，杜绝循环依赖。
|
||
|
||
```
|
||
┌─────────────────────────────────┐
|
||
│ vde (聚合接口库) │
|
||
└──────────────┬──────────────────┘
|
||
┌────────────────────────┼────────────────────────┐
|
||
│ │ │
|
||
┌────────┴────────┐ ┌────────┴────────┐ ┌────────┴────────┐
|
||
│ vde_capi │ │ vde_brep │ │ vde_plugin │
|
||
│ (C ABI 出口) │ │ (B-Rep 建模) │ │ (v6.0+ 插件) │
|
||
└────────┬────────┘ └────────┬────────┘ └────────┬────────┘
|
||
│ │ │
|
||
┌─────────┼───────────────┬───────┼───────┬───────────────┘
|
||
│ │ │ │ │
|
||
▼ ▼ ▼ ▼ ▼
|
||
┌──────────┐┌──────────┐┌──────────┐┌──────────┐┌──────────┐
|
||
│ vde_sdf ││vde_sketch││vde_curves││vde_mesh ││vde_ │
|
||
│隐式建模 ││草图约束 ││曲线曲面 ││网格处理 ││collision │
|
||
└────┬─────┘└────┬─────┘└────┬─────┘└────┬─────┘└────┬─────┘
|
||
│ │ │ │ │
|
||
└───────────┴───────────┼───────────┴───────────┘
|
||
│
|
||
┌─────────┴──────────┐
|
||
│ │
|
||
┌─────┴─────┐ ┌─────┴─────┐
|
||
│ vde_core │ │vde_spatial│
|
||
│ 几何核心 │ │ 空间索引 │
|
||
└─────┬─────┘ └─────┬─────┘
|
||
│ │
|
||
└──────────┬─────────┘
|
||
│
|
||
┌──────────┴──────────┐
|
||
│ vde_foundation │
|
||
│ 基础设施层 │
|
||
└──────────┬──────────┘
|
||
│
|
||
┌──────────┴──────────┐
|
||
│ Eigen3 (外部依赖) │
|
||
└─────────────────────┘
|
||
```
|
||
|
||
### 依赖矩阵
|
||
|
||
| 模块 | foundation | core | spatial | curves | mesh | collision | boolean | brep | sdf | sketch |
|
||
|------|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
|
||
| **foundation** | — | — | — | — | — | — | — | — | — | — |
|
||
| **core** | ✅ | — | — | — | — | — | — | — | — | — |
|
||
| **spatial** | — | ✅ | — | — | — | — | — | — | — | — |
|
||
| **curves** | — | ✅ | — | — | — | — | — | — | — | — |
|
||
| **mesh** | — | ✅ | — | — | — | — | — | ✅¹ | — | — |
|
||
| **collision** | — | ✅ | ✅ | — | — | — | — | — | — | — |
|
||
| **boolean** | — | ✅ | ✅ | — | ✅ | — | — | — | — | — |
|
||
| **brep** | — | — | — | ✅ | ✅ | ✅ | — | — | — | — |
|
||
| **sdf** | — | ✅ | — | — | ✅ | — | — | — | — | — |
|
||
| **sketch** | — | ✅ | — | — | — | — | — | — | — | — |
|
||
| **capi** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
|
||
| **plugin** | ✅ | — | — | — | — | — | — | — | — | — |
|
||
|
||
> ¹ vde_mesh → vde_brep 依赖仅用于拓扑转换（BrepModel → HalfedgeMesh），是单向弱依赖。
|
||
|
||
### 层次说明
|
||
|
||
| 层 | 模块 | 职责 | 上游依赖数 |
|
||
|----|------|------|:--------:|
|
||
| L0 基础 | foundation | 数学类型、I/O、公差、精确谓词 | 0 (仅 Eigen) |
|
||
| L1 核心 | core, spatial | 几何算法 + 空间索引 | 1 |
|
||
| L2 曲面 | curves | 曲线曲面计算 | 1 |
|
||
| L3 网格 | mesh | 网格处理与重建 | 2 |
|
||
| L4 检测 | collision, boolean | 碰撞检测、布尔运算 | 2–3 |
|
||
| L5 领域 | brep, sdf, sketch | 高层建模 | 3–4 |
|
||
| L6 出口 | capi, plugin | 跨语言接口、扩展机制 | 0–10 |
|
||
|
||
## 核心类型速查
|
||
|
||
| 类型 | 命名空间 | 说明 |
|
||
|------|---------|------|
|
||
| `Point2D` / `Point3D` | `vde::core` | 2D/3D 点 |
|
||
| `Vector2D` / `Vector3D` | `vde::core` | 2D/3D 向量 |
|
||
| `AABB2D` / `AABB3D` | `vde::core` | 轴对齐包围盒 |
|
||
| `Matrix3x3` / `Matrix4x4` | `vde::core` | 3x3 / 4x4 变换矩阵 |
|
||
| `Triangle` | `vde::core` | 三角形 |
|
||
| `HalfedgeMesh` | `vde::mesh` | 半边网格数据结构 |
|
||
| `BrepModel` | `vde::brep` | B-Rep 实体模型 |
|
||
| `SdfNode` | `vde::sdf` | SDF 场景图节点 |
|
||
| `BezierCurve` | `vde::curves` | Bézier 曲线 |
|
||
| `NurbsSurface` | `vde::curves` | NURBS 曲面 |
|
||
|
||
## 使用约定
|
||
|
||
### 头文件包含
|
||
|
||
```cpp
|
||
// 推荐：只包含需要的头文件
|
||
#include <vde/mesh/halfedge_mesh.h>
|
||
#include <vde/core/point.h>
|
||
|
||
// 不推荐：包含聚合头（编译慢）
|
||
// #include <vde/vde.h> // 不存在此文件
|
||
```
|
||
|
||
### 命名空间使用
|
||
|
||
```cpp
|
||
// .cpp 文件中可以使用 using
|
||
using namespace vde::core;
|
||
using namespace vde::mesh;
|
||
|
||
// .h 文件中禁止 using namespace
|
||
// 使用完整限定名或在作用域内声明
|
||
namespace vde::my_module {
|
||
using vde::core::Point3D;
|
||
}
|
||
```
|
||
|
||
### 错误处理
|
||
|
||
VDE 采用以下错误处理策略：
|
||
- **返回值**: 大部分函数返回 `std::optional<T>` 或错误码
|
||
- **断言**: 内部不变量使用 `assert()`
|
||
- **异常**: 仅在构造函数/资源分配失败时使用（RAII 保证）
|
||
- **日志**: 通过 `VDE_LOG_WARNING` / `VDE_LOG_ERROR` 宏
|
||
|
||
### 线程安全
|
||
|
||
- 所有 `const` 方法可并发调用
|
||
- 非 `const` 方法需要外部同步
|
||
- PluginManager 提供内部读写锁
|