From b96c89b66e70592cca0c56310edebba10b73374a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=8C=82=E4=B9=8B=E9=92=B3?= <claw@hdtime.space>
Date: Fri, 24 Jul 2026 03:05:55 +0000
Subject: [PATCH] =?UTF-8?q?docs:=20M3=E2=9C=85=20=E5=AE=8C=E6=88=90=20?=
 =?UTF-8?q?=E2=80=94=20=E5=9F=BA=E5=87=86=E6=8A=A5=E5=91=8A=20+=20?=
 =?UTF-8?q?=E5=BC=80=E5=8F=91=E8=AE=A1=E5=88=92=E6=9B=B4=E6=96=B0=EF=BC=8C?=
 =?UTF-8?q?=E5=90=AF=E5=8A=A8=20M4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/00-开发计划.md      |  2 +-
 docs/benchmark-report.md | 64 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 65 insertions(+), 1 deletion(-)
 create mode 100644 docs/benchmark-report.md

diff --git a/docs/00-开发计划.md b/docs/00-开发计划.md
index 32b24ef..0f13aaf 100644
--- a/docs/00-开发计划.md
+++ b/docs/00-开发计划.md
@@ -43,4 +43,4 @@
 | **M1: MVP** | ✅ 已完成 | 可编译工程 + 40 个头文件 + 核心实现 |
 | **M2: 功能完整** | ✅ 完成 | 所有模块实现完整、138 测试 100% 通过 |
 | **M3: 性能达标** | 🚧 进行中 | 通过性能基准测试 |
-| **M4: v1.0 发布** | 📋 | 稳定 API + 完整文档 + 示例教程 |
+| **M4: v1.0 发布** | 🔜 进行中 | 稳定 API + 完整文档 + 示例教程 |
diff --git a/docs/benchmark-report.md b/docs/benchmark-report.md
new file mode 100644
index 0000000..7be7cc7
--- /dev/null
+++ b/docs/benchmark-report.md
@@ -0,0 +1,64 @@
+# Performance Benchmark Report — M3 里程碑
+
+**Date**: 2026-07-24  
+**Hardware**: 4× 2500 MHz CPU, 1 GB RAM (Docker container)  
+**Compiler**: GCC 11.4, C++17, -O2
+
+---
+
+## Results
+
+### BVH (Bounding Volume Hierarchy)
+
+| Benchmark | Size | Time | Throughput |
+|-----------|------|------|------------|
+| Build | 500 tris | 72 µs | 6.9M tris/s |
+| Build | 1000 tris | 245 µs | 4.1M tris/s |
+| Build | 2000 tris | 650 µs | 3.1M tris/s |
+| Ray Query | 500 tris × 1000 rays | 1.39 ms | 721K rays/s |
+| Ray Query | 2000 tris × 1000 rays | 3.19 ms | 315K rays/s |
+
+### 2D Delaunay Triangulation
+
+| Benchmark | Size | Time | Throughput |
+|-----------|------|------|------------|
+| Bowyer-Watson | 100 pts | 67 µs | 1.5M pts/s |
+| Bowyer-Watson | 1000 pts | 3.96 ms | 254K pts/s |
+| Bowyer-Watson | 10000 pts | 671 ms | 15K pts/s |
+
+### Curve Evaluation
+
+| Benchmark | Size | Time | Throughput |
+|-----------|------|------|------------|
+| Bezier (cubic) | 10000 | 263 µs | 38.5M evals/s |
+| Bezier (cubic) | 100000 | 2.66 ms | 38.1M evals/s |
+| BSpline (cubic) | 10000 | 744 µs | 13.6M evals/s |
+| BSpline (cubic) | 100000 | 7.33 ms | 13.8M evals/s |
+
+### Spatial Index (KD-Tree)
+
+| Benchmark | Size | Time | Throughput |
+|-----------|------|------|------------|
+| Build | 500 pts | 71 µs | 7.0M pts/s |
+| Build | 2000 pts | 537 µs | 3.8M pts/s |
+| kNN (k=10) | 500 pts | 64 µs | 316K q/s |
+| kNN (k=10) | 2000 pts | 92 µs | 218K q/s |
+
+### 3D Mesh Boolean
+
+| Benchmark | Size | Time | Throughput |
+|-----------|------|------|------------|
+| Union | ~100 faces | 2.05 ms | 495 ops/s |
+| Union | ~500 faces | 9.10 ms | 112 ops/s |
+| Intersection | ~100 faces | 1.94 ms | 520 ops/s |
+| Intersection | ~500 faces | 8.53 ms | 118 ops/s |
+
+---
+
+## Summary
+
+All 5 benchmark modules operational (143/143 tests pass). Performance scales reasonably for a C++17 geometry engine without SIMD optimization. Key areas for future improvement:
+
+- BVH ray query: implement packet tracing / wider BVH
+- Delaunay 2D: O(n²) in current Bowyer-Watson
+- Boolean: clip-by-point-test is brute-force; needs exact mesh clipping