optiforge

<div align="center"> <img src="assets/banner.svg" alt="OptiForge" width="100%"> <img src="assets/intro.gif" alt="OptiForge in 20 seconds: a spec is audited, a topology is reasoned, quality gates fire, deliverables are produced" width="100%">

OptiForge — an AI-native optical engineering platform over the Zemax ZOS-API: from a one-line spec to a diffraction-limited lens, a tolerance budget, a STEP model and manufacturing drawings.

OptiForge · 光匠 —— 基于 Zemax ZOS-API 的 AI 原生光学工程平台：从一句需求，到衍射极限镜头、公差预算、STEP 三维模型与加工图纸。

English · 中文说明

</div>

---

本地可视化工作台

自然语言对话在外部 Agent 中进行；工作台显示当前服务模型的表面属性、二维轮廓和 Zemax 原生实光线。支持文件导入、真实视场与波长选择、滚轮缩放、左键拖动和一键复位，以及深浅主题。

在 frontend 目录执行 npm ci、npm run build，回到项目根目录运行 python -B workbench.py --model <已有文件路径>，然后打开 http://127.0.0.1:8765/。安装、Agent 桥接和支持范围见 工作台说明。

原生追迹需要 OpticStudio API 许可、有效模型归属及当前项目已确认的提案。导入文件创建独立工作副本；当前服务不自动跟随磁盘原件或其他 Zemax 窗口。像质分析面板尚未接入。

---

<a name="english"></a>

🌐 English

What is it?

OptiForge is an AI-native optical engineering platform. It is not a thin MCP wrapper around OpticStudio: the optics is in the platform. OptiForge drives Ansys Zemax OpticStudio through the ZOS-API (via pythonnet) and layers on top of it everything the optical software itself will not tell you — a mandatory design SOP with a human approval gate, fabrication rules encoded as executable gates, an aberration and first-order reasoning layer, and a tolerance / CAD / optomechanical delivery path.

That whole platform is then exposed over the Model Context Protocol, so any MCP-compliant agent — Claude, Gemini, Antigravity, Codex, or your own client — can drive a real design end to end.

Three things make it a platform rather than a tool collection:

1. It refuses to guess. A spec-completeness audit (zemax_audit_requirements) halts the agent and asks for the missing parameters, with industry defaults attached, before a single surface is created.
2. It encodes manufacturing reality. Centering feasibility (Karow), edge thickness at the clear aperture, test-plate steepness, hemispheric and near-flat bans, internal air-gap limits — checked outside the software, because OpticStudio will cheerfully save a design that cannot be made.
3. It learns from failure. Every "builds but doesn't work" incident becomes a registered gate in core/quality_gates.py plus an offline regression. Learn once, enforce forever.

The agent can take a design through the whole loop:

spec audit → starting structure → merit function → DLS / Hammer optimization → spot / MTF / wavefront analysis → manufacturing audit → STEP / DXF deliverables

and it gets structured JSON feedback at every step.

Highlights

| | | | :--- | :--- | | 🧭 Guided 5-stage design SOP | Spec audit with recommended defaults, literature and patent search, first-order and Seidel reasoning, a design proposal, and a user approval gate before any simulation. | | ⚙️ Robust optimization | DLS and Hammer, with a pre-flight ray-feasibility check (TIR or missed rays) and a stagnation guard that stops early when ΔMF/MF < 0.5 %. | | 🎯 Diffraction-aware analysis | Spot, FFT MTF, ray fan, wavefront or Strehl, field curvature and distortion. Spot-diagram PNGs are traced with Batch Ray Trace and include the Airy circle. | | 🏭 Manufacturing rules built in | CT and ET limits, air-gap limits (MXCA ≤ 12 mm), test-plate steepness, AOI (RAID), and a Narcissus / ghost back-reflection audit. | | 📐 CAD & drawings | Headless STEP / IGES / SAT / STL export. Editable DXF element and assembly drawings (ISO 10110 / GB/T 13323). JSON bridge to a SolidWorks MCP. | | 🗂️ Project workspaces | Every design gets its own folder, output/<project>/{cad,drawings,optomech,reports}. |

---

Showcases

⭐ Showcase 1: Diffraction-Limited F/8 Achromatic Doublet (every ray inside the Airy disk)

