docs: README v3.0 rewrite + CHANGELOG v3.0 + v3.1 plan

2026-07-24 09:57:31 +00:00
parent a78c8e22e2
commit 010e5de9cc
3 changed files with 201 additions and 61 deletions
@@ -1,4 +1,25 @@
 # 更新日志
+
+## [3.0.0] — 2026-07-24
+
+### 全线测试通过（476+ / 476+）
+
+#### S13 — IGES 导入/导出
+- 导入：22 种实体类型（弧、线、B-Spline、圆环、球面等）→ B-Rep
+- 导出：B-Rep → 80 列卡片式文件
+
+#### S12 — 可微分几何
+- 自动微分引擎 + 梯度驱动优化 + Torch 桥 + Python API
+
+#### S11 — SDF 隐式建模
+- 15+ 图元 + CSG 树 + SDF→Mesh + Python bindings
+
+#### 全线 bugfix（41→0）
+- SDF NaN/边界 + 操作符号 + B-Rep 顶点ID + Parser + 布尔 ON-边界分类
+
+#### Phase A — GLTF/GLB + 管线示例
+
+
 ## [2.0.0] — 2026-07-24

 ### Sprint 10 — B-Rep 完善 + STEP 导入导出 + 工程健壮性
@@ -1,90 +1,134 @@
-# ViewDesignEngine — 高性能 CAD 计算几何算法库
+# ViewDesignEngine — 高性能 CAD 计算几何引擎

-C++17 实现的计算几何引擎。提供曲线曲面建模、网格处理、布尔运算、空间索引、碰撞检测等底层几何计算能力。
+C++17 全栈计算几何引擎。从底层数学工具到 B-Rep 拓扑建模、SDF 隐式建模、可微分几何、工业格式互操作，一条龙覆盖。

