# bim-blender

> Blender driver for bim-cli. Converts between 3D formats headlessly (FBX, glTF/GLB, OBJ, USD, BLEND) and drives a live Blender session over TCP. IFC read/write requires the free Bonsai add-on.

## Two modes

**Headless (static):** `bim blender convert` spawns `blender --background`, converts, exits. No Blender window. Use for batch pipelines.

**Bridge (live):** `bim blender launch` opens Blender with its UI. A background Python server binds a random local port. `bim blender exec` sends Python over TCP — changes appear in the open Blender window in real time. This is the co-editing mode.

## Requirements

- Windows 10/11
- Managed Blender installed via `bim blender install` (downloads Blender 4.5.10 LTS, ~395 MB)
- IFC operations: also run `bim blender install --component bonsai` (~118 MB)
- No admin required. No system-wide Blender install required.

## Setup sequence

```
bim blender doctor           # check what's missing
bim blender install          # install managed Blender 4.5.10 LTS
bim blender install --component bonsai   # add IFC support (optional)
bim blender status           # confirm versions
```

## Verb reference

### Install / upgrade
- `bim blender install` — download and install managed Blender 4.5.10 LTS to `%LOCALAPPDATA%\bim-cli\blender\`. Idempotent.
- `bim blender install --component bonsai` — add Bonsai IFC add-on
- `bim blender install --component all` — Blender + Bonsai in one step
- `bim blender install --dry-run` — print what would be downloaded without downloading
- `bim blender upgrade` — upgrade to latest pinned versions
- `bim blender upgrade --component blender|bonsai|all`

### Health / status
- `bim blender doctor` — structured health check; each failed check includes a `fix` field with the exact command to run
- `bim blender status` — installed versions, paths, whether Bonsai is present

### Headless conversion
- `bim blender convert --in FILE --out FILE` — convert between formats; format auto-detected from file extension
- `bim blender convert --dry-run` — print what would happen without running Blender

**Supported format pairs (no Bonsai):** FBX↔glTF/GLB, FBX↔OBJ, FBX↔USD, FBX↔BLEND, glTF/GLB↔OBJ, glTF/GLB↔USD, OBJ↔USD, and all to/from BLEND.

**IFC pairs (Bonsai required):** IFC→FBX, IFC→glTF/GLB, IFC→OBJ, IFC→USD, IFC→BLEND, BLEND→IFC.

### Bridge (live session)
- `bim blender instances` — list live Blender instances: pid, port, open file. Call before exec when multiple instances may be running.
- `bim blender launch [--file FILE] [--timeout 30]` — open managed Blender; waits up to `timeout` seconds for bridge to bind. Returns `{pid, port}`.
- `bim blender exec --code "PYTHON"` — run a Python snippet against the active Blender instance
- `bim blender exec --file script.py` — run a .py file
- `bim blender exec --pid PID` — target a specific instance (required when >1 instance running)
- `bim blender exec --timeout 30` — seconds before timeout error (Blender stays alive after timeout)
- `bim blender kill --pid PID` — terminate a specific instance
- `bim blender kill --all` — terminate all managed Blender instances

## exec: available globals

Every `bim blender exec` snippet has access to:

| Variable | Type | Always |
|----------|------|--------|
| `bpy` | Blender Python API | yes |
| `bpy.context` | active context | yes |
| `bpy.data` | data blocks | yes |
| `bonsai` | Bonsai module | only if Bonsai installed |
| `tool` | `bonsai.tool` helpers | only if Bonsai installed |
| `ifcopenshell` | IfcOpenShell | only if Bonsai installed |

Return a value by assigning to `_`. Non-JSON-serializable objects fall back to `repr()`.

## exec: key patterns

```python
# Add geometry
bpy.ops.mesh.primitive_cube_add(location=(2, 0, 0))

# Read back user edits
_ = bpy.context.active_object.location[:]

# Redirect the viewport
bpy.ops.view3d.view_selected()

# IFC: load a project (requires Bonsai)
bpy.ops.bim.load_project(filepath=r"C:\model.ifc")

# IFC: query elements
import ifcopenshell
f = ifcopenshell.open(r"C:\model.ifc")
_ = len(f.by_type("IfcWall"))
```

## Error kinds

| kind | meaning |
|------|---------|
| `scope_required` | Blender not installed (run `bim blender install`) or Bonsai not installed (run `bim blender install --component bonsai`) |
| `not-found` | input file does not exist |
| `bad-args` | unsupported format pair or missing required flag |
| `connection` | could not connect to Blender bridge — check `bim blender instances` |
| `timeout` | Blender did not respond within the timeout; the Blender window is still open |
| `runtime` | Python error in exec snippet — check `error.data.hint` for the traceback |

## Doctor check fields

Each check in `bim blender doctor` output has: `name`, `ok`, `detail`, `fix` (command to run if not ok), `optional`.

Required checks: `blender-managed`, `bridge-addon`, `version-compat`.
Optional checks: `blender-system` (informational), `bonsai-managed` (only needed for IFC).