VDE Python 绑定(ctypes 路径)
本目录提供两条 Python 绑定路径:
- 原生 pybind11 模块
_vde(-DVDE_BUILD_PYTHON=ON):类型化 API 子集 (core/curves/mesh/brep/sdf/cam + assembly-level API),需要与 CPython 解释器 ABI 兼容的工具链(Windows 上为 MSVC)编译。AssemblyNode 树不暴露 (vector<unique_ptr>holder 限制);Assembly.add_part/add_subassembly、add_part_to/add_subassembly_to/remove/find/clear、visit_parts与只读Assembly.tree()(dict/list)可用;完整树操作仍走 ctypes。 已验证 MSVC + CPython 3.11/3.14(_vde.cp311/_vde.cp314);构建脚本见python/build_native_msvc.ps1。原生 wheel 可用python/build_native_wheel.py --pyd ... --tag ...打包(不依赖 setuptools/wheel), 已在 Python 3.11 和 3.14 上完成本地安装 +vde.brep.make_box验证; cp311/cp314 两个 wheel 都已验证vde.assembly.Assembly.add_part。 - ctypes 路径
vde._ctypes(默认推荐,离线可用):不依赖编译器/ABI, 通过vde_capi_shared目标生成的vde_capi.dll(Linux/macOS 为.so/.dylib) 直接调用 C API:include/vde/capi/vde_capi.h当前声明 61 个函数,ctypes 包装python/vde/_ctypes.py已绑定 60 个(基础 48 + Phase6 显示/B-Rep 查询及扩展 12;vde_body_to_wireframe_opt2尚未绑定,见「已知边界」)。
vde.native 指示实际加载的是哪条路径;两条路径的常用对象均可用:
from vde import _ctypes as vde # ctypes 路径(无需 pybind11)
# from vde import Body, Mesh, Sdf ... # 原生路径可用时也可直接导入
box = vde.Body.create_box(10, 10, 10)
mesh = box.to_mesh(0.5)
print(mesh.num_vertices(), mesh.num_faces())
mesh.free()
box.free()
环境与构建
# 1) 构建共享 C API(必需)
cmake --build build --target vde_capi_shared -j 8
# 2) 运行全量离线 smoke(25 项检查,覆盖全部 C API 族 + 显示/B-Rep 查询)
# 也可直接通过 CMake/CTest 运行(见下节「CTest / CI」)
python python/smoke_test_ctypes.py
# 或显式指定 DLL:
python python/smoke_test_ctypes.py --library build/src/libvde_capi.dll
加载顺序(vde/vde/_ctypes.py):
- 环境变量
VDE_LIBRARY(显式 DLL 路径); - 环境变量
VDE_BUILD_DIR指定的构建目录,然后仓库build/、build-*; - Windows 下自动查找 MinGW runtime(
libstdc++-6/libgomp-1/libwinpthread-1等), 支持VDE_DLL_DIR追加目录。
打包与安装(wheel / sdist,P4-12)
wheel 是纯 Python ctypes 包(vde/*.py),运行时不依赖 pybind11、编译器或 VDE 源码;
使用前按上节构建/指定 vde_capi 共享库。
cd python
python -m build --wheel --sdist --outdir ../build-fb-pypkg/dist --no-isolation
# 离线/无 build 模块时可用:
# python -m pip wheel --no-build-isolation --no-deps -w ../build-fb-pypkg/dist .
# 临时 venv 安装并做 import + ctypes 最小检查
python -m venv ../build-fb-pypkg/venv
../build-fb-pypkg/venv/Scripts/python -m pip install --no-index --no-deps \
../build-fb-pypkg/dist/vde-1.0.87-py3-none-any.whl # Linux: venv/bin/python
../build-fb-pypkg/venv/Scripts/python -c "import vde; print(vde.__version__, vde.native);
lib = vde.load(r'<build>/src/libvde_capi.dll'); print(vde.version())"
pyproject.toml使用 setuptools backend(PEP 621 元数据),setup.py仅为兼容 shim;MANIFEST.in保证 sdist 含vde/*.py、README、pyproject/setup/MANIFEST 与 smoke 脚本; wheel 只含纯 Pythonvde包,不包含 C++ 源/原生扩展;- 完整 ctypes smoke:把
smoke_test_ctypes.py复制到临时目录(避免python/源码路径遮蔽), 用 venv Python 以--library <vde_capi DLL/SO>运行(见「Smoke 覆盖」); - 打包依赖:Python 3.8+、
setuptools/wheel/build(离线时用--no-isolation,无需网络)。
原生 pybind11 模块 _vde(未打包,环境阻塞):需要 CPython 开发包 + pybind11 + 与解释器
ABI 兼容的工具链(Windows 官方 CPython 需 MSVC);本工作树 MinGW 下 CMake 明确跳过原生模块,
无法生成可发布的 _vde 扩展。wheel/sdist 故意只发布 ctypes 路径,不包含/不声称原生模块可用;
如需原生绑定,应在匹配工具链上以 -DVDE_BUILD_PYTHON=ON 单独构建,再另行打包。
CTest / CI(P4-Python 回归)
- CMake 在
BUILD_TESTS=ON时注册可选 CTestVDE_PythonCtypesSmoke:- 通过
find_package(Python3 COMPONENTS Interpreter QUIET)查找解释器;找不到时跳过 (configure 输出 STATUS 说明,不失败); - 需要
vde_capi_shared构建产物;测试命令用$<TARGET_FILE:vde_capi_shared>传入--library,Windows(vde_capi.dll)/Linux(libvde_capi.so)/macOS(.dylib)通用; - 默认
VDE_BUILD_PYTHON=OFF只跑 ctypes smoke,不需要 pybind11;
- 通过
-DVDE_BUILD_PYTHON=ON:原生_vde需要 CPython 开发包 + pybind11 + 与工具链 ABI 兼容 (Windows 官方 CPython 需 MSVC);MinGW 下 CMake 明确提示跳过原生模块 (native pybind11 module skipped on MinGW (CPython/MSVC ABI mismatch)),不导致 configure/build 失败,ctypes 路径与 CTest 仍可用;- 命令:
# 构建(ctypes 只需 C API 共享库;默认构建已包含)
cmake --build build --target vde_capi_shared -j 8
ctest --test-dir build -R VDE_PythonCtypesSmoke --output-on-failure
CI 建议:全量 cmake --build 后跑上述 CTest;无 Python3 的构建机该测试自动跳过,
不影响默认全量 build/ctest。
API 覆盖矩阵(基础 55 项;C API 头共 61,ctypes 已绑定 60/61)
| # | C API | Python 包装 | 说明 |
|---|---|---|---|
| 1 | vde_create |
Context() / create_context() |
显式引擎上下文 |
| 2 | vde_destroy |
Context.close() |
上下文释放 |
| 3 | vde_version |
version() |
版本字符串 |
| 4 | vde_last_error |
last_error(ctx=None) |
最近错误文本 |
| 5 | vde_load_mesh |
Mesh.load() / load_mesh() |
OBJ/STL/PLY/3MF/glTF/OFF |
| 6 | vde_save_mesh |
Mesh.save(path, fmt) |
网格写出 |
| 7 | vde_mesh_num_vertices |
Mesh.num_vertices() |
|
| 8 | vde_mesh_num_faces |
Mesh.num_faces() |
|
| 9 | vde_mesh_get_vertex |
Mesh.get_vertex(i) |
返回 (x,y,z) |
| 10 | vde_mesh_get_bounds |
Mesh.get_bounds() |
返回 (min, max) |
| 11 | vde_mesh_free |
Mesh.free() / with Mesh |
|
| 12 | vde_mesh_simplify |
Mesh.simplify(ratio) |
返回新网格 |
| 13 | vde_mesh_smooth |
Mesh.smooth(iterations) |
返回新网格 |
| 14 | vde_mesh_boolean |
Mesh.boolean(other, op) |
op: union/intersection/difference 或 0/1/2 |
| 15 | vde_curve_create_bezier |
Curve.create_bezier(points) |
3D Bezier |
| 16 | vde_curve_evaluate |
Curve.evaluate(t) |
返回 (x,y,z) |
| 17 | vde_curve_degree |
Curve.degree() |
|
| 18 | vde_curve_free |
Curve.free() |
|
| 19 | vde_collision_gjk_spheres |
gjk_spheres(c1,r1,c2,r2) |
GJK 球-球相交 |
| 20 | vde_collision_ray_mesh |
ray_mesh(mesh, origin, dir) |
返回 (hit,t,point) |
| 21 | vde_body_create_box |
Body.create_box(w,h,d) |
|
| 22 | vde_body_create_cylinder |
Body.create_cylinder(r,h,segs) |
|
| 23 | vde_body_create_sphere |
Body.create_sphere(r,su,sv) |
|
| 24 | vde_body_to_mesh |
Body.to_mesh(deflection) |
|
| 25 | vde_body_free |
Body.free() |
|
| 26 | vde_body_clone |
Body.clone() |
|
| 27 | vde_body_load_step |
Body.load_step(path) |
返回 list[Body](多实体) |
| 28 | vde_body_load_iges |
Body.load_iges(path) |
返回 list[Body](多实体) |
| 29 | vde_body_save_step |
Body.save_step(bodies, path) |
|
| 30 | vde_body_save_iges |
Body.save_iges(bodies, path) |
|
| 31 | vde_body_boolean |
Body.boolean(other, op) |
op 同上 |
| 32 | vde_mesh_get_face |
Mesh.get_face(face_idx) |
返回顶点索引列表;内部按契约 vde_free_buffer |
| 33 | vde_sdf_sphere |
Sdf.sphere(r) |
|
| 34 | vde_sdf_box |
Sdf.box(hx,hy,hz) |
|
| 35 | vde_sdf_cylinder |
Sdf.cylinder(r,h) |
|
| 36 | vde_sdf_union |
Sdf.union(other) |
|
| 37 | vde_sdf_intersection |
Sdf.intersection(other) |
|
| 38 | vde_sdf_difference |
Sdf.difference(other) |
|
| 39 | vde_sdf_to_mesh |
Sdf.to_mesh(resolution) |
返回 Mesh |
| 40 | vde_sdf_free |
Sdf.free() |
|
| 41 | vde_assembly_create |
Assembly.create(name) |
|
| 42 | vde_assembly_add_part |
Assembly.add_part(name, body) |
装配持有副本 |
| 43 | vde_assembly_part_count |
Assembly.part_count() |
|
| 44 | vde_assembly_free |
Assembly.free() |
先释放装配,再释放 body |
| 45 | vde_body_free_array |
body_free_array(ptr,count) |
低层;STEP/IGES 多实体加载内部已按契约使用 |
| 46 | vde_serialize_mesh |
Mesh.serialize() |
返回 bytes;内部 vde_free_buffer |
| 47 | vde_deserialize_mesh |
Mesh.deserialize(data) |
|
| 48 | vde_free_buffer |
free_buffer(ptr) |
低层 C 缓冲区释放 |
| 49 | vde_body_to_display_mesh |
Body.to_display_mesh(...) |
Phase6:平滑法线 + 面 ID + 曲面类型显示网格;DisplayMesh 拷贝后自动释放 C 缓冲 |
| 50 | vde_body_to_wireframe |
Body.to_wireframe(...) |
Phase6:精确 B-Rep 边线/圆/样条线框;Wireframe |
| 51 | vde_body_get_face_count |
Body.face_count() |
Phase6:B-Rep 面数 |
| 52 | vde_body_get_face_info |
Body.face_info(i) |
Phase6:FaceInfo(surface_kind/reversed/visible/bbox/params) |
| 53 | vde_body_get_edge_count |
Body.edge_count() |
Phase6:B-Rep 边数 |
| 54 | vde_body_get_edge_info |
Body.edge_info(i) |
Phase6:EdgeInfo(kind/radius/center/axis/angles);圆边半径精确 |
| 55 | vde_body_get_edge_polyline |
Body.edge_polyline(i, tol) |
Phase6:单边按弦高采样;内部 vde_free_buffer |
覆盖核对:上表 55 项主路径 C API 均有 Python 入口(含低层
free_buffer/body_free_array;高层便捷用法优先使用类方法)。vde_capi.h另有 6 个 Phase6 扩展变体(vde_body_to_display_mesh_{ex,lod,opt}、vde_body_to_wireframe_{ex,opt,opt2}); ctypes 包装已绑定其中 5 个,vde_body_to_wireframe_opt2暂未绑定——总计 60/61。
内存释放契约
- 每个
Body/Mesh/Curve/Sdf/Assembly/Context均支持.free()和上下文管理器(with ... as h:自动释放);释放后句柄不可再用。 Body.load_step/load_iges返回独立Body列表:C API 返回的句柄数组按vde_body_free_array语义整体释放,包装层为每个实体vde_body_clone出独立句柄供 Python 持有,避免悬垂/双重释放。Mesh.get_face/Mesh.serialize返回的缓冲区由库分配,包装层在拷贝数据后 立即用vde_free_buffer释放,符合 C API 文档。Body.save_step/save_iges不转移 body 所有权;Assembly保存 part 副本, 释放顺序建议先Assembly.free()再Body.free()(见 C API 文档)。
Smoke 覆盖(python/smoke_test_ctypes.py,无需 pybind11)
25 项检查(ctest -R VDE_PythonCtypesSmoke / 本机 build-fb-pytest)全部 PASS:
- 诊断/上下文:
version、last_error、Context创建/销毁; - B-Rep:box/cylinder/sphere、clone、union/intersection/difference、to_mesh;
- Phase6 显示/B-Rep 查询:box display mesh(24V/12T/6 面/法线/面 ID/Plane 类型)、 box wireframe 12 段、cylinder 圆边 kind=Circle/radius=4/折线半径校验、 face/edge info、越界错误拒绝;
- STEP + IGES 导出/导入往返(多实体加载、包围盒/网格数校验);
- Mesh:load/save(OBJ)、vertices/faces/get_vertex/get_bounds/get_face、 simplify/smooth、mesh boolean、serialize/deserialize;
- Curve:Bezier 创建/求值/次数;
- Collision:GJK 球相交 hit/miss、ray-mesh hit/miss(t=45、命中点校验);
- SDF:sphere/box/cylinder 与 union/intersection/difference 的 to_mesh;
- Assembly:create/add_part×2/part_count/free;
- 内存:100 次 body+mesh+get_face / 100 次 curve / 100 次 context 创建释放循环无崩溃;STEP 多实体往返 + STEP 连续 10 次 load/free(
vde_body_free_array契约); - 错误契约:缺失网格文件 →
RuntimeError(不崩溃、不静默)。
运行:
# Windows(构建产物路径由 CMake 生成器表达式在 CTest 中自动传入)
python python/smoke_test_ctypes.py --library build/src/libvde_capi.dll
# Linux / macOS
python python/smoke_test_ctypes.py --library build/src/libvde_capi.so
# => SMOKE PASS: 25 passed, 0 failed
也可用 CMake/CTest(自动选择当前构建产物,Python3 可选):
ctest --test-dir build -R VDE_PythonCtypesSmoke --output-on-failure
已知边界
- ctypes 路径只覆盖
vde_capi.h声明的 C API(C API 未暴露的模块,如装配导出、 PMI/STEP 完整语义、DWG 等,不在本绑定范围;原生 pybind11 路径可提供更多模块)。 vde_body_to_wireframe_opt2目前未在python/vde/_ctypes.py绑定(其余 60 个均绑定; 绑定补齐后需同步更新本节与 smoke 覆盖说明)。vde_mesh_simplify的target_ratio语义由 C API 决定(当前实现返回简化结果, 网格用例见 smoke);vde_load_mesh按扩展名识别格式,fmt形参仅为兼容保留。vde_last_error文本由 C API 返回(中文错误串随终端编码显示);包装层按 UTF-8 解码并对非法字节做替换,不抛异常。