基础模块

数学类型、公差系统、精确谓词、文件 I/O、序列化 更多...

类
class	vde::foundation::Interval
	双精度区间算术类 更多...
struct	vde::foundation::GltfOptions
	glTF 2.0 导出选项 更多...
struct	vde::foundation::ObjMeshData
	OBJ 文件解析结果数据结构 更多...
struct	vde::foundation::StlTriangle
	STL 三角形面片 更多...
class	vde::foundation::MemoryPool< T >
	固定块大小的内存池 更多...
struct	vde::foundation::Predicates
	统一谓词接口 — 编译时选择 GMP 或自适应双精度后端 更多...
struct	vde::foundation::SerializedMesh
	二进制序列化格式的网格数据结构 更多...
class	vde::foundation::BinarySerializer
	二进制序列化器 更多...
class	vde::foundation::Tolerance
	分层容差管理类 更多...
class	vde::foundation::ToleranceScope
	局部容差作用域（RAII） 更多...

类型定义
template<typename T , size_t Dim>
using	vde::foundation::Point = Eigen::Matrix< T, Dim, 1 >
	通用 N 维点类型（使用 Eigen 列向量） 更多...
template<typename T , size_t Dim>
using	vde::foundation::Vector = Eigen::Matrix< T, Dim, 1 >
	通用 N 维向量类型（与 Point 相同的列向量表示） 更多...

枚举
enum class	vde::foundation::ErrorCode : int32_t {   vde::foundation::kSuccess = 0 , vde::foundation::kInvalidArgument , vde::foundation::kInvalidGeometry , vde::foundation::kDegenerateCase ,   vde::foundation::kNotImplemented , vde::foundation::kNumericalError , vde::foundation::kOutOfMemory , vde::foundation::kInternalError }
	全局错误码枚举 更多...
enum class	vde::foundation::exact::Orientation { vde::foundation::exact::Clockwise , vde::foundation::exact::CounterClockwise , vde::foundation::exact::Collinear }
	二维定向测试结果 更多...
enum class	vde::foundation::exact::CircleTest { vde::foundation::exact::Inside , vde::foundation::exact::On , vde::foundation::exact::Outside }
	圆测试结果 更多...

函数
Orientation	vde::foundation::exact::orient_2d (const Point2D &a, const Point2D &b, const Point2D &c)
	自适应精度二维定向测试（Shewchuk 算法） 更多...
Orientation	vde::foundation::exact::orient_3d (const Point3D &a, const Point3D &b, const Point3D &c, const Point3D &d)
	自适应精度三维定向测试 更多...
CircleTest	vde::foundation::exact::in_circle (const Point2D &a, const Point2D &b, const Point2D &c, const Point2D &d)
	自适应精度圆内测试（In-Circle Test） 更多...
std::string	vde::foundation::fmt_double (double v, int precision=12)
	以 CAD 级别精度格式化双精度浮点数 更多...
std::string	vde::foundation::fmt_iges_real (double v, int=12)
	IGES 格式实数输出 更多...
std::string	vde::foundation::fmt_point (const core::Point3D &p, bool use_d=false)
	格式化三维点为逗号分隔字符串 更多...
std::string	vde::foundation::pad72 (const std::string &s)
	将字符串填充到恰好 72 个字符 更多...
std::string	vde::foundation::format_iges_line (const std::string &data, char section_char, int seq)
	格式化 IGES 段落行 更多...
Interval	vde::foundation::orient_2d_interval (double ax, double ay, double bx, double by, double cx, double cy)
	二维定向行列式的区间验证 更多...
int	vde::foundation::orient_2d_verified (double ax, double ay, double bx, double by, double cx, double cy)
	使用区间算术验证 orient_2d 结果 更多...
bool	vde::foundation::write_gltf (const std::string &filepath, const mesh::HalfedgeMesh &mesh, const GltfOptions &options=GltfOptions{})
	导出网格为 glTF 2.0 / GLB 格式 更多...
bool	vde::foundation::write_brep_gltf (const std::string &filepath, const brep::BrepModel &model, int tessellation_res=32)
	导出 B-Rep 模型为 GLB 格式（通过面片化） 更多...
