animation/docs/blender-bridge.md

Blender Bridge (TinqsBlenderBridge)

Live control of a running, interactive Blender session from the terminal — third sibling of the iClone (docs/iclone-bridge.md) and MD (docs/md-bridge.md) bridges: a socket server inside the app + a thin JSON-over-TCP client, same wire protocol and result convention.

Distinct from the headless pipeline scripts (tools/cc_retarget.py, tools/tailor/*), which spawn blender --background and exit. Those never touch the open GUI. This bridge is for driving the window Jeremy is looking at — inspecting a selection, nudging a mesh, checking a drape.

The good news vs. MD: Blender has bpy.app.timers, so the server polls a non-blocking socket from a main-thread timer. The UI stays fully interactive — no frozen-window session like MD. The UI only stalls for the duration of a single exec.

	iClone bridge	MD bridge	Blender bridge
Server source	tools/iclone_bridge/TinqsBridge/main.py	tools/md_bridge/TinqsMDBridge.py	tools/blender_bridge/tinqs_blender_bridge.py
Client	tools/iclone_bridge.py	tools/md_bridge.py	tools/blender_bridge.py
Port	18800	18900	19000 (TINQS_BLENDER_BRIDGE_PORT overrides)
Install	ps1 → OpenPlugin, auto-loads	manual register, click = session	ps1 → scripts/startup/, auto-starts
Executor	QTimer on Qt main thread	main-thread loop, UI frozen	bpy.app.timers, UI stays live
Session end	app exit	--stop / 4 h idle	--stop, or app exit (no idle timeout)
Embedded Python	3.8	3.11.8	3.13.9 (Blender 5.1.2)
Log	%TEMP%\tinqs_iclone_bridge.log	%TEMP%\tinqs_md_bridge.log	%TEMP%\tinqs_blender_bridge.log

Install (one-time)

powershell -File tools\install_blender_bridge.ps1

Copies the server into every %APPDATA%\Blender Foundation\Blender\<ver>\scripts\startup\. Blender imports startup modules at launch and calls their register(), so the bridge auto-starts on port 19000 from the next launch onward — zero clicks, forever.

To start it in an ALREADY-OPEN Blender (a session that predates the install — the common case, and one that matters when the window has unsaved work you don't want to lose to a restart):

Scripting workspace → Open → tools\blender_bridge\tinqs_blender_bridge.py → Run Script (▶)

Re-running is safe: a singleton on builtins closes the previous socket and retires its timer before rebinding, so no leak and no "port busy" on reload.

Workflow

python tools/blender_bridge.py --ping                 # blender ver, open .blend
python tools/blender_bridge.py --exec "result = [o.name for o in bpy.data.objects]"
python tools/blender_bridge.py --file edit_mesh.py
python tools/blender_bridge.py --timeout 300 --file long_bake.py
python tools/blender_bridge.py --stop                 # server off, Blender lives on

⚠ Use --file, not --exec, for anything with quotes. PowerShell strips inner double quotes from native-command args, so --exec "bpy.data.objects[\"Cube\"]" arrives as bpy.data.objects[Cube] → NameError: name 'Cube' is not defined. Write a scratchpad .py and use --file.

The exec namespace persists across requests within a Blender session and is pre-seeded with bpy, view3d_override(), and a BRIDGE info dict.

The context trap (read this before using bpy.ops)

Timer callbacks run with no window/area in bpy.context, so operators that need one fail with "context is incorrect". Two ways out:

1. Prefer the data API — bpy.data, obj.location, mesh.vertices[i].co, or bmesh for topology. Context-free, and the right tool anyway.

2. Override when an operator truly needs a viewport — the seeded helper returns the kwargs:

   with bpy.context.temp_override(**view3d_override()):
       bpy.ops.object.shade_smooth()
   

Verified (2026-08-04, Blender 5.1.2, Python 3.13.9)

Smoke-tested end to end in a throwaway GUI instance: socket up ~3 s after launch; --ping; direct vertex edit; bmesh subdivide (8 → 26 verts); shade_smooth via temp_override; --stop closed the port cleanly and Blender stayed alive and responsive.

Two bugs found and fixed during that verification

Both are the kind that silently produce "connection refused", so they're worth remembering if the bridge is ever ported or rewritten:

1. bpy.data is restricted during startup registration. Modules in scripts/startup/ register while bpy.data is still a _RestrictData stub — reading bpy.data.filepath there raises AttributeError: '_RestrictData' object has no attribute 'filepath', which aborts register() and the socket never binds, leaving no log file at all. Fix: register() only schedules a one-shot bpy.app.timers callback; the real start runs after boot, when the full API is live. Diagnose this class of failure with blender --background --python-expr "print('x')" — startup tracebacks print to stdout. (Do not pass --factory-startup; it disables user scripts and hides the very thing you're testing.)
2. Unregistering a timer from inside its own callback is an error. The __STOP__ path called stop() from within _poll. Fix: stop(in_timer=True) just closes the socket and lets the callback's return None retire the timer.