OpticalModeler is an evidence-first Agent Skill for reconstructing laboratory optical paths in Blender. It treats optical topology, real apertures, manufacturer CAD, fasteners, load paths, fiber routing, and artifact lineage as hard acceptance gates—not decorative details.

Independent community project. Not affiliated with or endorsed by Thorlabs, Inc. Product names identify compatible hardware only. A rendered CAD assembly is not a mechanical, spectral, laser-safety, or experimental certification.

Why OpticalModeler

Physical assembly	Optical truth	Fail-closed evidence
Post-first placement, real table holes, fasteners, load paths, and supported hardware.	Centered apertures, splitter planes, branch continuity, internal fine beams, and fiber bend constraints.	Reopened-scene audits, ray/BVH checks, hashes, manifests, annotated renders, and explicit PASS / BLOCKED / UNVERIFIED states.

2D input → verified 3D output

Original schematic	Annotated 3D reconstruction

The sanitized G1/G2 case study includes the original 2D input, editorial 3D renders, and a machine-readable acceptance record. Vendor STEP/CAD files and the large laboratory .blend are intentionally excluded.

Unified whole-system workflow

The primary workflow is now one ordered run with one run ID, one revision, one writer, one generator lineage, one Blender-scene lineage, and one append-only evidence ledger. Source locking, topology, CAD provenance, representative smoke, full-scene propagation, saved-scene reopen, optomechanical audit, rendering, and sanitization are gates in that same run—not independently authored modules that can be stitched together later.

Start with the end-to-end workflow contract, the single-run N04 deterministic replay, and its fresh whole-system runbook. The static replay intentionally stops at UNVERIFIED because the repository excludes vendor CAD and the saved representative .blend; downstream gates remain pending instead of inheriting a partial PASS. A fresh private revision can execute the included fetch, build, reopen, audit, and sanitization scripts end to end.

v1.2.0: new designs, clear scope, and honest previews

Ask for a new measurement path at the quality of an existing example, and the Skill now explicitly starts from a new topology and empty scene. It distinguishes reusable component assets from a complete prior apparatus and respects optics-only scope, including optical detectors and supports while excluding circuit/data visualization.

The fresh-design guide covers component fidelity, visible branches, measured ports, preview/final rendering, runtime isolation, and a practical completion cutoff. The MZI preview limitation case explains why expected-family ray hits, constant zero endpoint errors, whole-frame image scores, and 2048-wide previews cannot establish full physical or 4K acceptance.

This release updates the Skill and its evidence contract; it does not certify a new optical instrument. The historical examples below retain their original verdicts. See the changelog for the complete update.

Use $thorlabs-blender-optical-path to design a new optics-only measurement
system. Use the G1/G2 example only as a modeling and rendering quality reference.
Derive a new topology, build from an empty scene with provenance-bound component
assets, verify the physical paths, and deliver the declared final-resolution views.

v1.1.0 multi-run qualification

The v1.1.0 qualification package compares 64-, 96-, and 128-node N04 scale runs with an independent 40-node stateful interferometer test. The verdict is deliberately mixed: PARTIAL_SCOPED, strict-BVH BLOCKED, scale-only PASS_SCOPED, and topology UNVERIFIED. No track supplies a whole-system or physical-release PASS.

The repeated tests hardened atomic source acquisition, live-versus-pinned CAD identity, exact cache aliases, canonical ledger replay, execution-versus-claim status, representative spacing/load evidence, strict collision classification, stateful topology expansion, and public-package sanitization. See CHANGELOG.md for the versioned changes.

Public-only forward tests

Four isolated tests started from the published v1.0.0 tag and used no private Optical Path guidance. They cover a 32-node light-sheet path, a 40-node multi-state interferometer, an OCT representative smoke, and a Thorlabs CAD conversion benchmark.

Track	Accepted verdict	Reproduced failure
Light-sheet / N04	Propagation PASS, model PARTIAL_SCOPED, release BLOCKED	Public lock replay drifted from the saved scene until semantic replay and explicit overrides were added.
Interferometer	PARTIAL_SCOPED, release BLOCKED	README/GATE duplicated stale ray and port counts instead of deriving them from reopen evidence.
OCT	UNVERIFIED, propagation blocked	Package integrity passed while first-hit and load-path evidence remained incomplete.
CAD conversion	BLOCKED	PNG metadata leaked local paths; after sanitization, a separate CAD meshing blocker correctly remained.

The forward-test matrix remains a historical defect-discovery record. Its four packages are not inputs that may be combined into one whole-system result.

Install

With a compatible Agent Skills installer:

npx skills add k-telux/OpticalModeler

Or copy skills/thorlabs-blender-optical-path into your agent's skills directory.

Quick start

Send message below to your agent:

Use $thorlabs-blender-optical-path to reconstruct this 2D schematic in Blender.

Audit this optical table for real post/load paths, centered apertures, beam clearance, fiber bend radius, and stale evidence.

The skill guides the agent to:

1. map schematic nodes to experimental roles, real assets, ports, and support paths;
2. freeze exact directed topology and official-CAD provenance;
3. replay public lock scripts to the same normalized semantic parameters;
4. solve optical centers, surfaces, splitter planes, and branch continuity;
5. assemble hardware post-first from verified table holes;
6. prove one representative instance before propagation;
7. reopen the saved scene and run mesh, ray, BVH, and load-path checks;
8. derive public claims from evidence and scan binary/container metadata before packaging.

Validation and limits

• Manufacturer CAD is an asset source, never proof of correct assembly.
• Free-space rays, guided fiber, and electrical cables remain semantically distinct.
• Whole-project success requires an active-rule compliance matrix; scoped evidence stays PARTIAL/SCOPED.
• The repository excludes third-party CAD, private paths, oversized Blend files, and unsupported real-world performance claims.
• Public scripts must replay the published semantic locks; prose counts must match saved-reopen evidence.
• Every release is checked for skill metadata, links, file size, ASCII/UTF-16 privacy leaks, forbidden CAD binaries, PNG metadata/CRC/decompression, manifest hashes, and acceptance-state consistency.

See CHANGELOG.md for releases, CONTRIBUTING.md for rule proposals and case-study submissions, THIRD_PARTY_NOTICES.md for retained literature licensing, and SECURITY.md for responsible disclosure.

Maintained by telux. Released under the MIT License.