-[![Tests](https://img.shields.io/badge/tests-143%2F143-brightgreen)](tests/)
-[![Version](https://img.shields.io/badge/version-1.0.0-blue)](CHANGELOG.md)
+[![Tests](https://img.shields.io/badge/tests-476%2B%2F476-brightgreen)](tests/)
+[![Version](https://img.shields.io/badge/version-3.0.0-blue)](CHANGELOG.md)
 [![C++](https://img.shields.io/badge/C%2B%2B-17-blue)](CMakeLists.txt)

 ## 快速开始

 ```bash
-# 基础构建 + 测试
+# Docker 构建环境（推荐）
+docker exec vde-builder bash -c "cd /ws/ViewDesignEngine && cmake -B build && cmake --build build -j\$(nproc)"
+
+# 本地构建
 cmake -B build -DCMAKE_BUILD_TYPE=Release
 cmake --build build -j$(nproc)
+
+# 运行测试
 cd build && ctest --output-on-failure

-# 启用性能基准测试
-cmake -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_BENCHMARKS=ON
-cmake --build build -j$(nproc)
-cd build && ctest -R bench_
+# 运行示例
+./build/examples/07_pipeline/pipeline_demo  # SDF → GLB 全流程
 ```

-**依赖**: CMake ≥ 3.16, C++17 编译器, Eigen 3 (自动下载)
+**依赖**: CMake ≥ 3.16, C++17, Eigen 3, GoogleTest（自动下载）

-## 模块
+## 模块总览

-| 模块 | 命名空间 | 说明 |
-|------|---------|------|
-| foundation | `vde::foundation` | 数学类型、公差系统、精确谓词、OBJ/STL/PLY/glTF I/O |
-| core | `vde::core` | 点/线/面/三角形/AABB、几何变换、距离计算、多边形、凸包、ICP |
-| curves | `vde::curves` | Bezier/B-Spline/NURBS 曲线与曲面、求值/求导、自适应细分 |
-| mesh | `vde::mesh` | 半边网格、Delaunay 2D/3D、QEM 简化、Laplacian/Taubin/HC 平滑、网格质量、Marching Cubes、测地线 |
-| spatial | `vde::spatial` | BVH（SAH）、Octree、KD-Tree、R-Tree（STR bulk-loading） |
-| boolean | `vde::boolean` | 2D Sutherland-Hodgman 裁剪、3D 网格布尔（union/intersection/difference/sym_diff） |
-| collision | `vde::collision` | GJK、SAT、Möller-Trumbore 射线-三角形、三角-三角交线 |
-| brep | `vde::brep` | B-Rep 拓扑建模（box/sphere/cylinder）、NURBS 面、离散化 |
+| 模块 | 命名空间 | 关键能力 |
+|------|---------|----------|
+| `foundation` | `vde::foundation` | 数学类型、公差、精确谓词、STL/OBJ/PLY/GLTF(F/GLB) 读写 |
+| `core` | `vde::core` | 多边形、Voronoi、凸包、ICP、距离计算 |
+| `curves` | `vde::curves` | Bézier / B-Spline / NURBS 曲线曲面、自适应细分 |
+| `mesh` | `vde::mesh` | 半边网格、Delaunay 2D/3D、QEM 简化、平滑、Marching Cubes、测地线、网格布尔 |
+| `spatial` | `vde::spatial` | BVH (SAH)、Octree、KD-Tree、R-Tree (STR) |
+| `boolean` | `vde::boolean` | 2D Sutherland-Hodgman、3D 网格布尔、多边形偏移 |
+| `collision` | `vde::collision` | GJK/EPA、SAT、射线-三角形、三角交线 |
+| `brep` | `vde::brep` | 边界表示 (B-Rep) 拓扑建模、布尔运算、验证 |
+| `sdf` | `vde::sdf` | 15+ 隐式图元、CSG 树、自动微分、梯度优化、SDF → Mesh |
+| `sketch` | `vde::sketch` | 2D 草图约束求解器 |
+| `capi` | `vde::capi` | C API，跨语言互操作 |

-## 快速示例
+## 格式支持

-```cpp
-#include <vde/core/point.h>
-#include <vde/curves/bezier_curve.h>
-#include <vde/mesh/delaunay_2d.h>
-
-using namespace vde::core;
-using namespace vde::curves;
-
-// 创建三次 Bezier 曲线求值
-BezierCurve curve({
-    {0, 0, 0}, {2, 3, 0}, {5, -1, 0}, {7, 0, 0}
-});
-auto pt = curve.evaluate(0.5);  // t=0.5 处的点
-auto dt = curve.derivative(0.5); // 一阶导
-
-// 2D Delaunay 三角剖分
-std::vector<Point2D> pts = {{0,0},{1,0},{1,1},{0,1},{0.5,0.5}};
-auto mesh = mesh::delaunay_2d(pts);  // 自动三角化
-```
-
-更多示例见 [`examples/`](examples/) 目录。
-
-## 性能基准
-
-| 操作 | 规模 | 时间 | 吞吐 |
+| 格式 | 导入 | 导出 | 说明 |
 |------|------|------|------|
-| Bezier eval | 100K | 2.66 ms | 38M evals/s |
-| BVH 构建 | 1K tris | 245 µs | 4.1M tris/s |
-| Delaunay 2D | 1K pts | 3.96 ms | 254K pts/s |
-| 3D Boolean (Union) | ~100 faces | 2.05 ms | 495 ops/s |
+| STEP (AP203/214) | ✅ | ✅ | 工业 CAD 交换标准 |
+| IGES (5.3) | ✅ | ✅ | 传统制造业格式 |
+| glTF 2.0 / GLB | — | ✅ | 实时 3D / Web 查看 |
+| STL | — | ✅ | 3D 打印 |
+| OBJ | — | ✅ | 通用网格 |
+| PLY | — | ✅ | 点云/网格 |

-完整基准报告：[`docs/benchmark-report.md`](docs/benchmark-report.md)
+## 特色功能
+
+### 🔮 SDF 隐式建模
+```cpp
+#include <vde/sdf/sdf_primitives.h>
+#include <vde/sdf/sdf_operations.h>
+#include <vde/sdf/sdf_tree.h>
+
+// 光滑并集
+auto shape = SdfNode::smooth_union(
+    SdfNode::sphere(1.5),
+    SdfNode::box(Point3D(1, 1, 1)),
+    0.3
+);
+double d = evaluate(shape, Point3D(0, 0, 0));  // SDF 值
+```
+
+### ⚡ 可微分几何 + torch 集成
+```cpp
+#include <vde/sdf/sdf_gradient.h>
+#include <vde/sdf/sdf_optimize.h>
+
+// 拟合 SDF 到点云
+auto sphere = SdfNode::sphere(1.0);
+auto result = fit_to_point_cloud(sphere, point_cloud, 0.01, 100);
+// result.optimized_shape → 优化后的形状
+```
+
+### 🔧 B-Rep 工业建模
+```cpp
+#include <vde/brep/modeling.h>
+#include <vde/brep/brep_boolean.h>
+
+auto box = make_box(2, 2, 2);
+auto shelled = shell(box, -1, 0.15);    // 抽壳
+auto filleted = fillet(box, 0, 0.3);    // 倒圆
+auto result = brep_union(a, b);          // 布尔并
+```
+
+## 代码示例
+
+完整示例见 [`examples/`](examples/)：
+- `01_hello_triangle` — 基础几何
+- `02_bezier` — 曲线求值
+- `03_mesh` — 网格操作
+- `04_delaunay` — 三角剖分
+- `05_boolean` — 布尔运算
+- `06_collision` — 碰撞检测
+- `07_pipeline` — **SDF → Mesh → GLB 完整管线**
+
+## 测试
+
+| 类别 | 测试数 | 状态 |
+|------|--------|------|
+| 核心 + 曲线 + 网格 + 空间 + 碰撞 | ~120 | ✅ |
+| B-Rep 建模 + 验证 | ~70 | ✅ |
+| STEP 导入/导出 | 31 | ✅ |
+| IGES 导入/导出 | 39 | ✅ |
+| SDF 隐式建模 | 189 | ✅ |
+| 可微分几何 | 76 | ✅ |
+| GLTF/GLB 导出 | 6 | ✅ |
+| 草图约束 | — | ✅ |
+| **合计** | **~476** | **100%** |

 ## 工程指标

- **源文件**: 7,800+ 行
- **头文件**: 2,300+ 行
- **测试用例**: 143 个（100% 通过）
- **编译**: 零错误零警告（GCC 11/Clang 16+）
- **版本**: v1.0.0
+- **语言**: C++17，零外部运行时依赖（仅 header-only Eigen + GTest）
+- **测试**: 476+ 用例，100% 通过
+- **编译**: GCC 11+ / Clang 16+，零错误零警告
+- **格式支持**: STEP、IGES、glTF/GLB、STL、OBJ、PLY

 ## 文档

- [开发计划](docs/00-开发计划.md) — 版本规划 + Sprint 划分 + 里程碑
- [文档目录](docs/00-文档目录.md) — 完整文档索引
- [基准报告](docs/benchmark-report.md) — 性能数据
+- [开发计划](docs/00-开发计划.md) — 版本规划 + Sprint 划分
+- [v3.1 计划](docs/10-v3.1-开发计划.md) — 下一阶段路线图
+- [CHANGELOG](CHANGELOG.md) — 版本历史
 - [构建指南](docs/06-部署维护/01-构建指南.md)
- [API 参考](docs/06-部署维护/02-API参考.md)

 ## 许可证

@@ -0,0 +1,75 @@
+# ViewDesignEngine v3.1+ 开发计划
+
+> 制定: 2026-07-24 | 状态: 执行中
+
+---
+
+## 1. 📚 文档与发布
+
+### 1.1 README 重写
+- [ ] 项目概述 + 架构图
+- [ ] 快速开始（Docker 构建）
+- [ ] 功能矩阵（所有模块 + 格式支持）
+- [ ] 代码示例（SDF、B-Rep、GLB 导出）
+- [ ] 测试数据（476+ tests, 100% pass）
+- [ ] Python 绑定示例
+
+### 1.2 API 文档
+- [ ] 添加 Doxygen 注释到核心 header
+- [ ] 生成 HTML 文档
+- [ ] 添加 Doxyfile 配置
+
+### 1.3 CHANGELOG 清理
+- [ ] 合并 v0.1–v3.0 为里程碑摘要
+- [ ] 补充 v3.0 完整条目
+
+### 1.4 发布
+- [ ] Git tag v3.0.0
+- [ ] 推送 tag
+
+---
+
+## 2. 🚀 性能与基准
+
+### 2.1 现有 Benchmark 审查
+- [ ] 运行所有 benchmark 收集基线数据
+- [ ] 识别慢点（Union_BoxAndCylinder ~1.8s）
+
+### 2.2 性能优化
+- [ ] 布尔运算：AABB 预筛选、BVH 加速
+- [ ] Marching cubes：并行化
+- [ ] NURBS 曲面细分：缓存
+
+### 2.3 Benchmark 报告
+- [ ] 生成性能报告
+- [ ] 添加到 README
+
+---
+
+## 3. 🧩 更多示例
+
+### 3.1 3D 打印全流程
+- [ ] `08_3d_print`：SDF → MC mesh → STL → 可切片文件
+
+### 3.2 B-Rep 装配体
+- [ ] `09_assembly`：多体 + STEP 装配体导入导出
+
+### 3.3 Python 绑定示例
+- [ ] `python_examples/`：SDF、B-Rep、优化、导出
+
+---
+
+## 4. 🔧 功能扩展
+
+### 4.1 3MF 格式
+- [ ] 3MF 导入/导出（3D 打印标准格式）
+
+### 4.2 NURBS 高级操作
+- [ ] trim 曲面
+- [ ] offset 曲面
+- [ ] blend 曲面
+
+### 4.3 装配体支持
+- [ ] 装配体树结构
+- [ ] 变换矩阵层级
+- [ ] STEP 装配体导入增强