149 lines
3.7 KiB
Markdown
149 lines
3.7 KiB
Markdown
|
# 接口定义
|
||
|
|
|
||
|
|
## 目录
|
||
|
|
|
||
|
|
1. [命名约定](#1-命名约定)
|
||
|
|
2. [核心接口抽象](#2-核心接口抽象)
|
||
|
|
- 2.1 空间索引接口
|
||
|
|
- 2.2 曲线求值接口
|
||
|
|
- 2.3 网格数据结构接口
|
||
|
|
- 2.4 布尔运算接口
|
||
|
|
3. [稳定 C API（可选）](#3-稳定-c-api可选)
|
||
|
|
4. [错误处理约定](#4-错误处理约定)
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 1. 命名约定
|
||
|
|
|
||
|
|
| 元素 | 风格 | 示例 |
|
||
|
|
|------|------|------|
|
||
|
|
| 命名空间 | snake_case | `vde::core` |
|
||
|
|
| 类/结构体 | PascalCase | `HalfedgeMesh` |
|
||
|
|
| 函数/方法 | snake_case | `compute_convex_hull()` |
|
||
|
|
| 变量 | snake_case | `vertex_count` |
|
||
|
|
| 成员变量 | snake_case_ | `vertices_` |
|
||
|
|
| 常量 | UPPER_SNAKE_CASE | `MAX_ITERATIONS` |
|
||
|
|
| 枚举值 | kPascalCase | `kSuccess` |
|
||
|
|
| 宏前缀 | VDE_ | `VDE_VERSION_MAJOR` |
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 2. 核心接口抽象
|
||
|
|
|
||
|
|
### 2.1 空间索引接口
|
||
|
|
|
||
|
|
```cpp
|
||
|
|
namespace vde::spatial {
|
||
|
|
|
||
|
|
template <typename T>
|
||
|
|
class SpatialIndex {
|
||
|
|
public:
|
||
|
|
virtual ~SpatialIndex() = default;
|
||
|
|
virtual void build(const std::vector<T>& items) = 0;
|
||
|
|
virtual void insert(const T& item) = 0;
|
||
|
|
virtual bool remove(const T& item) = 0;
|
||
|
|
virtual std::vector<T> query_range(const AABB3D& range) const = 0;
|
||
|
|
virtual std::vector<T> query_knn(const Point3D& point, size_t k) const = 0;
|
||
|
|
virtual std::vector<T> query_ray(const Ray3Dd& ray) const = 0;
|
||
|
|
virtual void clear() = 0;
|
||
|
|
virtual size_t size() const = 0;
|
||
|
|
};
|
||
|
|
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
### 2.2 曲线求值接口
|
||
|
|
|
||
|
|
```cpp
|
||
|
|
namespace vde::curves {
|
||
|
|
|
||
|
|
template <typename T, size_t Dim>
|
||
|
|
class CurveBase {
|
||
|
|
public:
|
||
|
|
virtual ~CurveBase() = default;
|
||
|
|
virtual int degree() const = 0;
|
||
|
|
virtual std::pair<double, double> domain() const = 0;
|
||
|
|
virtual Point<T, Dim> evaluate(double t) const = 0;
|
||
|
|
virtual Vector<T, Dim> derivative(double t, int order = 1) const = 0;
|
||
|
|
virtual const std::vector<Point<T, Dim>>& control_points() const = 0;
|
||
|
|
};
|
||
|
|
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
### 2.3 网格数据结构接口
|
||
|
|
|
||
|
|
```cpp
|
||
|
|
namespace vde::mesh {
|
||
|
|
|
||
|
|
class MeshBase {
|
||
|
|
public:
|
||
|
|
virtual ~MeshBase() = default;
|
||
|
|
virtual size_t num_vertices() const = 0;
|
||
|
|
virtual size_t num_faces() const = 0;
|
||
|
|
virtual const Point3D& vertex(size_t idx) const = 0;
|
||
|
|
virtual std::vector<size_t> vertex_faces(size_t idx) const = 0;
|
||
|
|
virtual Vector3D face_normal(size_t idx) const = 0;
|
||
|
|
virtual Vector3D vertex_normal(size_t idx) const = 0;
|
||
|
|
virtual bool is_boundary_vertex(size_t idx) const = 0;
|
||
|
|
virtual void update_normals() = 0;
|
||
|
|
};
|
||
|
|
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
### 2.4 布尔运算接口
|
||
|
|
|
||
|
|
```cpp
|
||
|
|
namespace vde::boolean {
|
||
|
|
|
||
|
|
enum class BooleanOp { Union, Intersection, Difference, SymDiff };
|
||
|
|
|
||
|
|
template <typename GeometryType>
|
||
|
|
class BooleanEngine {
|
||
|
|
public:
|
||
|
|
virtual ~BooleanEngine() = default;
|
||
|
|
virtual GeometryType execute(
|
||
|
|
const GeometryType& a, const GeometryType& b, BooleanOp op) = 0;
|
||
|
|
virtual void set_tolerance(double tol) = 0;
|
||
|
|
};
|
||
|
|
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 3. 稳定 C API（可选）
|
||
|
|
|
||
|
|
为跨语言绑定提供纯 C 接口：
|
||
|
|
|
||
|
|
```c
|
||
|
|
// 创建与销毁上下文
|
||
|
|
vde_ctx_t vde_engine_create(void);
|
||
|
|
void vde_engine_destroy(vde_ctx_t ctx);
|
||
|
|
|
||
|
|
// 布尔运算
|
||
|
|
vde_mesh_t vde_boolean_union(vde_ctx_t ctx, vde_mesh_t a, vde_mesh_t b);
|
||
|
|
|
||
|
|
// 网格简化
|
||
|
|
vde_mesh_t vde_mesh_simplify(vde_ctx_t ctx, vde_mesh_t m, double ratio);
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 4. 错误处理约定
|
||
|
|
|
||
|
|
- 所有公开 API 返回值使用 `Result<T>` 类型（`std::expected<T, ErrorCode>` 的兼容实现）
|
||
|
|
- 错误码枚举定义于 `vde/foundation/error_codes.h`
|
||
|
|
- 内部实现可使用断言（`assert`），但公开 API 不抛异常
|
||
|
|
- `using Result<T> = tl::expected<T, ErrorCode>;`
|
||
|
|
|
||
|
|
| 错误码 | 说明 |
|
||
|
|
|--------|------|
|
||
|
|
| `kSuccess` | 操作成功 |
|
||
|
|
| `kInvalidArgument` | 非法参数 |
|
||
|
|
| `kInvalidGeometry` | 非法几何（退化/非流形） |
|
||
|
|
| `kDegenerateCase` | 退化情况 |
|
||
|
|
| `kNotImplemented` | 未实现 |
|
||
|
|
| `kNumericalError` | 数值计算错误 |
|