Blender Headless Rendering Workflow

Use this skill when the user needs quick, reliable images from local 3D assets: STL/OBJ/PLY print models, multi-part model folders, or BIM/Revit FBX exports. For actual 3D-print splitting, clearance, 3MF validation, or assembly-fit debugging, use a dedicated 3D-print workflow instead; this skill only produces previews/renders.

Current operating assumptions

• Prefer Workbench + orthographic camera for technical previews. It is fast, stable in headless mode, and shows geometry/part colors clearly.
• Use Cycles only when the user specifically wants a nicer beauty render; it is slower and more sensitive to GPU/render settings.
• Do not assume a fixed Blender version like 5.0.1. Use the installed Blender that works on the host, ideally current stable/LTS.
• Do not install or upgrade Blender without explicit user permission.
• Render previews are not validation. A pretty preview does not prove watertightness, printability, or physical assembly fit.

Blender executable

Resolve Blender in this order:

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

If that path fails, try command -v blender. If Blender is missing, ask before installing.

Workflow 1: multi-part STL/OBJ preview for print handoff

This is the preferred workflow for technical handoff previews: deterministic colors, orthographic front/iso views, optional exploded layout, and a contact sheet for chat/slicer review.

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

If the source format carries useful imported materials (for example OBJ+MTL), add --preserve-materials. For plain STL handoff previews, leave it off so the script assigns stable high-contrast colors. Contact sheets require Pillow (python3 -m pip install pillow) if it is not already available.

Then optionally create a labeled contact sheet:

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 透视预览

Quality checks:

• Parts are visibly separated or clearly color-coded.
• Orthographic front view is not clipped.
• Iso view shows the important interfaces.
• File names and labels make the preview understandable outside this chat.

Workflow 2: standard single-mesh beauty render

For STL/OBJ models where the goal is a nicer preview with procedural material and lighting:

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

This emits *_front.png, *_side.png, and *_top.png. Use --device cpu for portable smoke tests; use --device gpu only when GPU rendering is configured.

Workflow 3: BIM/Revit FBX fallback snapshot

BIM FBX often imports with hierarchy/material problems and may appear black in Cycles/Eevee. Use Workbench and force visibility:

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

Recent lessons to preserve

• Workbench first. For geometry review, Workbench/MATCAP or Workbench/STUDIO is more useful than photorealistic rendering.
• Orthographic cameras beat perspective for judging part layout and dimensions.
• Stable colors matter. Assign deterministic material colors per object/file for STL handoff screenshots; preserve imported materials only when the source format actually carries meaningful material data.
• Exploded copies are previews only. Keep source objects hidden or untouched; render duplicated preview objects with offsets.
• Large files should stay local. If chat upload is unreliable for large FBX/STL/3MF files, ask for a local absolute path copied from the OS file manager.
• Do not confuse render with validation. For print/slicer handoff, pair previews with geometry/3MF validation reports from the relevant workflow.

Script maintenance smoke test

After editing bundled scripts, at least run:

python3 -m py_compile scripts/*.py

A real Blender render smoke test is better, but only run it when Blender is available and the user permits access to the chosen local model paths.