v0.1.0: 初始工程骨架 — 7模块 40头文件 32源文件 17文档 Apache-2.0
This commit is contained in:
ViewDesignEngine
@@ -0,0 +1,110 @@
|
||||
# 构建指南
|
||||
|
||||
## 目录
|
||||
|
||||
1. [环境要求](#1-环境要求)
|
||||
2. [获取源码](#2-获取源码)
|
||||
3. [构建步骤](#3-构建步骤)
|
||||
4. [CMake 选项](#4-cmake-选项)
|
||||
5. [作为依赖集成](#5-作为依赖集成)
|
||||
6. [文档生成](#6-文档生成)
|
||||
7. [故障排查](#7-故障排查)
|
||||
|
||||
---
|
||||
|
||||
## 1. 环境要求
|
||||
|
||||
| 依赖 | 最低版本 | 说明 |
|
||||
|------|---------|------|
|
||||
| CMake | 3.16+ | 构建系统 |
|
||||
| C++ 编译器 | GCC 9+ / Clang 12+ / MSVC 2019+ | C++17 支持 |
|
||||
| Eigen | 3.3+（自动下载） | 线性代数（header-only） |
|
||||
| Google Test | 自动下载 | 单元测试 |
|
||||
| Doxygen | 1.9+ | API 文档生成（可选） |
|
||||
|
||||
---
|
||||
|
||||
## 2. 获取源码
|
||||
|
||||
```bash
|
||||
git clone <仓库地址>
|
||||
cd ViewDesignEngine
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 构建步骤
|
||||
|
||||
### Linux / macOS
|
||||
|
||||
```bash
|
||||
cmake -B build -DCMAKE_BUILD_TYPE=Release \
|
||||
-DBUILD_TESTS=ON \
|
||||
-DBUILD_EXAMPLES=ON
|
||||
cmake --build build -j$(nproc)
|
||||
cd build && ctest --output-on-failure
|
||||
```
|
||||
|
||||
### Windows
|
||||
|
||||
```powershell
|
||||
cmake -B build -G "Visual Studio 17 2022"
|
||||
cmake --build build --config Release
|
||||
cd build && ctest --config Release
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. CMake 选项
|
||||
|
||||
| 选项 | 默认值 | 说明 |
|
||||
|------|--------|------|
|
||||
| `BUILD_TESTS` | ON | 构建单元测试 |
|
||||
| `BUILD_EXAMPLES` | ON | 构建示例程序 |
|
||||
| `BUILD_BENCHMARKS` | OFF | 构建性能测试 |
|
||||
| `BUILD_SHARED_LIBS` | OFF | 构建共享库（默认静态库） |
|
||||
| `ENABLE_SANITIZERS` | OFF | 启用 ASan/UBSan |
|
||||
| `ENABLE_LTO` | ON | 启用链接时优化 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 作为依赖集成
|
||||
|
||||
### CMake FetchContent
|
||||
|
||||
```cmake
|
||||
include(FetchContent)
|
||||
FetchContent_Declare(ViewDesignEngine
|
||||
GIT_REPOSITORY <仓库地址>
|
||||
GIT_TAG v0.1.0
|
||||
)
|
||||
FetchContent_MakeAvailable(ViewDesignEngine)
|
||||
target_link_libraries(你的项目 PRIVATE vde)
|
||||
```
|
||||
|
||||
### find_package（安装后）
|
||||
|
||||
```cmake
|
||||
find_package(ViewDesignEngine REQUIRED)
|
||||
target_link_libraries(你的项目 PRIVATE vde::engine)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 文档生成
|
||||
|
||||
```bash
|
||||
cmake -B build -DVDE_BUILD_DOCS=ON
|
||||
cmake --build build --target doc
|
||||
# 输出：build/docs/html/index.html
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 故障排查
|
||||
|
||||
| 问题 | 解决方案 |
|
||||
|------|---------|
|
||||
| Eigen 未找到 | 将自动通过 FetchContent 下载 |
|
||||
| 编译时间过长 | 使用 `-j` 并行编译，关闭 LTO |
|
||||
| 链接错误 | 确认 C++17 标准库链接正确 |
|
||||
@@ -0,0 +1,194 @@
|
||||
# API 参考
|
||||
|
||||
## 目录
|
||||
|
||||
1. [命名空间](#1-命名空间)
|
||||
2. [core 模块](#2-core-模块)
|
||||
3. [curves 模块](#3-curves-模块)
|
||||
4. [mesh 模块](#4-mesh-模块)
|
||||
5. [spatial 模块](#5-spatial-模块)
|
||||
6. [boolean 模块](#6-boolean-模块)
|
||||
7. [collision 模块](#7-collision-模块)
|
||||
8. [foundation 模块](#8-foundation-模块)
|
||||
9. [错误码](#9-错误码)
|
||||
|
||||
---
|
||||
|
||||
## 1. 命名空间
|
||||
|
||||
```cpp
|
||||
namespace vde::foundation { ... } // 基础设施
|
||||
namespace vde::core { ... } // 几何核心
|
||||
namespace vde::curves { ... } // 曲线曲面
|
||||
namespace vde::mesh { ... } // 网格处理
|
||||
namespace vde::spatial { ... } // 空间索引
|
||||
namespace vde::boolean { ... } // 布尔运算
|
||||
namespace vde::collision { ... } // 碰撞检测
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. core 模块
|
||||
|
||||
### 基本类型
|
||||
|
||||
| 类型 | 说明 |
|
||||
|------|------|
|
||||
| `Point2D`, `Point3D` | 二维/三维点 |
|
||||
| `Vector2D`, `Vector3D` | 二维/三维向量 |
|
||||
| `Line3Dd` | 三维无限直线 |
|
||||
| `Ray3Dd` | 三维射线 |
|
||||
| `Segment3Dd` | 三维线段 |
|
||||
| `Plane3D` | 三维平面 |
|
||||
| `Triangle3D` | 三维三角形 |
|
||||
| `AABB3D` | 轴对齐包围盒 |
|
||||
|
||||
### 变换
|
||||
|
||||
```cpp
|
||||
Transform3D translate(double x, double y, double z);
|
||||
Transform3D rotate(const Vector3D& axis, double rad);
|
||||
Transform3D scale(double sx, double sy, double sz);
|
||||
|
||||
// 组合
|
||||
Matrix4D m = rotate_x(90_deg) * translate(1, 0, 0);
|
||||
Point3D p2 = m * p1;
|
||||
```
|
||||
|
||||
### 凸包与距离
|
||||
|
||||
```cpp
|
||||
// 2D 凸包（Graham Scan）
|
||||
std::vector<Point2D> convex_hull_2d(const std::vector<Point2D>& pts);
|
||||
|
||||
// 距离计算
|
||||
double distance(const Point3D& a, const Point3D& b);
|
||||
double distance(const Point3D& p, const Plane3D& plane);
|
||||
double distance(const Point3D& p, const Triangle3D& tri);
|
||||
Point3D closest_point(const Point3D& p, const Triangle3D& tri);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. curves 模块
|
||||
|
||||
```cpp
|
||||
// 曲线构造
|
||||
BezierCurve bezier(control_points);
|
||||
NurbsCurve nurbs(control_points, knots, weights, degree);
|
||||
|
||||
// 求值与求导
|
||||
Point3D p = curve.evaluate(t);
|
||||
Vector3D d1 = curve.derivative(t, 1);
|
||||
|
||||
// 曲面
|
||||
NurbsSurface surface(grid, knots_u, knots_v, weights, deg_u, deg_v);
|
||||
Point3D p = surface.evaluate(u, v);
|
||||
|
||||
// 离散化
|
||||
auto [verts, tris] = tessellate(eval_func, res_u, res_v);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. mesh 模块
|
||||
|
||||
```cpp
|
||||
HalfedgeMesh mesh;
|
||||
|
||||
// 查询
|
||||
size_t nv = mesh.num_vertices();
|
||||
const Point3D& v = mesh.vertex(idx);
|
||||
|
||||
// Delaunay
|
||||
auto [verts, tris] = delaunay_2d(points);
|
||||
|
||||
// 简化与平滑
|
||||
auto simplified = simplify_mesh(mesh, {.target_ratio = 0.5});
|
||||
auto smoothed = smooth_mesh(mesh, {.iterations = 10});
|
||||
|
||||
// 质量评估
|
||||
auto quality = evaluate_mesh_quality(mesh);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. spatial 模块
|
||||
|
||||
```cpp
|
||||
BVH bvh;
|
||||
bvh.build(triangles);
|
||||
|
||||
auto hits = bvh.query_ray(ray); // 所有命中
|
||||
auto nearest = bvh.query_ray_nearest(ray); // 最近命中
|
||||
auto in_box = bvh.query_range(aabb); // 范围查询
|
||||
auto knn = bvh.query_knn(point, 5); // K 近邻
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. boolean 模块
|
||||
|
||||
```cpp
|
||||
// 2D 多边形布尔
|
||||
auto result = boolean_2d(poly_a, poly_b, BooleanOp::Union);
|
||||
auto result = boolean_2d(poly_a, poly_b, BooleanOp::Intersection);
|
||||
auto result = boolean_2d(poly_a, poly_b, BooleanOp::Difference);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. collision 模块
|
||||
|
||||
```cpp
|
||||
// GJK 碰撞检测
|
||||
bool hit = gjk_intersect(convex_a, convex_b);
|
||||
|
||||
// 射线-三角形相交（Möller-Trumbore）
|
||||
auto hit = ray_triangle_intersect(ray, tri);
|
||||
// hit->t, hit->point, hit->u, hit->v
|
||||
|
||||
// 三角形-三角形相交
|
||||
bool hit = tri_tri_intersect(t1, t2);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. foundation 模块
|
||||
|
||||
### 公差系统
|
||||
|
||||
```cpp
|
||||
Tolerance tol(/* absolute */ 1e-6, /* relative */ 1e-8);
|
||||
bool eq = tol.points_equal(a, b);
|
||||
bool zero = tol.is_zero(value);
|
||||
```
|
||||
|
||||
### 精确谓词
|
||||
|
||||
```cpp
|
||||
auto orient = exact::orient_2d(a, b, c);
|
||||
auto in = exact::in_circle(a, b, c, d);
|
||||
```
|
||||
|
||||
### I/O
|
||||
|
||||
```cpp
|
||||
auto mesh = read_obj("model.obj");
|
||||
write_obj(mesh, "output.obj");
|
||||
auto tris = read_stl("model.stl");
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. 错误码
|
||||
|
||||
| 错误码 | 说明 |
|
||||
|--------|------|
|
||||
| `kSuccess` | 操作成功 |
|
||||
| `kInvalidArgument` | 非法参数 |
|
||||
| `kInvalidGeometry` | 非法几何（退化/非流形） |
|
||||
| `kDegenerateCase` | 退化情况 |
|
||||
| `kNotImplemented` | 未实现 |
|
||||
| `kNumericalError` | 数值计算错误 |
|
||||
| `kOutOfMemory` | 内存不足 |
|
||||
Reference in New Issue
Block a user