ObjMeshData	vde::foundation::read_obj (const std::string &filepath)
	读取 Wavefront OBJ 文件 更多...
void	vde::foundation::write_obj (const std::string &filepath, const ObjMeshData &data)
	写入 Wavefront OBJ 文件 更多...
mesh::HalfedgeMesh	vde::foundation::read_ply (const std::string &filepath)
	读取 PLY 文件（Stanford Polygon Format） 更多...
void	vde::foundation::write_ply (const std::string &filepath, const mesh::HalfedgeMesh &mesh)
	写入 PLY 文件（ASCII 格式） 更多...
std::vector< StlTriangle >	vde::foundation::read_stl (const std::string &filepath)
	读取 STL 文件（自动检测格式） 更多...
void	vde::foundation::write_stl (const std::string &filepath, const std::vector< StlTriangle > &tris)
	写入二进制 STL 文件 更多...
void	vde::foundation::write_stl_ascii (const std::string &filepath, const std::vector< StlTriangle > &tris)
	写入 ASCII STL 文件 更多...
exact::Orientation	vde::foundation::orient (const Point2D &a, const Point2D &b, const Point2D &c)
	二维定向测试便捷封装 更多...
exact::Orientation	vde::foundation::orient (const Point3D &a, const Point3D &b, const Point3D &c, const Point3D &d)
	三维定向测试便捷封装 更多...
exact::CircleTest	vde::foundation::in_circle (const Point2D &a, const Point2D &b, const Point2D &c, const Point2D &d)
	圆内测试便捷封装 更多...

详细描述

数学类型、公差系统、精确谓词、文件 I/O、序列化

基础模块提供 VDE 引擎的核心基础设施：

• 数学类型定义（点、向量、矩阵）
• 精确几何谓词（自适应双精度 + GMP 可选后端）
• 区间算术验证
• 分层容差管理
• 内存池分配
• 文件 I/O（STL、OBJ、PLY、glTF）
• 格式化工具与序列化

提供整个引擎使用的底层基础设施。

类型定义说明

Point

template<typename T , size_t Dim>

using vde::foundation::Point = typedef Eigen::Matrix<T, Dim, 1>

通用 N 维点类型（使用 Eigen 列向量）

模板参数

T	标量类型（double, float 等）
Dim	维度

在文件 math_types.h 第 17 行定义.

Vector

template<typename T , size_t Dim>

using vde::foundation::Vector = typedef Eigen::Matrix<T, Dim, 1>

通用 N 维向量类型（与 Point 相同的列向量表示）

虽然类型相同，但语义上区分几何点（位置）和向量（方向/位移）。

模板参数

T	标量类型
Dim	维度

在文件 math_types.h 第 30 行定义.

枚举类型说明

CircleTest

enum vde::foundation::exact::CircleTest

strong

圆测试结果

判断点 d 相对于三角形 abc 外接圆的位置。

枚举值
Inside
On
Outside

在文件 exact_predicates.h 第 22 行定义.

ErrorCode

enum vde::foundation::ErrorCode : int32_t

strong

全局错误码枚举

VDE 引擎中所有函数可能返回的错误状态码。 成功用 kSuccess(0) 表示，非零值表示各类错误。

枚举值
kSuccess	操作成功完成，无错误
kInvalidArgument	传入参数无效（空指针、越界、非法值等）
kInvalidGeometry	输入几何数据不合法（自交、非流形、退化等）
kDegenerateCase	退化情况（共线、共面等导致无法确定唯一解）
kNotImplemented	功能尚未实现
kNumericalError	数值计算误差超出容差范围
kOutOfMemory	内存分配失败
kInternalError	内部逻辑错误（不应出现的情况）

在文件 error_codes.h 第 14 行定义.

Orientation

enum vde::foundation::exact::Orientation

strong

二维定向测试结果

判断三点构成的三角形的定向（顺时针 / 逆时针 / 共线）。

枚举值
Clockwise
CounterClockwise
Collinear

在文件 exact_predicates.h 第 13 行定义.

函数说明

fmt_double()

std::string vde::foundation::fmt_double ( double  v, int  precision = 12  )

inline

