---
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.