Using the achromat_doublet template as a starting point, the agent screened glass pairs, then ran repeated DLS → Hammer → DLS rounds until it reached a cemented N-BK7 / N-SF2 doublet. Every ray from every field and wavelength lands inside the Airy disk.

| Field | RMS radius | GEO radius | GEO / Airy radius (5.736 µm) | Strehl | Wavefront RMS | | :---: | :---: | :---: | :---: | :---: | :---: | | 0° | 1.575 µm | 3.050 µm | 53 % | 0.991 | 0.015 λ | | 0.7° | 1.264 µm | 2.352 µm | 41 % | 0.957 | 0.033 λ | | 1.0° | 1.570 µm | 3.442 µm | 60 % | 0.894 | 0.053 λ |

• First order: EFL 100.000 mm, F/8.002, TOTR 108.77 mm, F/d/C wavelengths (0.486 / 0.588 / 0.656 µm).
• Prescription: R1 62.844 / 8.000 N-BK7 → R2 −39.605 / 7.334 N-SF2 → R3 −122.520 / BFD 93.432 mm.
• MTF @ 50 lp/mm: 0.66 to 0.70 at all fields. Distortion is 0.002 %. The manufacturing rule audit is PASS with 0 errors and 0 warnings.

Showcase 2: High-NA Water-Immersion Objective (Diffraction-Limited at NA 0.80)

For reflectance confocal microscopy (RCM / skin CT), an AI agent designed and optimized a high-NA water-immersion objective.

• Aperture & working distance: $NA = 0.800$ in water ($n=1.32882$), $WD = 3.00,\text{mm}$.
• Compact packaging: $TOTR = 26.00,\text{mm}$, max element diameter $12.33,\text{mm}$. The front tip is only $2.88,\text{mm}$ in diameter, for tissue contact.

| Optical Parameter | Target Requirement | Autonomous Optimization Result | Status | | :--- | :--- | :--- | :---: | | Focal Length ($EFL$) | $\approx 4.50,\text{mm}$ (Pairs with $180,\text{mm}$ tube lens for $40\times$) | $4.5000,\text{mm}$ (Water equivalent $5.9797,\text{mm}$) | Achieved | | Working Distance ($WD$) | $\approx 3.00,\text{mm}$ in water (no cover glass) | $3.0000,\text{mm}$ in pure water | Achieved | | Numerical Aperture ($NA$)| $\ge 0.80$ in water | $0.800$ ($EPD = 7.20,\text{mm}$, half-angle $37.02^\circ$) | Achieved | | Wavelength Band | Core $830,\text{nm}$ ($810 - 850,\text{nm}$ band) | $810,\text{nm} - 850,\text{nm}$ fully corrected | Achieved | | Field of View ($FOV$) | $\varnothing 0.66,\text{mm}$ ($y = \pm 0.33,\text{mm}$) | $\varnothing 0.66,\text{mm}$ (Semi-field angle $4.19^\circ$) | Achieved | | Strehl Ratio ($S$) | Diffraction-limited ($S \ge 0.80$) | $S \ge 0.953$ across all fields & wavelengths | Surpassed | | Narcissus Back-Reflection| Zero pinhole ghost focus | All $|i| \ge 4.58^\circ$, pinhole rejection $> 99.999%$ | Achieved |

<details> <summary><b>Aberration charts: MTF, spot vs. Airy disk, Narcissus audit</b></summary>

FFT MTF: contrast stays above 0.86 at $117.7,\text{lp/mm}$ for all fields.

Spot diagram vs. Airy disk: every field point falls near or inside the Airy radius in water ($r_{\text{Airy}} = 0.8422,\mu\text{m}$).

Narcissus / ghost audit: all 15 surfaces avoid normal-incidence retroreflection ($|i| \ge 4.58^\circ$). At the pinhole plane the ghost disks are defocused to between 28 and 238 mm, which gives more than 85 dB of stray-light isolation.

</details>

Showcase 3: High-NA Water Immersion Objective ($40\times$, $\text{NA}=0.90$ Diffraction-Limited, Yutong Cup Replication)

Replicating the 13th National Undergraduate Optoelectronic Design Competition ("Yutong Cup" Track 1) water immersion microscope objective. The AI agent completed the entire closed-loop design autonomously via MCP tools—from ORS specification audit, baseline patent retrieval, and first-order paraxial reasoning to progressive DLS optimization.