以 CAD 级别精度格式化双精度浮点数

输出科学计数法字符串，保证 12 位有效数字，满足 CAD 数据交换精度要求。 NaN 被格式化为 "0.0"，Inf/ -Inf 被裁剪为安全边界值。

参数

v	要格式化的双精度数
precision	有效数字位数（默认 12）

返回

格式化后的字符串，如 "1.234567890123e+02"

注解

总是确保指数部分带符号（如 "e+00" 而非 "e00"），便于解析器统一处理

auto s = fmt_double(3.14159265358979);
// s == "3.141592653590e+00"

参见

fmt_iges_real, fmt_point

在文件 format_utils.h 第 31 行定义.

被这些函数引用 vde::foundation::fmt_iges_real() , 以及 vde::foundation::fmt_point().

fmt_iges_real()

std::string vde::foundation::fmt_iges_real ( double  v, int  = 12  )

inline

IGES 格式实数输出

与 fmt_double() 相同，但使用 IGES 标准的 'D' 指数标记代替 'E'。

参数

v

要格式化的双精度数

返回

IGES 格式字符串，如 "3.141592653590D+00"

auto s = fmt_iges_real(3.14159265358979);
// s == "3.141592653590D+00"

参见

fmt_double

在文件 format_utils.h 第 63 行定义.

引用了 vde::foundation::fmt_double().

被这些函数引用 vde::foundation::fmt_point().

fmt_point()

std::string vde::foundation::fmt_point ( const core::Point3D &  p, bool  use_d = false  )

inline

格式化三维点为逗号分隔字符串

输出 "x,y,z" 形式，常用于 IGES/STEP/OBJ 等文本格式的顶点坐标行。

参数

p	三维点
use_d	若为 true，使用 IGES 风格 D 指数标记

返回

逗号分隔的坐标字符串

Point3D p(1.0, 2.5, -3.14);
auto s = fmt_point(p);
// s == "1.000000000000e+00,2.500000000000e+00,-3.140000000000e+00"

参见

fmt_double, fmt_iges_real

在文件 format_utils.h 第 88 行定义.

引用了 vde::foundation::fmt_double() , 以及 vde::foundation::fmt_iges_real().

format_iges_line()

std::string vde::foundation::format_iges_line ( const std::string &  data, char  section_char, int  seq  )

inline

格式化 IGES 段落行

生成一条完整的 IGES 80 列记录行：72 列数据 + 8 列序号（section_char + 7 位数字）。

参数

data	数据内容（最多 72 字符，超出截断）
section_char	段落标识符（如 'P' 参数段, 'D' 目录段）
seq	行序号（1-based）

返回

完整 IGES 行（含换行符），共 81 字符

auto line = format_iges_line("110,1.0,2.0,3.0;", 'P', 1);
// 输出: "110,1.0,2.0,3.0;                                      P0000001\n"

参见

pad72

在文件 format_utils.h 第 130 行定义.

引用了 vde::foundation::pad72().

in_circle() [1/2]

CircleTest vde::foundation::exact::in_circle	(	const Point2D &	a,
		const Point2D &	b,
		const Point2D &	c,
		const Point2D &	d
	)

自适应精度圆内测试（In-Circle Test）

判断点 d 是否在三角形 abc 的外接圆内部、边界上或外部。 等价于计算 4×4 行列式的符号。

参数

a	三角形第一个顶点
b	三角形第二个顶点
c	三角形第三个顶点
d	待测试点

返回

CircleTest::Inside 若 d 在三角形外接圆内部

CircleTest::On 若 d 恰好在三角形外接圆上

CircleTest::Outside 若 d 在三角形外接圆外部

注解

Delaunay 三角剖分的空圆性质检查核心原语

前置条件

三点 a、b、c 不共线

Point2D a(0,0), b(2,0), c(0,2);
Point2D d(0.5, 0.5);  // 在外接圆内部
auto result = exact::in_circle(a, b, c, d);
// result == CircleTest::Inside

参见

orient_2d, orient_3d

被这些函数引用 vde::foundation::AdaptiveDouble::in_circle().

in_circle() [2/2]

