OpticalModeler 2.0 — from schematics and photographs to editable, evidence-gated optical systems.
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.
| 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. |
| 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.
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.
Version 2.0 adds explicit workflows for photograph reconstruction, fixed-endpoint layout corrections, selected instrument outputs/shutters, and separate presentation copies. It distinguishes installed, candidate and proposed parts; audits user intent as well as geometry; preserves accepted files; and records actual image producers instead of relabeling old renders.
Start with six use cases and real public input/output, then read the full English dialogues or 中文交互案例. Each reaches a concrete handoff: editable review package, final presentation images, or a reproducible blocker/checkpoint. The dialogues show relevant clarification, user rejection and correction, scoped checks and final results.
| Your request | Guide | Delivery boundary |
|---|---|---|
| Reconstruct my photographs on an accepted baseline | Photo reconstruction and revisions | Complete private review model with installed/reference/unknown identity separated. |
| Move only this branch; keep the upper route fixed | Constraint and intent checks | Whole-family movement, fixed endpoints, actual footprint and affected-neighbor evidence. |
| Make the enclosure darker; keep the model/cameras | Presentation and delivery | Separate saved copy, preserved scientific geometry and fresh affected views. |
| Publish the workflow without exposing the laboratory | Publication privacy | Functional aliases, curated files, private identifier scan, image/container review. |
Laboratory-derived examples omit important instrument SKUs, exact setup coordinates/operating parameters, private photographs/models and identity maps. They are edited teaching reconstructions, not raw transcripts. Already public independent examples retain their source-backed catalog references. This release updates guidance and ledger software; it performs no new geometry run or blind forward test and changes no historical physical verdict. See CHANGELOG.
Use $thorlabs-blender-optical-path to reconstruct these annotated photographs
on the accepted baseline. Preserve its original files and fixed upper endpoints.
Keep this optics-only. Deliver one editable review model, readable final views,
and a measurement checklist. Separate installed, candidate and proposed parts.
Keep laboratory identities, photos and the full scene private.
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.
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.
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.
With a compatible Agent Skills installer:
npx skills add k-telux/OpticalModelerOr copy skills/thorlabs-blender-optical-path into your agent's skills directory.
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:
- map schematic nodes to experimental roles, real assets, ports, and support paths;
- freeze exact directed topology and official-CAD provenance;
- replay public lock scripts to the same normalized semantic parameters;
- solve optical centers, surfaces, splitter planes, and branch continuity;
- assemble hardware post-first from verified table holes;
- prove one representative instance before propagation;
- reopen the saved scene and run mesh, ray, BVH, and load-path checks;
- derive public claims from evidence and scan binary/container metadata before packaging.
python scripts/validate_repository.py
python scripts/validate_repository.py --private-terms-file /private/release-inputs/sensitive-terms.txt
The optional UTF-8 policy file remains outside the repository. Its identifier scan covers candidate filenames and uncompressed UTF-8/UTF-16 bytes; it is not OCR or archive inspection. Inspect newly public visuals and container content separately. Existing unit checks and manifest/PNG validation run through the same validator; no new package dependency is needed.
- 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.