Blender 无界面渲染工作流

当用户需要从本地 3D 资产（如 STL/OBJ/PLY 打印模型、多部件模型文件夹，或 BIM/Revit 导出的 FBX）快速、可靠地生成预览图像时，请使用本技能。若需执行实际的 3D 打印分件、间隙校验、3MF 合规性验证或装配适配调试，请改用专用的 3D 打印工作流；本技能仅用于生成预览图/渲染图。

当前运行假设

• 技术预览优先采用 Workbench 渲染器 + 正交相机：该组合在无界面模式下运行快速稳定，且能清晰呈现几何结构与部件颜色。
• 仅当用户明确要求更高质量的“美型渲染”（beauty render）时，才使用 Cycles；其渲染速度较慢，且对 GPU/渲染设置更为敏感。
• 不假定固定 Blender 版本（例如 5.0.1）。应使用主机上已安装并可正常运行的 Blender，推荐为当前稳定版或 LTS 版本。
• 未经用户明确许可，不得安装或升级 Blender。
• 渲染预览图 不构成验证。一张美观的预览图无法证明模型水密性、可打印性或物理装配适配性。

Blender 可执行文件路径

按以下顺序解析 Blender 可执行文件路径：

${BLENDER_BIN:-$(command -v blender || echo /Applications/Blender.app/Contents/MacOS/Blender)}

若该路径不可用，则尝试执行 command -v blender。若未找到 Blender，请先向用户确认是否安装。

工作流 1：面向打印交付的多部件 STL/OBJ 预览

这是技术交付预览的首选工作流：采用确定性着色、正交前视图/等轴测图、可选爆炸图布局，并生成可用于聊天沟通或切片器审查的拼贴图（contact sheet）。

BLENDER_BIN="${BLENDER_BIN:-/Applications/Blender.app/Contents/MacOS/Blender}"
"$BLENDER_BIN" --background 
  --python scripts/render_stl_set_preview.py -- 
  --input /path/to/final_parts_dir 
  --output-dir /path/to/preview 
  --prefix model-preview 
  --explode 0.35

若源格式携带可用的导入材质（例如 OBJ+MTL），可添加 --preserve-materials 参数；对于纯 STL 交付预览，建议不启用该参数，以便脚本自动分配高对比度、稳定的部件颜色。若尚未安装 Pillow 库，生成拼贴图将失败，此时请运行 python3 -m pip install pillow 进行安装。

随后可选生成带标签的拼贴图：

python3 scripts/make_contact_sheet.py 
  --output /path/to/preview/model-preview-contact-sheet.png 
  --image /path/to/preview/model-preview-front.png --label 正面预览 
  --image /path/to/preview/model-preview-iso.png --label 透视预览

质量检查要点：

• 各部件在图像中明显分离，或通过颜色清晰区分；
• 正交前视图未被裁剪；
• 等轴测图展示了关键接口区域；
• 文件名与标签确保预览图在本对话之外仍具备可理解性。

工作流 2：标准单网格美型渲染

适用于目标为获得更高质量预览（含程序化材质与光照）的 STL/OBJ 模型：

BLENDER_BIN="${BLENDER_BIN:-/Applications/Blender.app/Contents/MacOS/Blender}"
"$BLENDER_BIN" --background 
  --python scripts/render_standard.py -- 
  --input /path/to/model.stl 
  --output /path/to/output_prefix 
  --device auto 
  --samples 64 
  --resolution 1400

输出文件包括 *_front.png、*_side.png 和 *_top.png。使用 --device cpu 可进行便携式冒烟测试（smoke test）；仅当 GPU 渲染已正确配置时，才使用 --device gpu。

工作流 3：BIM/Revit FBX 回退快照

BIM FBX 文件常因层级或材质问题导致导入异常，在 Cycles/Eevee 中可能显示为全黑。此时应强制使用 Workbench 渲染器并启用可见性强制策略：

BLENDER_BIN="${BLENDER_BIN:-/Applications/Blender.app/Contents/MacOS/Blender}"
"$BLENDER_BIN" --background 
  --python scripts/render_bim.py -- 
  --input /path/to/structure.fbx 
  --output /path/to/structure-preview.png

需持续保留的近期经验总结

• 优先使用 Workbench。 在几何结构审查场景中，Workbench/MATCAP 或 Workbench/STUDIO 比写实渲染更有价值。
• 正交相机优于透视相机。 判断部件布局与尺寸关系时，正交视角更具准确性。
• 颜色稳定性至关重要。 对于 STL 交付截图，应为每个对象/文件分配确定性的材质颜色；仅当源格式确实包含有意义的材质数据时，才启用 --preserve-materials。
• 爆炸图仅为预览用途。 原始对象应保持隐藏或完全不动；所有爆炸效果均须通过对副本对象施加偏移实现。
• 大文件应保留在本地。 若通过聊天窗口上传大型 FBX/STL/3MF 文件不可靠，请请求用户提供由操作系统文件管理器复制的本地绝对路径。
• 切勿混淆渲染与验证。 在打印/切片器交付流程中，预览图必须与对应工作流生成的几何/3MF 验证报告配套使用。

脚本维护冒烟测试

修改打包脚本后，至少应执行以下编译检查：

python3 -m py_compile scripts/*.py

真实的 Blender 渲染冒烟测试效果更佳，但仅当 Blender 可用且用户允许访问所选本地模型路径时，方可执行该测试。