exact::CircleTest vde::foundation::in_circle ( const Point2D &  a, const Point2D &  b, const Point2D &  c, const Point2D &  d  )

inline

圆内测试便捷封装

参数

a,b,c	三角形三顶点
d	测试点

返回

CircleTest::Inside / On / Outside

在文件 predicates.h 第 100 行定义.

引用了 vde::foundation::Predicates::in_circle().

被这些函数引用 vde::foundation::Predicates::in_circle().

orient() [1/2]

exact::Orientation vde::foundation::orient ( const Point2D &  a, const Point2D &  b, const Point2D &  c  )

inline

二维定向测试便捷封装

使用 Predicates::orient_2d，无需指定后端。 这是推荐的对外 API。

参数

a,b,c

三个二维点

返回

Orientation::Clockwise / CounterClockwise / Collinear

using namespace vde::foundation;
Point2D a(0,0), b(1,0), c(0,1);
auto result = orient(a, b, c); // CounterClockwise

在文件 predicates.h 第 74 行定义.

引用了 vde::foundation::Predicates::orient_2d().

orient() [2/2]

exact::Orientation vde::foundation::orient ( const Point3D &  a, const Point3D &  b, const Point3D &  c, const Point3D &  d  )

inline

三维定向测试便捷封装

参数

a,b,c	定义平面的三点
d	测试点

返回

Orientation::Clockwise / CounterClockwise / Collinear

在文件 predicates.h 第 87 行定义.

引用了 vde::foundation::Predicates::orient_3d().

orient_2d()

Orientation vde::foundation::exact::orient_2d	(	const Point2D &	a,
		const Point2D &	b,
		const Point2D &	c
	)

自适应精度二维定向测试（Shewchuk 算法）

判断点 a, b, c 的定向。使用自适应浮点精度： 先用双精度计算行列式，若结果不可靠则逐步提高精度，直至确定符号。

参数

a	第一个点
b	第二个点
c	第三个点

返回

Orientation::Clockwise 若 a→b→c 顺时针

Orientation::CounterClockwise 若 a→b→c 逆时针

Orientation::Collinear 若三点共线

注解

Delaunay 三角剖分、凸包计算等几何算法的核心原语

警告

输入点坐标必须为有限值，NaN/Inf 会导致未定义行为

Point2D a(0,0), b(1,0), c(0,1);
auto ori = exact::orient_2d(a, b, c);
// ori == Orientation::CounterClockwise

参见

orient_3d, in_circle

被这些函数引用 vde::foundation::AdaptiveDouble::orient_2d() , 以及 vde::foundation::Predicates::orient_2d().

orient_2d_interval()

Interval vde::foundation::orient_2d_interval ( double  ax, double  ay, double  bx, double  by, double  cx, double  cy  )

inline

二维定向行列式的区间验证

用区间算术计算 orient_2d 行列式，结果区间用于判断双精度是否可靠。

参数

ax,ay	点 a 的坐标
bx,by	点 b 的坐标
cx,cy	点 c 的坐标

返回

行列式的区间值

参见

orient_2d_verified

在文件 interval.h 第 200 行定义.

引用了 vde::foundation::Interval::from_coord().

被这些函数引用 vde::foundation::orient_2d_verified().

orient_2d_verified()

int vde::foundation::orient_2d_verified ( double  ax, double  ay, double  bx, double  by, double  cx, double  cy  )

inline

使用区间算术验证 orient_2d 结果

若双精度计算结果接近零，调用此函数进行区间验证。 若区间不跨越零，则结果可靠；否则需要升级到精确算术。

参数

ax,ay	点 a 的坐标
bx,by	点 b 的坐标
cx,cy	点 c 的坐标

返回

-1 确认 Clockwise

0 无法确定（需升级到 GMP / 自适应精度）

1 确认 CounterClockwise

int result = orient_2d_verified(0.0, 0.0, 1.0, 1e-16, 2.0, 2e-16);
if (result == 0) {
    // 双精度不可靠，需要精确算术
    auto ori = GmpExact::orient_2d(a, b, c);
}

参见

orient_2d_interval, Interval::cmp

在文件 interval.h 第 232 行定义.

引用了 vde::foundation::Interval::cmp() , 以及 vde::foundation::orient_2d_interval().

