t3d-surface-hole/README.md

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

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

插件由两部分组成：

- **Python 前端**：基于 Blender `bpy` 的算子（Operator）与菜单，负责交互、参数管理、
  模型导入导出。
- **C++ 后端**：位于 `src/`，通过 [pybind11](https://github.com/pybind/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` 控制参数，然后运行：

```bash
./blender -b -P batch_surface_hole.py
```

## 说明

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