The agent automatically diagnosed and resolved three major engineering challenges:

1. NIR Water Dispersion Compatibility: Overcame OpticStudio's built-in water catalog wavelength limit by synthesizing an extended NIR water dispersion model and generating a self-contained WATER_NIR.AGF catalog for uninterrupted ray tracing from $785$ to $850,\text{nm}$.
2. Lens Edge Interference & Sag Collision Elimination: Detected severe edge collision between steep meniscus elements (Lens 2 and Lens 3). Embedded ETGT and MNEA operand barriers in the merit function, expanding the edge clearance from negative collision to $+0.80,\text{mm}$, leaving ample room for spacer flat lands.
3. Ray Overflow & Semi-Diameter Reconstitution: Recomputed clear apertures across all 21 surfaces to prevent beam spillover, ensuring $100%$ transmission across all field angles ($0^\circ \sim 4.26^\circ$) without clipping or vignetting.

1. System Specifications & Compliance Matrix

| Optical / Mechanical Parameter | Competition Target Specification | Agent Optimized Value | Compliance Status | | :--- | :--- | :--- | :---: | | Numerical Aperture ($NA$) | $\ge 0.90$ (pure water immersion, $n=1.33$) | $0.900$ ($EPD = 8.55,\text{mm}$, half-angle $42.54^\circ$) | 100% Achieved | | Effective Focal Length ($EFL$)| Nominal $4.75,\text{mm}$ ($40\times$ with tube lens) | $4.7500,\text{mm}$ (Water-equivalent $6.3323,\text{mm}$) | 100% Achieved | | Working Distance ($WD$) | $0.5,\text{mm} \le d \le 1.0,\text{mm}$ (nominal $0.75 \sim 1.0,\text{mm}$) | $1.0000,\text{mm}$ (Pure water immersion layer) | 100% Achieved | | Total Track Length ($TOTR$) | $\le 50.8,\text{mm}$ (2-inch mechanical envelope) | $48.921,\text{mm}$ (Surface 1 to focal image plane) | 100% Achieved | | Max Mechanical Clear Aperture| $\le 25.4,\text{mm}$ (1-inch barrel diameter) | Max lens OD $16.4,\text{mm}$ (Barrel OD $\le 20.0,\text{mm}$) | 100% Achieved | | Wavelength Band | $785,\text{nm}, 810,\text{nm}, 850,\text{nm}$ (NIR fluorescence/confocal) | $785 - 850,\text{nm}$ full-band apochromatic | 100% Achieved | | Cover Glass Thickness & Glass| $0.170,\text{mm}$ thickness, Schott D263 / CDGM H-K9L | $0.170,\text{mm}$ H-K9L ($n=1.511$) spherical aberration balanced | 100% Achieved | | Specimen Scan Field ($FOV$) | $0.5,\text{mm} \times 0.5,\text{mm}$ (diagonal $\varnothing 0.707,\text{mm}$) | $0.5,\text{mm} \times 0.5,\text{mm}$ (half-angle $4.26^\circ$) | 100% Achieved | | Telecentricity (CRA) | Object-space chief ray angle $\le \pm 2.0^\circ$ | $< 0.15^\circ$ (Double-telecentric behavior) | Surpassed | | Max Distortion | Absolute value $\le 5.0%$ | $-0.4735%$ (Ultra-low grid distortion) | 10x Margin | | Field Curvature Sag | Sagittal / tangential $\le 25.0,\mu\text{m}$ | Tangential $1.7,\mu\text{m}$ / Sagittal $3.5,\mu\text{m}$ | 7x Margin | | Astigmatism | ASTI $\le 10.0,\mu\text{m}$ | $1.84,\mu\text{m}$ | Surpassed | | Axial Chromatic Aberration | $\le 3.0,\mu\text{m}$ | $1.98,\mu\text{m}$ ($785 \sim 850,\text{nm}$) | 100% Achieved | | Lateral Chromatic Aberration| $\le 1.5,\mu\text{m}$ | $1.28,\mu\text{m}$ (at full field) | 100% Achieved | | Optical Glass Catalog | Commercial preferred glasses (CDG