59 lines
4.7 KiB
Markdown
59 lines
4.7 KiB
Markdown
---
|
||
name: blender-local
|
||
description: Build, edit, and render 3D scenes with the locally installed Blender on this Mac. Use when the user requests Blender work or an editable Blender scene.
|
||
---
|
||
|
||
# Local Blender
|
||
|
||
## Installed application
|
||
|
||
The verified executable is `/Applications/Blender.app/Contents/MacOS/Blender` (plural `Applications`, not `/Application/Blender`). It reported Blender 5.1.2 during the September 2026 pelican project. Check the executable if the installation changes; use this local app for Blender requests.
|
||
|
||
## Working workflow
|
||
|
||
Write scene-building scripts in the task's `work/` directory. Execute `bpy` scripts with Blender's bundled Python, not an ordinary Python interpreter:
|
||
|
||
```sh
|
||
/Applications/Blender.app/Contents/MacOS/Blender --background --python work/scene.py
|
||
```
|
||
|
||
For ordinary Python helpers outside Blender, use `uv run`. Set absolute output paths in the Blender script, create the destination directory, and save both the editable `.blend` and rendered PNG to the task's deliverable directory.
|
||
|
||
To edit a saved scene, call `bpy.ops.wm.open_mainfile(filepath=...)` before making changes. Only clear all objects when intentionally building a new scene. Prefer reusable functions or loading the existing `.blend` over executing fragments sliced out of earlier scripts.
|
||
|
||
This finalization pattern worked with the installed version; choose image dimensions and samples for the task:
|
||
|
||
```python
|
||
scene = bpy.context.scene
|
||
scene.render.engine = 'CYCLES'
|
||
scene.cycles.samples = 64
|
||
scene.cycles.use_denoising = True
|
||
scene.render.resolution_x = 1600
|
||
scene.render.resolution_y = 1200
|
||
scene.render.resolution_percentage = 100
|
||
scene.view_settings.view_transform = 'AgX'
|
||
scene.render.image_settings.file_format = 'PNG'
|
||
scene.render.filepath = str(output_dir / 'scene.png')
|
||
bpy.ops.wm.save_as_mainfile(filepath=str(output_dir / 'scene.blend'))
|
||
bpy.ops.render.render(write_still=True)
|
||
```
|
||
|
||
Use roughly 32–48 samples for previews and 64–96 for a polished still with denoising as starting points. Do not assume GPU acceleration is configured. Saving before rendering preserves the scene if rendering fails.
|
||
|
||
## Execution and diagnosis
|
||
|
||
- The first sandboxed launch in this project exited with code 139 before running the script and wrote `blender.crash.txt` in the system temporary directory. A retry through the approved unsandboxed execution mechanism succeeded. Treat this as an observed environment issue, not proof that every crash needs escalation. On a similar startup failure, inspect the output and request the applicable execution permission; if a permitted retry still fails, investigate rather than repeatedly escalating.
|
||
- A USD `Arch_ValidateAssumptions` warning accompanied that startup failure; it did not establish the root cause.
|
||
- `Material.use_nodes` and `World.use_nodes` emitted deprecation warnings in 5.1.2 but worked. They are expected to change in Blender 6; verify the installed API when upgrading.
|
||
- Background rendering can produce little output for tens of seconds. If execution returns a session ID, poll that session until completion instead of launching duplicate renders. Confirm the exit status and saved files.
|
||
|
||
## Modeling and visual lessons
|
||
|
||
- Cylinders aligned with `direction.to_track_quat('Z', 'Y')`, beveled curves, UV spheres, and custom meshes worked well for stylized scene construction. Smooth shading does not fix a faceted silhouette: give focal shapes enough geometry. Cap exposed curve ends or cover them with modeled joints.
|
||
- Inspect the rendered image after meaningful changes. Check the silhouette, grip and pedal contacts, floating parts, frame cropping, shadows, and whether background details are actually visible. A successfully saved render is not visual QA.
|
||
- Avoid overlapping coplanar surfaces. The retained studio floor hid the new beach and ocean; coincident surfaces produced black bands. Remove obsolete geometry and deliberately separate surface heights. For a box, calculate the top as center Z plus half its height.
|
||
- Frame an orthographic camera deliberately: an infinite ground plane fills the background without a natural horizon. A distant sky backdrop perpendicular to the horizontal viewing direction can provide a level horizon. Check projected positions of the sun, clouds, and distant props; adding them does not guarantee they appear in frame.
|
||
- For a substantial quality improvement, prioritize coherent composition, character anatomy, materials, and light over adding more objects. Preview warm key light, cooler fill, and rim light; avoid washed-out colors and unlit distant props. Keep decorative details from obscuring the subject.
|
||
|
||
Deliver the inspected render inline and link the editable `.blend` using absolute paths. Preserve earlier versions when making major revisions unless the user requests replacement.
|