ViewDesignEngine/docs/dev-guide/api-overview.md

API 总览

ViewDesignEngine 提供 C++17 头文件 API，所有公开接口位于 include/vde/ 目录下。

模块 API 概览

foundation — 基础设施 (vde::foundation)

// 数学类型
#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)

#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)

#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)

#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)

#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)

#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)

#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)

#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)

#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)

#include <vde/sketch/constraint_solver.h> // ConstraintSolver

plugin — 插件系统 (vde::plugin, v6.0+)

#include <vde/plugin/plugin_system.h>   // PluginInterface, PluginManager, PluginManifest

详见 插件系统设计。

核心类型速查

类型	命名空间	说明
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 曲面

使用约定

头文件包含

// 推荐：只包含需要的头文件
#include <vde/mesh/halfedge_mesh.h>
#include <vde/core/point.h>

// 不推荐：包含聚合头（编译慢）
// #include <vde/vde.h>  // 不存在此文件

命名空间使用

// .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 提供内部读写锁