From 010e5de9ccb4d91f2adc4c34936f0ccfd4eec240 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E8=8C=82=E4=B9=8B=E9=92=B3?= Date: Fri, 24 Jul 2026 09:57:31 +0000 Subject: [PATCH] docs: README v3.0 rewrite + CHANGELOG v3.0 + v3.1 plan --- CHANGELOG.md | 21 +++++ README.md | 166 +++++++++++++++++++++++++-------------- docs/10-v3.1-开发计划.md | 75 ++++++++++++++++++ 3 files changed, 201 insertions(+), 61 deletions(-) create mode 100644 docs/10-v3.1-开发计划.md diff --git a/CHANGELOG.md b/CHANGELOG.md index ec10a9a..ebcb03e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 导入导出 + 工程健壮性 diff --git a/README.md b/README.md index c69efd6..ec85b45 100644 --- a/README.md +++ b/README.md @@ -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 -#include -#include - -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 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 +#include +#include + +// 光滑并集 +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 +#include + +// 拟合 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 +#include + +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) ## 许可证 diff --git a/docs/10-v3.1-开发计划.md b/docs/10-v3.1-开发计划.md new file mode 100644 index 0000000..b7bc1b2 --- /dev/null +++ b/docs/10-v3.1-开发计划.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 装配体导入增强