orient_3d()

Orientation vde::foundation::exact::orient_3d	(	const Point3D &	a,
		const Point3D &	b,
		const Point3D &	c,
		const Point3D &	d
	)

自适应精度三维定向测试

判断点 a, b, c, d 的定向（即点 d 在平面 abc 的哪一侧）。 等价于计算四面体 abcd 的有向体积的符号。

参数

a	第一个点
b	第二个点
c	第三个点
d	第四个点（测试点）

返回

Orientation::CounterClockwise 若 d 在平面 abc 上方（按右手法则）

Orientation::Clockwise 若 d 在平面 abc 下方

Orientation::Collinear 若四点共面

注解

三维 Delaunay 剖分和凸包计算的核心原语

Point3D a(0,0,0), b(1,0,0), c(0,1,0), d(0,0,1);
auto ori = exact::orient_3d(a, b, c, d);
// ori == Orientation::CounterClockwise

参见

orient_2d, in_circle

被这些函数引用 vde::foundation::AdaptiveDouble::orient_3d() , 以及 vde::foundation::Predicates::orient_3d().

pad72()

std::string vde::foundation::pad72 ( const std::string &  s )

inline

将字符串填充到恰好 72 个字符

IGES 格式中每条数据行固定为 72 字符宽。不足用空格补齐，超出则截断。

参数

s

输入字符串

返回

恰好 72 字符的字符串（不足右侧补空格，超出截断）

参见

format_iges_line

在文件 format_utils.h 第 105 行定义.

被这些函数引用 vde::foundation::format_iges_line().

read_obj()

ObjMeshData vde::foundation::read_obj

(

const std::string &

filepath

)

读取 Wavefront OBJ 文件

解析 ASCII OBJ 文件，支持以下 OBJ 特性：

• v（顶点）、vt（纹理坐标）、vn（法线）
• f（面）：支持三角面和任意多边形面
• usemtl（材质名称）、g（组名）、o（对象名）
• # 注释行

参数

filepath

OBJ 文件路径

返回

解析后的 ObjMeshData

异常

std::runtime_error

若文件无法打开或格式错误

注解

不解析 MTL 材质文件，仅记录 usemtl 指令中的材质名称

面索引在内部转换为 0-based；若文件中使用相对索引（负值），自动转换为正向

auto data = read_obj("model.obj");
std::cout << "Vertices: " << data.vertices.size() << "\n";
std::cout << "Faces: " << data.faces.size() << "\n";

参见

write_obj, ObjMeshData

read_ply()

mesh::HalfedgeMesh vde::foundation::read_ply

(

const std::string &

filepath

)

读取 PLY 文件（Stanford Polygon Format）

解析 PLY 格式文件，支持 ASCII 和二进制（小端序）两种编码。 支持的 PLY 元素：vertex（位置、法线、颜色）、face（顶点索引列表）。

参数

filepath

PLY 文件路径

返回

解析后的半边网格

异常

std::runtime_error

若文件无法打开、格式不支持或数据损坏

注解

自动检测文件头部 magic number 判断 ASCII / 二进制格式

二进制格式仅支持小端序（little-endian）

返回类型为 HalfedgeMesh，内部自动建立半边拓扑

auto mesh = read_ply("scan.ply");
std::cout << "Vertices: " << mesh.vertex_count() << "\n";
std::cout << "Faces: " << mesh.face_count() << "\n";

参见

write_ply

read_stl()

std::vector<StlTriangle> vde::foundation::read_stl

(

const std::string &

filepath

)

读取 STL 文件（自动检测格式）

通过检查文件头部的 80 字节判断二进制（含 triangle count） 还是 ASCII（以 "solid" 开头）格式，然后选择对应解析器。

参数

filepath

STL 文件路径

返回

三角形面片列表

异常

std::runtime_error

若文件无法打开或格式无效

注解

自动格式检测：二进制 STL 的 80 字节头后跟 4 字节三角形数量

ASCII STL 以 "solid name" 开头

auto tris = read_stl("part.stl");
std::cout << "Triangles: " << tris.size() << "\n";

参见

write_stl, write_stl_ascii

write_brep_gltf()

