Skill: lzyling/blender-render (version 1.0.0)

--- name: blender-render description: Automate Blender headless previews for STL/OBJ/FBX/BIM and multi-part 3D-print models. Use for local-path model import, Workbench orthographic previews, stable part colors, exploded views, contact sheets, simple Cycles beauty renders, and BIM fallback snapshots without opening the Blender UI. --- # 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: ```bash ${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. ```bash 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: ```bash 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: ```bash 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: ```bash 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: ```bash 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.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)