Blender Optics Simulator

An optical bench an AI agent can build, inspect, align, and render — over MCP.

"See a need, fill a need." — Bigweld, Robots (2005)

60-second tour — Lay out lasers, mirrors, beamsplitters, lenses, waveplates, gratings and detectors in Blender; a live beam engine traces them (ray + Gaussian-q ABCD + Jones/Stokes polarization + wave-optics overlays), all physics-verified against textbook answers in CI. Everything mounts on real opto-mechanics and renders in Cycles. The whole optical state is exposed over a localhost MCP bridge, so an AI agent reads ground-truth geometry and beam data and drives the bench — aligning, closing an AO loop, nulling fringes. Install: drag the one-click link from the releases page into Blender 4.2+ (it also subscribes you to updates — see Install & stay updated).

Blender becomes a physics-checked optical bench: lasers, mirrors, beamsplitters, lenses, waveplates, polarizers, gratings, deformable mirrors, detectors — laid out in 3-D, traced by a live beam engine, mounted on real opto-mechanics, and rendered in Cycles. The twist: the entire optical state is exposed as JSON over a localhost MCP bridge, so an AI agent (e.g. Claude) doesn't guess geometry — it reads every element's pose, port normals, beam path, mount limits, and wavefront error as ground truth, then drives the bench toward design intent and watches the beam update live.

This is the one place Blender × optics × MCP/AI-agents actually overlap. Most Blender-MCP work is geometry and animation. This is a physics-grounded digital twin of a real optical table that an agent can see and close the loop on.

A real bench, traced live. Every mount, post, base and beam above is placed and computed by the add-on — then rendered in Cycles. Build it by hand in the UI, from a script, or let an AI agent drive it over MCP.

Alignment, solved. A kinematic mirror is knocked 2° out of alignment, throwing the beam well off the sensor centre — then one optics_api.align_element() call collapses the pointing residual (7.02 → 0.0008 mrad) and re-centres it. See examples/agent_align.py, which reproduces those numbers headlessly in one command.

The core loop

An agent doesn't fly blind — it has the optical truth and iterates against it:

get_state()  →  read every element's world pose, port positions+normals, mount DOFs,
                 traced beam path, detector readings, wavefront error  (full JSON)
   ↓ decide
action()     →  align a mirror · scan OPD · place a part on a grid hole · close the AO loop
   ↓
beam re-traces live  →  next iteration

get_state() returns the whole bench as JSON — elements, sources, detectors, beam path, bench grid, cages/tubes/rails, and mechanical-limit warnings — so the agent always knows where things are and where the light goes. 30 functions are exposed over MCP; the bridge whitelists only the curated optics_api facade.

Drive it with an AI agent (MCP)

1. In Blender: Optics ▸ Simulation ▸ Start MCP Bridge (exposes every public optics_api function on 127.0.0.1:9765).
2. Run the bridge server in mcp/ and wire it into your MCP client.

Then the agent can READ the bench, WRITE changes, and COMPOSE subsystems:

import optics_api

# COMPOSE — bootstrap a canonical bench in one call
optics_api.build_example("michelson")        # full setup + live beam

# READ — the agent's numeric eyes: ground truth, not guesses
state = optics_api.get_state()               # poses, port normals, beam path, mounts, detectors
optics_api.inspect_beam("MI_BS")             # power, w, R(z), M², divergence, polarization, coherence here
optics_api.inspect_element("MI_BS")          # what this optic DOES + its live in/out by kind, throughput
optics_api.beam_profile("MI_D")              # Gaussian w(z), waist, aperture clipping
optics_api.detect_phenomena()                # flags interference / off-axis-hologram conditions the trace meets
optics_api.propose_corrections()             # advisory fixes you JUDGE (refuse / partial / accept)

# WRITE — act, then the beam re-traces
optics_api.align_all()                       # auto-tune every kinematic knob toward its target
optics_api.set_param("MI_BS", "split_ratio", 0.5)
optics_api.place_on_grid("MI_M_fixed", 6, 2) # slide a part to a real breadboard hole
optics_api.scan(kind="STAGE", lo=0, hi=2e-3, steps=120, element="MI_M_stage")  # interferogram PNG+CSV

# Adaptive optics: sense the wavefront, then close the loop
optics_api.build_example("adaptive_optics")
optics_api.ao_measure("AO_WFS")                                 # {zernike:[...], rms: 0.559} (incl. beam defocus)
optics_api.pyramid_wfs("AO_WFS")                                # same wavefront read as a SLOPE sensor
optics_api.ao_close_loop("AO_WFS", "AO_DM", gain=0.5, iters=15) # rms 0.559 → ~0

# RENDER — photorealistic Cycles, or a turntable movie
optics_api.bake_beams()
optics_api.render(preset="final", camera="HERO", filepath="/tmp/michelson.png")

The full surface (each also an MCP tool): capabilities, get_state, diagnose, propose_corrections, detect_phenomena, inspect_beam, inspect_element, beam_profile, sensor_capture, ao_measure, get_wavefront, pyramid_wfs, zonal_render, coupling_efficiency, check_mechanics, build_example, trace_beam, path_statistics, tag_element, add_component, swap_part, place_relative, set_mount, set_param, align_element, align_all, auto_align, tilt_null, design_telescope, design_4f, mode_match, scan, render, render_sequence, bake_beams, clear_beams, export_svg, dress_bench, set_grid, place_on_grid, make_cage, make_tube, make_rail, place_on_rail, ao_command, ao_close_loop. Call capabilities() first — it returns a self-describing manifest (read mcp/AGENT_GUIDE.md for the conventions and the refuse / partial / accept judgement model).

Five repeatable /optics-* skills ship in .claude/skills/ (build · align · inspect · correct · sensor-render) — model-invoked workflows that sequence these tools and carry the disciplines (inspect-first, byte-identical, advisory-corrections-you-judge).

For headless pipelines, optics_api is importable directly inside Blender (blender --background --python your_script.py).

Detector path length, shutters, and custom meshes

path_statistics() reports every source-to-detector arrival separately. It reconstructs the parent-indexed route and returns both its geometric length and the tracer's accumulated phase OPL:

stats = optics_api.path_statistics()                 # all detector terminals
one = optics_api.path_statistics("MyDetector")      # one detector

The result deliberately says group_delay_available: false. The current tracer carries phase-index OPL; it does not model group index, group delay, or GDD, so the number must not be presented as an ultrafast time-of-flight result. In the UI the same phase OPL/geometric range appears under Inspect → Optical Report.

A binary shutter is available from the component library under the key SHUTTER:

created = optics_api.add_component("SHUTTER", location=(0, 0, 0))
optics_api.set_param(created["name"], "shutter_open", False)  # block
optics_api.set_param(created["name"], "shutter_open", True)   # transmit