batch-t3d — 表面圆孔纹理 Blender 插件

batch-t3d（Batch Design Auto）是一个 Blender 插件，用于在三维网格表面自动生成 镂空 / 圆孔纹理，并提供批量处理、手动选面、场驱动纹理以及纹理库等能力。常见应用 场景为牙科 / CAD 模型（冠、桥、coping 等）的表面纹理化设计。

插件由两部分组成：

• Python 前端：基于 Blender bpy 的算子（Operator）与菜单，负责交互、参数管理、 模型导入导出。
• C++ 后端：位于 src/，通过 pybind11 封装为 Python 扩展（dapy_t3d_surface_hole、dapy_qss_fem_tetrahedral），完成 采样、参数化、网格打孔等几何计算；同时可编译为命令行可执行文件 t3d-surface-hole。

说明：编译产物（*.so、可执行文件）、测试模型（*.stl、大型 *.obj）以及运行时 中间文件不纳入版本库，请按下文自行构建 / 准备。

功能

通过 3D 视图顶部菜单 Batch Design Auto 调用，对应模块见 manifest.py：

菜单项	算子 idname	模块	说明
圆孔纹理	designauto.texture_3d_surface_hole	bld_texture_3d	对单个选中网格生成表面圆孔纹理
批量圆孔纹理	designauto.batch_texture_3d_surface_hole	bld_batch_texture_3d	批量处理 assets/ 下的多个模型
手动选面	designauto.manual_texture_3d_surface_hole	bld_manual_selection	手动选择面后再打孔
场驱动纹理	designauto.quasistatic_simulation_fem_tetrahedral	bld_quasistatic_simulation	基于四面体有限元准静态仿真的应力场驱动纹理
纹理库	designauto.lattice_library	bld_lattice_library	内置点阵 / 纹理样式库

孔类型

texture_style 参数与孔形状的对应关系：

编号	形状
1	圆台1
2	圆台2
3	圆柱
4	方形
5	三角形
6	六边形
7	八边形

目录结构

.
├── __init__.py                  # 插件入口，注册 bl_info / 菜单
├── auto_load.py                 # 自动发现并注册各子模块中的 Blender 类
├── menu.py / manifest.py        # 菜单与菜单项清单
├── project_config.py            # 运行时目录约定（exe/Release、lib/Release、Workplace）
├── bld_texture_3d/              # 单模型圆孔纹理
├── bld_batch_texture_3d/        # 批量圆孔纹理
├── bld_manual_selection/        # 手动选面
├── bld_quasistatic_simulation/  # 场驱动（有限元）纹理
├── bld_lattice_library/         # 纹理 / 点阵库
├── src/                         # C++ 后端源码（pybind11 + 命令行）
└── 放到blender程序所在文件夹/      # 无头(headless)批处理脚本与操作说明

运行依赖

• Blender 2.80+（bl_info 声明的最低版本，开发使用 Python 3.10）。
• C++ 后端编译产物，需放置到 project_config.py 约定的路径：
  • lib/Release/dapy_t3d_surface_hole.cpython-310-*.so
  • lib/Release/dapy_qss_fem_tetrahedral.cpython-310-*.so
  • exe/Release/t3d-surface-hole（命令行可执行）
• 运行时工作目录 exe/Workplace/，包含三个子目录：
  • assets/：输入模型
  • parameters/：参数与配置文件（如 single.txt、input.txt、config.json）
  • results/：输出结果

构建 C++ 后端

src/ 依赖 pybind11、Eigen、spdlog，以及内部 sha-* 框架 （sha-base-framework、sha-entry-framework、sha-io-foundation、sha-surface-mesh）。 通过编译宏选择产物类型：

• 定义 DA_PY：编译为 Python 扩展模块 dapy_t3d_surface_hole。
• 定义 DA_CMD：编译为命令行程序 t3d-surface-hole，支持 --hole_height、 --radius_factor、--texture_style 等参数（详见 src/entry.cpp）。

将生成的 .so 与可执行文件分别放入 lib/Release/ 与 exe/Release/。

使用

在 Blender GUI 中

1. 将插件目录安装到 Blender 的 addons 目录并启用。
2. 准备好 C++ 后端产物（见上）。
3. 在 3D 视图顶部菜单 Batch Design Auto 中选择对应功能，按弹窗设置参数后执行。

无头批处理

参考 放到blender程序所在文件夹/操作说明.txt：将该文件夹下的脚本与产物放到 Blender 可执行文件所在目录，准备好 exe/Workplace/{assets,parameters,results}， 通过 parameters/input.txt 控制参数，然后运行：

./blender -b -P batch_surface_hole.py

说明

• 仓库仅纳入源代码（Python / C++）与本说明。编译产物、测试模型、运行中间文件 及任何凭据文件均不纳入版本控制，请勿提交。
• 作者：kwp