Files
ViewDesignEngine/python
..

VDE Python 绑定(ctypes 路径)

本目录提供两条 Python 绑定路径:

  1. 原生 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。
  2. 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):

  1. 环境变量 VDE_LIBRARY(显式 DLL 路径);
  2. 环境变量 VDE_BUILD_DIR 指定的构建目录,然后仓库 build/、build-*;
  3. 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 只含纯 Python vde 包,不包含 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 时注册可选 CTest VDE_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 解码并对非法字节做替换,不抛异常。