bool vde::foundation::write_brep_gltf	(	const std::string &	filepath,
		const brep::BrepModel &	model,
		int	tessellation_res = 32
	)

导出 B-Rep 模型为 GLB 格式（通过面片化）

将 B-Rep 模型的参数曲面离散化为三角网格后导出为 GLB。 曲面通过 tessellation_res 控制离散精度。

参数

filepath	输出文件路径（建议 .glb）
model	要导出的 B-Rep 模型
tessellation_res	每条边的离散段数（默认 32），越大越精确

返回

true 导出成功

false 导出失败

brep::BrepModel model = // ...;
// 高精度曲面导出
bool ok = write_brep_gltf("model.glb", model, 64);

参见

write_gltf

write_gltf()

bool vde::foundation::write_gltf	(	const std::string &	filepath,
		const mesh::HalfedgeMesh &	mesh,
		const GltfOptions &	options = GltfOptions{}
	)

导出网格为 glTF 2.0 / GLB 格式

将 HalfedgeMesh 写入 glTF 2.0 规范文件。默认输出单文件 GLB 二进制格式， 可通过 GltfOptions 控制输出格式和包含的属性。

参数

filepath	输出文件路径（.glb 或 .gltf）
mesh	要导出的半边网格
options	导出选项（格式、法线、颜色等）

返回

true 导出成功

false 导出失败（文件无法创建等）

注解

生成的 glTF 符合 2.0 规范，兼容 Blender、three.js、Unreal Engine 等工具

mesh::HalfedgeMesh mesh = // ...;
GltfOptions opts;
opts.binary = true;
opts.include_normals = true;
bool ok = write_gltf("output.glb", mesh, opts);

参见

write_brep_gltf, GltfOptions

write_obj()

void vde::foundation::write_obj	(	const std::string &	filepath,
		const ObjMeshData &	data
	)

写入 Wavefront OBJ 文件

将 ObjMeshData 以 ASCII OBJ 格式写出，包含顶点、纹理坐标、 法线和面信息。材质名称通过注释嵌入。

参数

filepath	输出文件路径
data	要写出的网格数据

注解

输出的面索引为 1-based（OBJ 标准）

ObjMeshData data;
// ... 填充 data ...
write_obj("output.obj", data);

参见

read_obj

write_ply()

void vde::foundation::write_ply	(	const std::string &	filepath,
		const mesh::HalfedgeMesh &	mesh
	)

写入 PLY 文件（ASCII 格式）

将半边网格以 ASCII PLY 格式写出，包含顶点位置和面信息。

参数

filepath	输出文件路径
mesh	要导出的半边网格

注解

输出的 PLY 为 ASCII 编码，易于人工阅读和编辑

若需要二进制输出以提高性能，请使用 BinarySerializer

mesh::HalfedgeMesh mesh = // ...;
write_ply("output.ply", mesh);

参见

read_ply, BinarySerializer

write_stl()

void vde::foundation::write_stl	(	const std::string &	filepath,
		const std::vector< StlTriangle > &	tris
	)

写入二进制 STL 文件

以紧凑的二进制格式写出 STL 三角形列表。 二进制 STL 为业界标准交换格式，文件体积小、读写快。

参数

filepath	输出文件路径
tris	三角形面片列表

注解

二进制 STL 格式：80 字节头 + 4 字节三角形数 + 每三角形 50 字节

法向量在写入时自动归一化

std::vector<StlTriangle> tris = // ...;
write_stl("output.stl", tris);  // 二进制，体积小

参见

read_stl, write_stl_ascii

write_stl_ascii()

void vde::foundation::write_stl_ascii	(	const std::string &	filepath,
		const std::vector< StlTriangle > &	tris
	)

写入 ASCII STL 文件

以人类可读的 ASCII 文本格式写出 STL，便于调试和手动编辑。

参数

filepath	输出文件路径
tris	三角形面片列表

警告

ASCII STL 文件体积约为二进制 STL 的 5-10 倍，不适合大规模网格

std::vector<StlTriangle> tris = // ...;
write_stl_ascii("debug.stl", tris);  // 可读文本，便于调试

参见

read_stl, write_stl