diff --git a/docs/00-文档目录.md b/docs/00-文档目录.md index a73bb06..467036d 100644 --- a/docs/00-文档目录.md +++ b/docs/00-文档目录.md @@ -6,30 +6,40 @@ |------|------|------| | **第一阶段：需求分析** | | | | 01 | [市场调研与竞品分析](01-需求分析/01-市场调研与竞品分析.md) | CGAL、OCCT、libigl 等 7 个引擎对标 | -| 02 | [需求规格说明书](01-需求分析/02-需求规格说明书.md) | 10 类功能需求 + 5 类非功能需求 | +| 02 | [需求规格说明书](01-需求分析/02-需求规格说明书.md) | 14 类功能需求 + 5 类非功能需求（v1.0 完整版） | | 03 | [用例文档](01-需求分析/03-用例文档.md) | 6 个核心用例场景 | +| 04 | [功能差距分析](01-需求分析/04-功能差距分析.md) | 41 项功能差距，5 级优先级，分版本路线 | | **第二阶段：概要设计** | | | -| 04 | [系统架构设计](02-概要设计/01-系统架构设计.md) | 7 层模块架构 + 数据流 + 设计原则 | -| 05 | [模块划分](02-概要设计/02-模块划分.md) | 7 个模块详细组件清单与依赖关系 | -| 06 | [接口定义](02-概要设计/03-接口定义.md) | C++ 虚接口抽象 + C API + 错误处理约定 | +| 05 | [系统架构设计](02-概要设计/01-系统架构设计.md) | 7 层模块架构 + 数据流 + 设计原则 | +| 06 | [模块划分](02-概要设计/02-模块划分.md) | 7 个模块详细组件清单与依赖关系 | +| 07 | [接口定义](02-概要设计/03-接口定义.md) | C++ 虚接口抽象 + C API + 错误处理约定 | | **第三阶段：详细设计** | | | -| 07 | [数据结构设计](03-详细设计/01-数据结构设计.md) | 半边网格、NURBS、BVH、公差系统 | -| 08 | [核心算法设计](03-详细设计/02-核心算法设计.md) | Delaunay、GJK、QEM、SAH 等算法伪代码 | -| 09 | [类设计](03-详细设计/03-类设计.md) | 类关系图、工厂模式、策略模式、访问者模式 | +| 08 | [数据结构设计](03-详细设计/01-数据结构设计.md) | 半边网格、NURBS、BVH、公差系统 | +| 09 | [核心算法设计](03-详细设计/02-核心算法设计.md) | Delaunay、GJK、QEM、SAH 等算法伪代码 | +| 10 | [类设计](03-详细设计/03-类设计.md) | 类关系图、工厂模式、策略模式、访问者模式 | | **第四阶段：编码实现** | | | -| 10 | [编码规范](04-编码实现/01-编码规范.md) | C++17 命名、格式、注释、内存、错误处理规范 | -| 11 | [目录结构](04-编码实现/02-目录结构.md) | 完整工程目录树 + CMakeLists.txt 骨架 | +| 11 | [编码规范](04-编码实现/01-编码规范.md) | C++17 命名、格式、注释、内存、错误处理规范 | +| 12 | [目录结构](04-编码实现/02-目录结构.md) | 完整工程目录树 + CMakeLists.txt 骨架 | | **第五阶段：测试验证** | | | -| 12 | [测试计划](05-测试验证/01-测试计划.md) | 测试策略、CI 流程、性能基准、回归测试 | -| 13 | [测试用例](05-测试验证/02-测试用例.md) | 8 组详细测试用例，含输入/预期输出 | +| 13 | [测试计划](05-测试验证/01-测试计划.md) | 测试策略、CI 流程、性能基准、回归测试 | +| 14 | [测试用例](05-测试验证/02-测试用例.md) | 8 组详细测试用例，含输入/预期输出 | | **第六阶段：部署维护** | | | -| 14 | [构建指南](06-部署维护/01-构建指南.md) | Linux/Win/macOS 构建 + FetchContent 集成 | -| 15 | [API 参考](06-部署维护/02-API参考.md) | 7 个模块全部公开 API 签名 | +| 15 | [构建指南](06-部署维护/01-构建指南.md) | Linux/Win/macOS 构建 + FetchContent 集成 | +| 16 | [API 参考](06-部署维护/02-API参考.md) | 7 个模块全部公开 API 签名 | + +## 版本路线 + +``` +v0.1.0 v0.3.0 v0.5.0 v1.0.0 v2.0.0 + ✅ 已完成 → P0 核心缺口 → P1 算法广度 → P2 B-Rep → P4 高级功能 + 追上 Clipper2 追上 Manifold 追上 OCCT 追上 CGAL + + Manifold + libigl 建模层 高级 +``` ## 技术栈 - **语言**: C++17 - **构建**: CMake 3.16+ -- **依赖**: Eigen 3.3+（唯一必需依赖） +- **依赖**: Eigen 3.3+ - **测试**: Google Test - **许可证**: Apache 2.0 diff --git a/docs/01-需求分析/02-需求规格说明书.md b/docs/01-需求分析/02-需求规格说明书.md index 98375cf..27b8e49 100644 --- a/docs/01-需求分析/02-需求规格说明书.md +++ b/docs/01-需求分析/02-需求规格说明书.md @@ -1,10 +1,25 @@ -# 需求规格说明书 +# 需求规格说明书（v1.0 完整版） ## 目录 1. [引言](#1-引言) 2. [功能需求](#2-功能需求) + - FR-01 基本几何类型 + - FR-02 几何变换 + - FR-03 曲线建模 + - FR-04 曲面建模 + - FR-05 网格处理 + - FR-06 布尔运算 + - FR-07 空间索引 + - FR-08 碰撞检测 + - FR-09 几何计算 + - FR-10 公差与精度 + - FR-11 B-Rep 实体建模 + - FR-12 离散化与重建 + - FR-13 数据交换 + - FR-14 高级算法 3. [非功能需求](#3-非功能需求) +4. [版本规划](#4-版本规划) --- @@ -12,126 +27,213 @@ ### 1.1 目的 -本文档定义 ViewDesignEngine 几何算法引擎的功能需求与非功能需求，作为后续设计、实现与测试的基线。 +本文档定义 ViewDesignEngine 几何算法引擎的完整功能需求与非功能需求，覆盖 v0.1.0 到 v2.0.0 的全部规划。 ### 1.2 范围 -本引擎提供底层几何计算能力，覆盖二维和三维空间的基础几何运算、曲线曲面建模、网格处理、布尔运算、空间索引和碰撞检测。 +对标 CGAL + OCCT + Manifold + Clipper2 + libigl 五个引擎的核心功能交集，提供从基础几何运算到工业级 B-Rep 建模的全栈几何计算能力。 -### 1.3 术语定义 +### 1.3 对标基线 + +> 前置阅读：[市场调研与竞品分析](01-市场调研与竞品分析.md) | [功能差距分析](04-功能差距分析.md) + +| 竞品 | 对标方向 | 差距项数 | +|------|---------|---------| +| Clipper2 | 2D 布尔精度与速度 | 2 | +| Manifold | 3D 网格布尔速度与鲁棒性 | 2 | +| libigl | 网格处理完整度 | 5 | +| OCCT | B-Rep 建模能力 | 7 | +| CGAL | 算法广度 | 8 | + +### 1.4 术语 | 术语 | 定义 | |------|------| | CSG | 构造实体几何（Constructive Solid Geometry） | -| NURBS | 非均匀有理 B 样条（Non-Uniform Rational B-Spline） | -| BVH | 包围体层次结构（Bounding Volume Hierarchy） | -| GJK | Gilbert-Johnson-Keerthi 碰撞检测算法 | -| Delaunay | Delaunay 三角剖分 | -| B-Rep | 边界表示法（Boundary Representation） | -| QEM | 二次误差度量（Quadric Error Metrics） | +| NURBS | 非均匀有理 B 样条 | +| BVH | 包围体层次结构 | +| GJK/EPA | GJK 碰撞检测 + EPA 穿透深度 | +| QEM | 二次误差度量（网格简化） | +| B-Rep | 边界表示法 | +| CDT | 约束 Delaunay 三角剖分 | +| Vatti | Vatti 扫描线算法（2D 布尔黄金标准） | --- ## 2. 功能需求 +> 标记说明：✅ 已实现 🔨 实现中 📋 已规划 🔜 远期目标 + ### FR-01：基本几何类型 -| 编号 | 需求 | 优先级 | -|------|------|--------| -| FR-01.1 | Point2D / Point3D：二维/三维点，支持算术运算 | P0 | -| FR-01.2 | Vector2D / Vector3D：向量运算（加减、点积、叉积、归一化） | P0 | -| FR-01.3 | Line2D / Line3D / Ray / Segment：直线、射线、线段 | P0 | -| FR-01.4 | Plane：平面定义与运算 | P0 | -| FR-01.5 | Triangle / Polygon：三角形与多边形（法向量、面积、点包含判断） | P0 | -| FR-01.6 | BoundingBox：轴对齐包围盒（AABB）与定向包围盒（OBB） | P0 | +| 编号 | 需求 | 对标 | 状态 | +|------|------|------|------| +| FR-01.1 | Point2D / Point3D | CGAL Kernel | ✅ | +| FR-01.2 | Vector2D / Vector3D（点积/叉积/归一化） | CGAL Kernel | ✅ | +| FR-01.3 | Line / Ray / Segment | CGAL Kernel | ✅ | +| FR-01.4 | Plane（法向量 + 有符号距离） | CGAL Kernel | ✅ | +| FR-01.5 | Triangle（面积/法向量/重心坐标/点包含） | CGAL Kernel | ✅ | +| FR-01.6 | Polygon2D（面积/点包含/CCW 判断） | CGAL Kernel | ✅ | +| FR-01.7 | AABB（轴对齐包围盒） | CGAL Kernel | ✅ | +| FR-01.8 | OBB（定向包围盒） | CGAL Optimal Bounding Box | 🔜 P4 | ### FR-02：几何变换 -| 编号 | 需求 | 优先级 | -|------|------|--------| -| FR-02.1 | 平移、旋转、缩放 | P0 | -| FR-02.2 | 变换矩阵（4×4 齐次坐标） | P0 | -| FR-02.3 | 组合变换（变换链） | P1 | -| FR-02.4 | 反射、剪切、投影 | P2 | +| 编号 | 需求 | 对标 | 状态 | +|------|------|------|------| +| FR-02.1 | 平移/旋转/缩放（3D） | CGAL Kernel | ✅ | +| FR-02.2 | 4×4 齐次变换矩阵 | Eigen | ✅ | +| FR-02.3 | 组合变换链 | CGAL | ✅ | +| FR-02.4 | 反射/镜像变换 | CGAL | 📋 P1 | ### FR-03：曲线建模 -| 编号 | 需求 | 优先级 | -|------|------|--------| -| FR-03.1 | Bezier 曲线（任意阶） | P0 | -| FR-03.2 | B-Spline 曲线 | P0 | -| FR-03.3 | NURBS 曲线 | P0 | -| FR-03.4 | 曲线求值（de Casteljau / Cox-de Boor 算法） | P0 | -| FR-03.5 | 曲线求导（一阶/二阶导数） | P1 | -| FR-03.6 | 曲线分割与拼接 | P1 | -| FR-03.7 | 弧长参数化 | P2 | +| 编号 | 需求 | 对标 | 状态 | +|------|------|------|------| +| FR-03.1 | Bezier 曲线（任意阶） | CGAL | ✅ | +| FR-03.2 | B-Spline 曲线 | CGAL | ✅ | +| FR-03.3 | NURBS 曲线（Cox-de Boor 求值） | CGAL NURBS | ✅ | +| FR-03.4 | 曲线一阶/二阶导数 | CGAL | 🔨 部分实现 | +| FR-03.5 | 曲线分割与拼接 | CGAL | 📋 P2 | +| FR-03.6 | 曲线升阶 | CGAL | 📋 P2 | +| FR-03.7 | 曲线弧长参数化 | CGAL | 📋 P2 | +| FR-03.8 | 曲线-曲线求交 | CGAL | 📋 P2 | +| FR-03.9 | 曲线投影（点到曲线最近点） | CGAL | 📋 P2 | ### FR-04：曲面建模 -| 编号 | 需求 | 优先级 | -|------|------|--------| -| FR-04.1 | Bezier 曲面 | P1 | -| FR-04.2 | B-Spline 曲面 | P1 | -| FR-04.3 | NURBS 曲面 | P1 | -| FR-04.4 | 曲面求值与求导 | P1 | -| FR-04.5 | 曲面离散化（三角网格化） | P1 | +| 编号 | 需求 | 对标 | 状态 | +|------|------|------|------| +| FR-04.1 | Bezier 曲面 | CGAL | ✅ | +| FR-04.2 | B-Spline 曲面 | CGAL | ✅ | +| FR-04.3 | NURBS 曲面（张量积） | CGAL / OCCT | 🔨 部分实现 | +| FR-04.4 | 曲面求值与求导 | CGAL | 🔨 | +| FR-04.5 | 曲面法向量计算 | CGAL | ✅ | +| FR-04.6 | 曲面离散化（三角网格化） | CGAL | ✅ | +| FR-04.7 | 曲面修剪（Trimmed Surface） | OCCT | 📋 P2 | +| FR-04.8 | 曲面-曲面求交 | OCCT | 📋 P2 | +| FR-04.9 | 直纹面（Ruled Surface） | OCCT | 📋 P2 | +| FR-04.10 | 旋转面（Surface of Revolution） | OCCT | 📋 P2 | ### FR-05：网格处理 -| 编号 | 需求 | 优先级 | -|------|------|--------| -| FR-05.1 | 半边数据结构（Half-Edge） | P0 | -| FR-05.2 | Delaunay 三角剖分（2D） | P0 | -| FR-05.3 | 约束 Delaunay 三角剖分（2D） | P2 | -| FR-05.4 | 网格简化（QEM 算法） | P1 | -| FR-05.5 | 网格平滑（Laplacian / Taubin） | P1 | -| FR-05.6 | 网格布尔运算（并、交、差） | P1 | -| FR-05.7 | 网格质量评估 | P1 | -| FR-05.8 | 网格修复（孔洞填充、非流形修复） | P2 | +| 编号 | 需求 | 对标 | 状态 | +|------|------|------|------| +| FR-05.1 | 半边数据结构（Half-Edge） | CGAL Polyhedron | ✅ | +| FR-05.2 | Delaunay 三角剖分 2D（Bowyer-Watson） | CGAL 2D Triangulation | ✅ | +| FR-05.3 | 约束 Delaunay 三角剖分 2D（CDT） | CGAL / Triangle | 📋 P1 | +| FR-05.4 | 3D Delaunay 四面体剖分 | CGAL 3D Triangulation | 📋 P1 | +| FR-05.5 | **网格简化（QEM）** | CGAL / libigl | 🔨 P0 | +| FR-05.6 | **网格平滑（Laplacian / Taubin）** | libigl | 🔨 P0 | +| FR-05.7 | **网格质量评估** | CGAL | 🔨 P0 | +| FR-05.8 | **网格修复（水密化/孔洞填充/去除非流形）** | Manifold / CGAL | 🔨 P0 | +| FR-05.9 | 网格细分（Loop / Catmull-Clark） | libigl | 📋 P2 | +| FR-05.10 | 网格重网格化（Isotropic Remeshing） | CGAL | 📋 P2 | +| FR-05.11 | 网格参数化（Tutte / LSCM） | libigl | 📋 P2 | +| FR-05.12 | 测地线距离 | libigl / CGAL | 📋 P1 | +| FR-05.13 | 离散曲率（高斯曲率/平均曲率） | libigl | 📋 P1 | +| FR-05.14 | 网格法向量（面/顶点/角） | CGAL | ✅ | -### FR-06：布尔运算（CSG） +### FR-06：布尔运算 -| 编号 | 需求 | 优先级 | -|------|------|--------| -| FR-06.1 | 二维多边形布尔运算（并、交、差、异或） | P0 | -| FR-06.2 | 三维网格布尔运算 | P1 | -| FR-06.3 | B-Rep 实体布尔运算 | P2 | +| 编号 | 需求 | 对标 | 状态 | +|------|------|------|------| +| FR-06.1 | **2D 多边形布尔（Vatti 算法）** | Clipper2 | 🔨 P0 | +| FR-06.2 | 2D 多边形偏移（膨胀/腐蚀） | Clipper2 | 📋 P1 | +| FR-06.3 | **3D 网格布尔（并/交/差）** | Manifold / CGAL | 🔨 P0 | +| FR-06.4 | B-Rep 实体布尔 | OCCT | 📋 P2 | +| FR-06.5 | Nef 多面体精确布尔 | CGAL | 🔜 P4 | ### FR-07：空间索引 -| 编号 | 需求 | 优先级 | -|------|------|--------| -| FR-07.1 | 包围体层次结构（BVH） | P0 | -| FR-07.2 | 八叉树（Octree） | P1 | -| FR-07.3 | KD-Tree | P1 | -| FR-07.4 | R-Tree | P2 | +| 编号 | 需求 | 对标 | 状态 | +|------|------|------|------| +| FR-07.1 | BVH（SAH 构建 + 射线/范围/KNN 查询） | CGAL AABB Tree | 🔨 基础版 | +| FR-07.2 | **BVH 最近命中查询** | CGAL | 🔨 P0 | +| FR-07.3 | Octree（点云/网格） | CGAL | 🔨 P0 | +| FR-07.4 | KD-Tree（KNN/范围查询） | CGAL | 🔨 P0 | +| FR-07.5 | R-Tree（空间对象索引） | GEOS / CGAL | 🔨 P1 | +| FR-07.6 | 空间索引抽象接口 | — | ✅ | ### FR-08：碰撞检测 -| 编号 | 需求 | 优先级 | -|------|------|--------| -| FR-08.1 | GJK 算法（凸体距离/碰撞检测） | P0 | -| FR-08.2 | SAT 分离轴定理（多面体） | P1 | -| FR-08.3 | 射线-三角形相交（Möller-Trumbore） | P0 | -| FR-08.4 | 三角形-三角形相交 | P1 | -| FR-08.5 | AABB / OBB 相交测试 | P1 | +| 编号 | 需求 | 对标 | 状态 | +|------|------|------|------| +| FR-08.1 | GJK 相交判断 | — | ✅ | +| FR-08.2 | **GJK 最小距离计算** | — | 🔨 P0 | +| FR-08.3 | **EPA 穿透深度（碰撞点+法向量+深度）** | — | 🔨 P0 | +| FR-08.4 | SAT 多面体碰撞 | — | 🔨 P1 | +| FR-08.5 | 射线-三角形相交（Möller-Trumbore） | — | ✅ | +| FR-08.6 | 射线-网格相交（利用 BVH） | — | 📋 P1 | +| FR-08.7 | 三角形-三角形相交 | — | 🔨 P1 | +| FR-08.8 | AABB-AABB / OBB-OBB 相交 | — | 📋 P1 | +| FR-08.9 | 连续碰撞检测（CCD） | — | 📋 P2 | ### FR-09：几何计算 -| 编号 | 需求 | 优先级 | -|------|------|--------| -| FR-09.1 | 距离计算（点-点、点-线、点-面、线-线） | P0 | -| FR-09.2 | 面积计算（多边形、曲面） | P1 | -| FR-09.3 | 最近点查询 | P1 | -| FR-09.4 | 凸包计算（2D / 3D） | P0 | +| 编号 | 需求 | 对标 | 状态 | +|------|------|------|------| +| FR-09.1 | 距离计算（点-点/线/面/三角形/线段） | CGAL | ✅ | +| FR-09.2 | 最近点查询 | CGAL | ✅ | +| FR-09.3 | 2D 凸包（Graham Scan） | CGAL | ✅ | +| FR-09.4 | **3D 凸包（QuickHull）** | CGAL | 🔨 P0 | +| FR-09.5 | 2D Voronoi 图 | CGAL | 📋 P1 | +| FR-09.6 | 3D Voronoi 图 | CGAL | 📋 P2 | +| FR-09.7 | 面积计算（多边形/曲面） | CGAL | ✅ | +| FR-09.8 | 体积计算（多面体） | CGAL | 📋 P1 | +| FR-09.9 | 主成分分析（PCA） | CGAL | 📋 P2 | ### FR-10：公差与精度 -| 编号 | 需求 | 优先级 | -|------|------|--------| -| FR-10.1 | 可配置的几何公差 | P0 | -| FR-10.2 | 自适应精度策略 | P1 | -| FR-10.3 | 鲁棒的浮点谓词（Shewchuk 自适应精度） | P1 | +| 编号 | 需求 | 对标 | 状态 | +|------|------|------|------| +| FR-10.1 | 可配置全局/局部公差 | CGAL | ✅ | +| FR-10.2 | 精确谓词（orient_2d/3d, in_circle） | CGAL Exact | ✅ 基础版 | +| FR-10.3 | Shewchuk 自适应精度完整实现 | CGAL | 🔨 简化版 | +| FR-10.4 | 几何吸附（snapping） | — | 📋 P1 | + +### FR-11：B-Rep 实体建模 + +| 编号 | 需求 | 对标 | 状态 | +|------|------|------|------| +| FR-11.1 | B-Rep 数据结构（体/壳/面/环/边/顶点） | OCCT | 📋 P2 | +| FR-11.2 | 拉伸体（Extrude） | OCCT | 📋 P2 | +| FR-11.3 | 旋转体（Revolve） | OCCT | 📋 P2 | +| FR-11.4 | 扫掠体（Sweep） | OCCT | 📋 P2 | +| FR-11.5 | 放样体（Loft） | OCCT | 📋 P2 | +| FR-11.6 | 倒角（Fillet / Chamfer） | OCCT | 📋 P2 | +| FR-11.7 | 抽壳（Shell / Hollow） | OCCT | 📋 P2 | +| FR-11.8 | 曲面偏移（Offset） | OCCT | 📋 P2 | +| FR-11.9 | 基本体生成（盒/球/柱/锥/环） | OCCT | 📋 P2 | + +### FR-12：离散化与重建 + +| 编号 | 需求 | 对标 | 状态 | +|------|------|------|------| +| FR-12.1 | Marching Cubes（等值面提取） | libigl | 📋 P1 | +| FR-12.2 | 体素化（网格→体素 / 体素→网格） | libigl | 📋 P1 | +| FR-12.3 | Alpha Shapes（点云→网格） | CGAL | 📋 P2 | +| FR-12.4 | 曲面重建（Poisson 重建） | CGAL | 📋 P2 | + +### FR-13：数据交换 + +| 编号 | 需求 | 对标 | 状态 | +|------|------|------|------| +| FR-13.1 | OBJ 读写 | CGAL / libigl | ✅ | +| FR-13.2 | STL 读写（文本+二进制） | CGAL | ✅ | +| FR-13.3 | PLY 读写 | libigl | 📋 P3 | +| FR-13.4 | OFF 读写 | CGAL | 📋 P3 | +| FR-13.5 | STEP 导入/导出 | OCCT | 🔜 P3 | +| FR-13.6 | IGES 导入/导出 | OCCT | 🔜 P3 | +| FR-13.7 | glTF 导出 | OCCT | 📋 P3 | + +### FR-14：高级算法 + +| 编号 | 需求 | 对标 | 状态 | +|------|------|------|------| +| FR-14.1 | Nef 多面体（精确布尔） | CGAL | 🔜 P4 | +| FR-14.2 | 点云配准（ICP） | CGAL / PCL | 🔜 P4 | +| FR-14.3 | 最优包围盒（OBB 最小体积） | CGAL | 🔜 P4 | --- @@ -139,32 +241,54 @@ ### NFR-01：性能 -| 指标 | 输入规模 | 目标 | -|------|---------|------| -| 布尔运算 | 百万面级网格 | ≤ 30 秒 | -| 最近点查询 | 10 万三角面（BVH） | ≤ 1 毫秒 | -| Delaunay 剖分 | 百万点 | ≤ 10 秒 | +| 指标 | 输入规模 | 目标 | 对标 | +|------|---------|------|------| +| 2D 布尔（Vatti） | 10⁴ 顶点 | ≤ 0.1s | Clipper2 | +| 3D 网格布尔 | 10⁵ 三角面 | ≤ 1s | Manifold | +| 网格简化 | 10⁵→10⁴ 面 | ≤ 2s | CGAL | +| BVH 射线查询 | 10⁶ 面 | ≤ 0.1ms/次 | CGAL | +| Delaunay 2D | 10⁶ 点 | ≤ 10s | CGAL | +| 3D Delaunay | 10⁵ 点 | ≤ 5s | CGAL | +| GJK 碰撞 | 凸体 | ≤ 30 次迭代 | — | ### NFR-02：可靠性 - 核心算法单元测试覆盖率 ≥ 90% -- 回归测试套件覆盖所有公开 API -- 边界条件与退化情况的鲁棒处理 +- 2D/3D 布尔运算通过标准测试集 +- 所有公开 API 有边界条件测试 ### NFR-03：可移植性 -- 支持 Linux（GCC 9+ / Clang 12+） -- 支持 Windows（MSVC 2019+） -- 支持 macOS（Clang 12+） +- Linux GCC 9+ / Clang 12+ +- Windows MSVC 2019+ +- macOS Clang 12+ ### NFR-04：可扩展性 -- 模块化架构，各模块独立编译 -- 清晰的接口抽象层，支持算法替换 -- 插件式空间索引后端 +- 模块化架构，仅 Eigen 一个必需依赖 +- 空间索引后端可替换 +- C API 支持跨语言绑定 -### NFR-05：可用性 +### NFR-05：许可证 -- 完善的 API 文档（Doxygen） -- 丰富的示例代码 -- 入门指南与教程 +- Apache 2.0，商业友好 + +--- + +## 4. 版本规划 + +| 版本 | 包含功能 | 优先级覆盖 | +|------|---------|-----------| +| **v0.1.0** | 基础几何 + 曲线曲面 + 基础网格 + 基础 BVH + GJK | ✅ 已完成 | +| **v0.3.0** | P0 全部 11 项（Vatti/网格布尔/QEM/3D凸包/Octree等） | P0 | +| **v0.5.0** | P1 全部 12 项（Voronoi/3DDelaunay/MarchingCubes/曲率等） | P1 | +| **v1.0.0** | P2 全部 10 项（B-Rep/倒角/抽壳/扫掠/放样/参数化等） | P2 | +| **v1.5.0** | P3 全部 5 项（STEP/IGES/PLY/glTF 等） | P3 | +| **v2.0.0** | P4 全部 3 项（Nef/ICP/OBB） | P4 | + +![版本路线](v0.1.0 → v0.3.0 → v0.5.0 → v1.0.0 → v2.0.0) + +``` +现在 追上Clipper2 追上Manifold 追上OCCT 追上CGAL高级 + +Manifold +libigl 建模层 功能 +``` diff --git a/docs/01-需求分析/04-功能差距分析.md b/docs/01-需求分析/04-功能差距分析.md new file mode 100644 index 0000000..cce2dfb --- /dev/null +++ b/docs/01-需求分析/04-功能差距分析.md @@ -0,0 +1,168 @@ +# 功能差距分析 + +## 目录 + +1. [分析范围](#1-分析范围) +2. [差距总览](#2-差距总览) +3. [逐项差距详析](#3-逐项差距详析) +4. [优先级排序](#4-优先级排序) +5. [实施路线](#5-实施路线) + +--- + +## 1. 分析范围 + +本分析将 ViewDesignEngine v0.1.0 已有功能与以下竞品进行全面对标： + +| 竞品 | 定位 | 分析重点 | +|------|------|---------| +| **CGAL 6.0** | 学术级全功能几何库 | 算法广度、精度、结构 | +| **OCCT 7.8** | 工业级 CAD 内核 | B-Rep、建模操作、数据交换 | +| **Manifold** | 3D网格布尔引擎 | 速度、鲁棒性 | +| **Clipper2** | 2D布尔引擎 | 2D布尔速度与正确性 | +| **libigl** | 研究级网格处理 | 网格简化/平滑/参数化 | + +--- + +## 2. 差距总览 + +共识别 **41 项功能差距**，按优先级分为 5 级： + +| 优先级 | 数量 | 说明 | +|--------|------|------| +| **P0** | 11 项 | 必须有——缺失则无法称为完整几何引擎 | +| **P1** | 12 项 | 应该有——对标 Clipper2 + Manifold + libigl | +| **P2** | 10 项 | 最好有——对标 OCCT 建模层 | +| **P3** | 5 项 | 锦上添花——对标 OCCT 数据交换 | +| **P4** | 3 项 | 长期目标——对标 CGAL 高级功能 | + +--- + +## 3. 逐项差距详析 + +### 3.1 P0 级 — 必须有（11 项） + +| 编号 | 功能 | 对标 | 当前状态 | 复杂度 | +|------|------|------|---------|--------| +| GAP-01 | **2D 布尔运算（Vatti 算法）** | Clipper2 | ❌ 仅有 S-H 裁剪（仅凸多边形） | ⭐⭐⭐⭐ | +| GAP-02 | **3D 网格布尔运算** | Manifold / CGAL | ❌ Stub | ⭐⭐⭐⭐⭐ | +| GAP-03 | **GJK + EPA 穿透深度** | — | ❌ GJK 仅有相交判断，无距离/深度 | ⭐⭐⭐ | +| GAP-04 | **网格简化（QEM）** | CGAL / libigl | ❌ Stub | ⭐⭐⭐ | +| GAP-05 | **网格平滑** | libigl | ❌ Stub | ⭐⭐ | +| GAP-06 | **网格质量评估** | CGAL | ❌ Stub | ⭐⭐ | +| GAP-07 | **网格修复（水密化/孔洞填充）** | Manifold / CGAL | ❌ Stub | ⭐⭐⭐⭐ | +| GAP-08 | **3D 凸包（QuickHull）** | CGAL | ❌ TODO（仅有 2D） | ⭐⭐⭐ | +| GAP-09 | **BVH 最近命中查询** | CGAL | ❌ 仅有全部命中查询 | ⭐⭐ | +| GAP-10 | **Octree 完整实现** | CGAL | ❌ Stub | ⭐⭐ | +| GAP-11 | **KD-Tree 完整实现** | CGAL | ❌ Stub | ⭐⭐ | + +### 3.2 P1 级 — 应该有（12 项） + +| 编号 | 功能 | 对标 | 当前状态 | 复杂度 | +|------|------|------|---------|--------| +| GAP-12 | **2D Voronoi 图** | CGAL | ❌ 未实现 | ⭐⭐⭐ | +| GAP-13 | **3D Delaunay 四面体剖分** | CGAL / TetGen | ❌ 未实现 | ⭐⭐⭐⭐ | +| GAP-14 | **约束 Delaunay（2D）** | CGAL / Triangle | ❌ 未实现 | ⭐⭐⭐ | +| GAP-15 | **Marching Cubes（等值面提取）** | libigl | ❌ 未实现 | ⭐⭐ | +| GAP-16 | **体素化** | libigl / Manifold | ❌ 未实现 | ⭐⭐ | +| GAP-17 | **测地线距离** | libigl / CGAL | ❌ 未实现 | ⭐⭐⭐ | +| GAP-18 | **离散曲率（高斯/平均）** | libigl / CGAL | ❌ 未实现 | ⭐⭐ | +| GAP-19 | **SAT 多面体碰撞** | — | ❌ Stub | ⭐⭐⭐ | +| GAP-20 | **三角形-三角形相交** | CGAL | ❌ Stub | ⭐⭐ | +| GAP-21 | **R-Tree 完整实现** | GEOS / CGAL | ❌ Stub | ⭐⭐⭐ | +| GAP-22 | **2D 多边形偏移（膨胀/腐蚀）** | Clipper2 | ❌ 未实现 | ⭐⭐⭐ | +| GAP-23 | **NURBS 曲面完整实现** | CGAL / OCCT | ❌ 仅有曲线 | ⭐⭐⭐ | + +### 3.3 P2 级 — 最好有（10 项） + +| 编号 | 功能 | 对标 | 当前状态 | 复杂度 | +|------|------|------|---------|--------| +| GAP-24 | **B-Rep 内核** | OCCT | ❌ 未实现 | ⭐⭐⭐⭐⭐ | +| GAP-25 | **倒角（Fillet/Chamfer）** | OCCT | ❌ 未实现 | ⭐⭐⭐⭐ | +| GAP-26 | **抽壳（Shell/Hollow）** | OCCT | ❌ 未实现 | ⭐⭐⭐⭐ | +| GAP-27 | **扫掠（Sweep）** | OCCT | ❌ 未实现 | ⭐⭐⭐⭐ | +| GAP-28 | **拉伸/旋转体** | OCCT | ❌ 未实现 | ⭐⭐ | +| GAP-29 | **放样（Loft）** | OCCT | ❌ 未实现 | ⭐⭐⭐ | +| GAP-30 | **曲面偏移** | OCCT | ❌ 未实现 | ⭐⭐⭐⭐ | +| GAP-31 | **网格参数化（Tutte/LSCM）** | libigl | ❌ 未实现 | ⭐⭐⭐ | +| GAP-32 | **曲面重建（Poisson）** | CGAL | ❌ 未实现 | ⭐⭐⭐⭐ | +| GAP-33 | **Alpha Shapes** | CGAL | ❌ 未实现 | ⭐⭐⭐ | + +### 3.4 P3 级 — 锦上添花（5 项） + +| 编号 | 功能 | 对标 | 当前状态 | 复杂度 | +|------|------|------|---------|--------| +| GAP-34 | **STEP 导入/导出** | OCCT | ❌ 未实现 | ⭐⭐⭐⭐⭐ | +| GAP-35 | **IGES 导入/导出** | OCCT | ❌ 未实现 | ⭐⭐⭐⭐ | +| GAP-36 | **PLY 导入/导出** | libigl | ❌ 未实现 | ⭐ | +| GAP-37 | **WKT/WKB 格式** | GEOS | ❌ 未实现 | ⭐ | +| GAP-38 | **glTF 导出** | OCCT | ❌ 未实现 | ⭐⭐ | + +### 3.5 P4 级 — 长期目标（3 项） + +| 编号 | 功能 | 对标 | 当前状态 | 复杂度 | +|------|------|------|---------|--------| +| GAP-39 | **Nef 多面体（精确布尔）** | CGAL | ❌ 未实现 | ⭐⭐⭐⭐⭐ | +| GAP-40 | **点云配准（ICP）** | CGAL / PCL | ❌ 未实现 | ⭐⭐⭐ | +| GAP-41 | **最优包围盒（OBB）** | CGAL | ❌ 未实现 | ⭐⭐⭐ | + +--- + +## 4. 优先级排序 + +### 4.1 按版本编排 + +| 版本 | 新增功能 | gap 数 | +|------|---------|--------| +| **v0.3.0** | P0 全部（11 项）：Vatti 2D 布尔、3D 网格布尔、GJK+EPA、QEM 简化、平滑、质量、修复、3D 凸包、BVH 完整、Octree、KD-Tree | 11 | +| **v0.5.0** | P1 全部（12 项）：Voronoi、3D Delaunay、CDT、Marching Cubes、体素化、测地线、曲率、SAT、Tri-Tri、R-Tree、多边形偏移、NURBS 曲面 | 12 | +| **v1.0.0** | P2 全部（10 项）：B-Rep、倒角、抽壳、扫掠/放样、拉伸、曲面偏移、参数化、曲面重建、Alpha Shapes | 10 | +| **v1.5.0** | P3 全部（5 项）：STEP、IGES、PLY、WKT/WKB、glTF | 5 | +| **v2.0.0** | P4 全部（3 项）：Nef 多面体、点云配准、OBB | 3 | + +### 4.2 与竞品的差距缩小路线 + +``` +v0.1.0 ──────► v0.3.0 ──────► v0.5.0 ──────► v1.0.0 ──────► v2.0.0 + 现在 追上Clipper2 追上Manifold 追上OCCT建模 追上CGAL + +Manifold +libigl 高级功能 +``` + +--- + +## 5. 实施路线 + +### 阶段一：v0.3.0 — 核心缺口补齐（预计 3 个月） + +``` +Week 1-2: Vatti 2D 布尔 + 多边形偏移 +Week 3-4: 3D 网格布尔（借鉴 Manifold） +Week 5: GJK+EPA 穿透深度 +Week 6: QEM 网格简化 +Week 7: 网格平滑 + 质量评估 +Week 8: 网格修复 +Week 9: 3D 凸包 QuickHull +Week 10-12: BVH 增强 + Octree + KD-Tree + 测试 +``` + +### 阶段二：v0.5.0 — 算法广度（预计 3 个月） + +``` +Month 4: 2D/3D Voronoi + 3D Delaunay + CDT +Month 5: Marching Cubes + 体素化 + 测地线 + 曲率 +Month 6: SAT + Tri-Tri + R-Tree + NURBS 曲面 + 多边形偏移 +``` + +### 阶段三：v1.0.0 — B-Rep 内核（预计 6 个月） + +``` +Month 7-9: B-Rep 数据结构 + 拓扑图 +Month 10-12: 倒角/抽壳/扫掠/放样/拉伸/偏移 +``` + +### 阶段四：v1.5.0+ 数据交换与高级功能 + +``` +Month 13-15: STEP/IGES/PLY/glTF 读写 +Month 16-18: Alpha Shapes、曲面重建、Nef 多面体 +```