Skip to content
Back to search

ai-zemax-optical-design

Automated optical design agent skill for Ansys Zemax OpticStudio via ZOS-API — AI-driven requirements parsing, lens modeling, staged optimization, and design reporting.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jerry-del975--ai-zemax-optical-design/badge.svg)](/listings/jerry-del975--ai-zemax-optical-design)

HTML

<a href="/listings/jerry-del975--ai-zemax-optical-design"><img src="/api/listings/jerry-del975--ai-zemax-optical-design/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# Clone the repo
git clone https://github.com/Jerry-del975/ai-zemax-optical-design.git
cd ai-zemax-optical-design

# Install Python dependencies
pip install zospy pythonnet

# Install as Claude Code skill (default)
npm install

# Or install as Codex skill
npm run install:codex

The postinstall script deploys the skill to `~/.claude/skills/ai-zemax-optical-design/` by default. To install for Codex, run `npm run install:codex`; this deploys to `${CODEX_HOME:-~/.codex}/skills/ai-zemax-optical-design/`. Restart the target agent after installation.

Prerequisites

| Component | Requirement | |-----------|-------------| | **OS** | Windows 10/11 | | **OpticStudio** | 2024 R1 (tested), v20.3+ (via ZOSPy) | | **Python** | 3.10+ | | **Python packages** | `zospy>=2.1` (primary connection, multi-version auto-discovery), `pythonnet` (underlying .NET bridge, also used as fallback when ZOSPy is unavailable) | | **Claude Code or Codex** | latest |

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 163 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: ai-zemax-optical-design
  3. description: "Automated optical design agent for Ansys Zemax OpticStudio 2024 R1 through ZOS-API. Use when Codex should automatically turn optical requirements or an existing .zmx/.zos/.zar file into an executable Zemax design loop: parse requirements, create or load a lens model, run baseline analyses, choose variables and constraints, build a merit function, run staged optimization, compare iterations, save final lens files, and produce machine-readable design logs. Supports both prime lenses and multi-configuration zoom systems."
  4. ---
  5. # AI Zemax Optical Design
  6. Use this skill as an automation agent for Zemax optical design. The deliverable is executable ZOS-API automation, not only design advice.
  7. Target environment: Ansys Zemax OpticStudio v20.3+, with ZOSPy handling version discovery and API connection.
  8. ## Operating Contract
  9. Always drive toward these artifacts:
  10. - A normalized requirements JSON with explicit assumptions.
  11. - A seed-design selection record when an official or catalog case can shorten the path to a valid design.
  12. - A runnable ZOS-API Python script or patched scaffold.
  13. - Baseline analysis exports before optimization.
  14. - A staged variable/constraint/merit-function plan.
  15. - Versioned lens saves for accepted stages.
  16. - A final design log with metrics, constraints, changes, and unresolved risks.
  17. Do not stop at conceptual optical-design suggestions unless the user explicitly asks only for theory.
  18. For complex lens families, treat the existing multi-round scoring / optimization scaffold as stable infrastructure and do not rewrite it in this pass.
  19. ## Hard Constraints
  20. - Do not invent a starting architecture when a closer official or catalog seed is available.
  21. - Do not silently switch from a seed-based workflow to a from-scratch workflow.
  22. - Do not broaden the problem scope beyond the user's requested lens class, focal-length range, aperture, and packaging limits.
  23. - Do not treat a weakly similar seed as acceptable unless the mismatch is explicitly logged.
  24. - Do not begin optimization until the seed selection, target normalization, and structural gap list are complete.
  25. - Do not claim a design is suitable for the target if the seed-to-target gap is still unaccounted for.
  26. - Do not fill missing structural details with guesses; record them as assumptions or ask for user confirmation.
  27. - Do not modify the user's requested class of lens to make the problem easier.
  28. - Do not replace the staged optimization logic; preserve the existing feasibility -> image quality -> field balance -> manufacturability flow unless the user explicitly requests a different strategy.
  29. ## Complex-Design Guardrails
  30. - Use a conservative interpretation for difficult lenses: prioritize structural fidelity, convergence stability, and traceable changes over aggressive optimization.
  31. - Treat large family mismatches as blocking until the structural gap is explained and logged.
  32. - Prefer the nearest seed that matches the requested optical family, zoom behavior, aperture regime, and packaging constraints, even if the focal length is imperfect.
  33. - If the best available seed is only a partial match, log the exact mismatch and the adaptation burden before proceeding.
  34. - For difficult designs, do not expand degrees of freedom just to force convergence; increase them only when the current stage and gap analysis justify it.
  35. ## Automation Flow
  36. 1. Parse input.
  37. - Normalize requirements with `references/requirements-schema.md`.
  38. - If an existing `.zmx`, `.zos`, or `.zar` is provided, load it first and extract baseline fields, wavelengths, aperture, configurations, prescription, and merit state.
  39. - Mark assumptions in the log instead of silently inventing constraints, and include seed provenance for any adopted starting design.
  40. - For new designs, search first for the closest official Zemax example or catalog/reference lens with the same structural family, then adapt from that seed instead of starting from a blank system.
  41. - For fast zoom imaging tasks such as an F/1.4, 3x zoom, 18-55 mm-style lens, prefer a structurally similar zoom seed and record the match criteria.
  42. - If no clearly relevant seed is available, stop and report the missing structural basis instead of improvising a new architecture.
  43. - Record the structural gap list before any optimization so the adaptation burden is explicit.
  44. 2. Create or load the Zemax model.
  45. - Prefer loading an existing model when provided.
  46. - For new designs, choose the best seed design first, then adapt it to the requested focal-length range, aperture, field, and packaging limits.
  47. - When no suitable seed exists, create a minimal sequential starting model from first-order requirements, then set surfaces, aperture, fields, wavelengths, stop, image plane, and materials.
  48. - For zoom designs, set multi-configuration data before optimization.
  49. - Keep the seed architecture stable during the initial adaptation stage; do not add, remove, or reorder groups without logging the reason.
  50. 3. Run baseline evaluation.
  51. - Export first-order data, prescription, spot, FFT MTF, wavefront, ray fan, and field curvature/distortion.
  52. - Add domain-specific analyses when relevant.
  53. - Parse raw analysis text into metrics JSON where practical.
  54. 4. Select variables and constraints.
  55. - Choose variables in stages: focus/air gaps, curvatures, thicknesses, glass substitutions, aspheres, multi-configuration solves, tolerance compensators.
  56. - Encode hard feasibility constraints before image quality goals.
  57. - Only vary parameters that preserve the current structural intent unless the user explicitly approves a structural change.
  58. 5. Build and run the merit function.
  59. - Use `references/merit-function.md`.
  60. - Run staged optimization: feasibility, image quality, field balance, manufacturability, optional tolerance readiness.
  61. - Save lens and metrics after each stage.
  62. - If a stage fails, fix the failure at the current stage rather than jumping ahead to a later one.
  63. 6. Compare and accept iterations.
  64. - Compare each candidate against baseline, previous accepted design, and user targets.
  65. - Reject candidates that improve one score by creating hidden geometry, glass, aperture, field, or tolerance failures.
  66. - Preserve seed-design provenance so the final log explains how the result diverged from the starting case.
  67. - Reject any candidate that changes the lens class, zoom behavior, or complexity envelope without explicit user approval.
  68. - Log any new assumption introduced during optimization immediately, with the reason it was needed.
  69. 7. Report outputs.
  70. - Return final lens path, intermediate lens paths, analysis output paths, design log path, performance versus targets, assumptions, and manual checks still needed.
  71. ## Scripts
  72. - `scripts/automated_design_agent.py`: controller for the automated prime-lens design loop.
  73. - `scripts/zoom_lens_design_agent.py`: controller for multi-configuration zoom lens design with MCE setup, variable air gaps, and per-configuration optimization.
  74. - `scripts/zos_design_primitives.py`: ZOS-API connection (pythonnet with ZOSPy fallback), analysis export, save, metrics, and optimization primitives. Supports OpticStudio 2024 R1+.
  75. - `scripts/connection_smoke_test.py`: quick connection test for Standalone or Interactive Extension.
  76. - `scripts/connection_smoke_test.ps1`: PowerShell smoke test that loads the OpticStudio DLLs directly when Python lacks `pythonnet`.
  77. - `scripts/design_single_lens_interactive.ps1`: live Interactive Extension smoke design that creates a simple N-BK7 singlet, saves lens files, and exports analyses.
  78. - `examples/minimal_imaging_requirements.json`: small sample input for smoke-testing the automated design controller.
  79. - `examples/apsc_18-55_f1.4_zoom_requirements.json`: APS-C 18-55mm F/1.4 3× zoom lens requirements with three zoom configurations (wide/mid/tele).
  80. ## References
  81. - `references/requirements-schema.md`: normalized input schema.
  82. - `references/merit-function.md`: staged merit-function and variable-selection rules.
  83. - `references/result-parsing.md`: analysis export, parsing, comparison, and logging rules.
  84. - `references/zos-api-patterns.md`: OpticStudio 2024 R1 ZOS-API reminders.
  85. Load only the reference files needed for the active task.
  86. ## Seed-Design Policy
  87. For complex optical structures, especially zoom lenses, the default strategy is:
  88. 1. Find the closest official Zemax example or a catalog/reference lens in the same structural family.
  89. 2. Compare candidate seeds against the request on these axes:
  90. - focal-length span
  91. - aperture and entrance pupil behavior
  92. - number of groups and elements
  93. - zoom mechanism and conjugate behavior
  94. - field of view and image format
  95. - package length and back focal space
  96. - glass strategy and asphere usage
  97. 3. Pick the best structural match as the seed design and log the gaps explicitly.
  98. 4. Adapt the seed in small stages instead of redrawing the system from scratch.
  99. 5. Keep seed provenance, mismatch notes, and any manual structural edits visible in the final design log.
  100. For a fast 3x zoom 18-55 mm lens at F/1.4, bias toward the nearest zoom imaging seed even if it is not an exact focal-length match.
  101. ## Connection Diagnostics
  102. For Python automation, **pythonnet** (`pip install pythonnet`) is required. ZOSPy (`pip install zospy`) is also supported as an alternative connection layer.
  103. Default to Interactive Extension for live testing because Standalone may crash or hang
  104. when the API license/session is unhealthy. Use Standalone only when explicitly requested
  105. or after the smoke test passes.
  106. Expected healthy connection:
  107. - Standalone: `CreateNewApplication()` returns an application, `IsValidLicenseForAPI=True`, and `PrimarySystem` is not null.
  108. - Interactive Extension: OpticStudio must be open in an extension-ready state; `ConnectAsExtension(0)` must return an application with valid API license and primary system.
  109. If a connection object exists but `IsValidLicenseForAPI=False` or `PrimarySystem` is null,
  110. treat it as not usable for automation and fix the OpticStudio extension/license state before
  111. running the design loop.
  112. Do not retry Standalone repeatedly after an OpticStudio exception dialog or timeout.
  113. Clear the dialog, restart OpticStudio if needed, then validate Interactive Extension first with:
  114. ```powershell
  115. powershell -ExecutionPolicy Bypass -File .\scripts\connection_smoke_test.ps1
  116. ```
  117. ### ZOS-API Quirks (2024 R1)
  118. - `system.LDE.StopSurface = N` — set stop by property, not `MakeSurfaceStop()`.
  119. - `system.MFE` — access merit function editor directly, not via `Tools.OpenMeritFunction()`.
  120. - MCE: `AddConfiguration(True)` — takes bool, not int.
  121. - MCE: `ChangeType(MultiConfigOperandType.THIC)` — use enum, not string.
  122. - Optimization wizard: `wizard.OK()` not `Ok()`. Properties: `Ring`, `Arm`, `Data` (singular).
  123. - Python.NET 3.0: cannot assign `int` to enum properties (e.g. `tool.Cycles`).
  124. - `SaveAs()` requires absolute paths; relative paths may fail with non-ASCII directories.
README.md · README · 303 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # AI Zemax Optical Design
  2. Automated optical design skill for **Claude Code and Codex** — drives **Ansys Zemax OpticStudio** through ZOS-API to turn optical requirements into executable, multi-stage design loops.
  3. [![version](https://img.shields.io/badge/version-1.3.0-blue)](https://github.com/Jerry-del975/ai-zemax-optical-design)
  4. [![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
  5. ---
  6. ## What's New in v1.3.0
  7. - **Profile-driven zoom lens design** — `zoom_lens_design_agent.py` is no longer hardcoded to APS-C 18-55mm. The complete starting prescription (surfaces, materials, variable gaps, MCE setup, optimization variables per stage) is defined in a standalone JSON profile. Swap profiles to design different zoom systems without touching Python code.
  8. - **Zoom lens profile schema** — new `lens_profile` field in requirements references a JSON profile file or inline object. Profiles define every surface, variable gap, glass material, stop location, merit function parameters, and per-stage variable release lists. See `examples/profiles/apsc_18_55_f14_zoom_profile.json` for the first example and `references/requirements-schema.md` for the schema.
  9. - **Per-configuration gap initialization** — `resolve_gap_initial_value()` supports three priority levels: explicit `gap_values_mm` in each zoom configuration → per-config name matching in `variable_gaps.per_config` → `default_mm` fallback. No more array-index-based gap lookup.
  10. - **Surgical variable control** — each optimization stage uses profile-defined surface lists (`feasibility_radius_surfaces`, `image-quality_radius_surfaces`, `material_surfaces`, etc.) instead of varying every surface. This prevents over-parameterization and accelerates convergence.
  11. - **`InstanceId` parameterization** — PowerShell connection scripts now accept `-InstanceId` (default 1) instead of hardcoded `ConnectAsExtension(0)`.
  12. - **pythonnet fallback singlet script** — new `scripts/design_single_lens_pythonnet.py` is a lightweight alternative that connects directly via `clr` / pythonnet without ZOSPy. Intended as a fallback for environments where ZOSPy cannot be installed; the primary connection layer for all design agents remains ZOSPy.
  13. - **Zoom lens profile unit tests** — `tests/test_zoom_lens_profile.py` validates profile loading from path, prescription building with stop surfaces, and gap initialization priority logic.
  14. ## What's New in v1.2.0
  15. - **Zoom lens design agent** — new `scripts/zoom_lens_design_agent.py` for multi-configuration zoom systems with automatic MCE setup, staged optimization, and per-configuration analysis export.
  16. - **APS-C 18-55mm F/1.4 example** — complete zoom requirements and 4-group starting prescription with 3× zoom ratio, constant F/1.4 aperture.
  17. - **Hardened ZOS-API patterns** — fixed real-world API mismatches discovered during intensive testing: `MultiConfigOperandType` enum usage, MCE `AddConfiguration` signatures, optimization wizard property names, `LDE.StopSurface`, Python.NET 3.0 enum handling, and more.
  18. - **Automated analysis export** — per-configuration spot, MTF, wavefront, ray fan, and distortion analyses for every stage.
  19. - **Extended merit function builder** — built-in optimization wizard integration plus first-order targets (EFFL, WFNO, REAY, AXCL, LACL, DIMX) and manufacturing constraints (MNCT, MNET, MNEA, MXSD, MNEG, GCOS).
  20. ## What's New in v1.1.0
  21. - **ZOSPy integration** — connection layer uses [ZOSPy](https://github.com/MREYE-LUMC/ZOSPy) for automatic version discovery across OpticStudio v20.3 through v26+. A standalone pythonnet fallback script is also available for environments where ZOSPy cannot be installed.
  22. - **Multi-version support** — OpticStudio v20.3 through v26+.
  23. - **Dual-mode connection** — Interactive Extension (recommended) and Standalone.
  24. ---
  25. ## Installation
  26. ```bash
  27. # Clone the repo
  28. git clone https://github.com/Jerry-del975/ai-zemax-optical-design.git
  29. cd ai-zemax-optical-design
  30. # Install Python dependencies
  31. pip install zospy pythonnet
  32. # Install as Claude Code skill (default)
  33. npm install
  34. # Or install as Codex skill
  35. npm run install:codex
  36. ```
  37. The postinstall script deploys the skill to `~/.claude/skills/ai-zemax-optical-design/` by default. To install for Codex, run `npm run install:codex`; this deploys to `${CODEX_HOME:-~/.codex}/skills/ai-zemax-optical-design/`. Restart the target agent after installation.
  38. ### Prerequisites
  39. | Component | Requirement |
  40. |-----------|-------------|
  41. | **OS** | Windows 10/11 |
  42. | **OpticStudio** | 2024 R1 (tested), v20.3+ (via ZOSPy) |
  43. | **Python** | 3.10+ |
  44. | **Python packages** | `zospy>=2.1` (primary connection, multi-version auto-discovery), `pythonnet` (underlying .NET bridge, also used as fallback when ZOSPy is unavailable) |
  45. | **Claude Code or Codex** | latest |
  46. ---
  47. ## Quickstart
  48. ### 1. Smoke test connection
  49. Make sure OpticStudio is open, then:
  50. ```bash
  51. python scripts/connection_smoke_test.py
  52. # Expected: "Connected: yes"
  53. ```
  54. ### 2. Design a lens
  55. **Simple prime lens:**
  56. ```bash
  57. python scripts/automated_design_agent.py \
  58. --requirements examples/minimal_imaging_requirements.json \
  59. --out output/my-design
  60. ```
  61. **Zoom lens (APS-C 18-55mm F/1.4):**
  62. ```bash
  63. python scripts/zoom_lens_design_agent.py \
  64. --requirements examples/apsc_18-55_f1.4_zoom_requirements.json \
  65. --out output/aps-c-zoom
  66. ```
  67. **Custom zoom lens (your own profile):**
  68. ```bash
  69. # 1. Create a profile JSON (copy examples/profiles/ as starting point)
  70. # 2. Point requirements.lens_profile to your profile
  71. python scripts/zoom_lens_design_agent.py \
  72. --requirements my_zoom_requirements.json \
  73. --out output/my-zoom-design
  74. ```
  75. ### 3. Review results
  76. ```
  77. output/aps-c-zoom/
  78. ├── zoom_baseline.zmx ← Baseline lens (before optimization)
  79. ├── zoom_feasibility.zmx ← After feasibility stage
  80. ├── zoom_image-quality.zmx ← After image quality optimization
  81. ├── zoom_field-balance.zmx ← After field balancing
  82. ├── zoom_manufacturability.zmx ← Final lens (all stages)
  83. ├── design-log.jsonl ← Machine-readable event log
  84. ├── metrics-*.json ← Per-stage merit values
  85. ├── requirements.json ← Normalized requirements (copy)
  86. └── analyses/
  87. ├── baseline/ ← 5 analyses × 3 configurations
  88. ├── feasibility/
  89. ├── image-quality/
  90. ├── field-balance/
  91. └── manufacturability/
  92. ```
  93. ---
  94. ## What It Does
  95. This skill turns Claude Code or Codex into a Zemax automation agent:
  96. 1. **Parse requirements** — normalize optical specs from JSON or existing `.zmx` / `.zos` / `.zar` files
  97. 2. **Build or load models** — create sequential starting prescriptions (prime or zoom), or adapt existing designs
  98. 3. **Setup multi-configuration** — automatic MCE operand setup for zoom systems with variable air gaps
  99. 4. **Run baseline analyses** — spot diagrams, FFT MTF, wavefront maps, ray fans, field curvature/distortion
  100. 5. **Stage optimization** — feasibility → image quality → field balance → manufacturability
  101. 6. **Export everything** — versioned lens files, analysis text exports, metrics JSON, and design logs
  102. ---
  103. ## Project Structure
  104. ```
  105. ├── SKILL.md # Skill definition (loaded by Claude Code or Codex)
  106. ├── README.md
  107. ├── package.json
  108. ├── install.js # Installer: deploys skill to ~/.claude/skills/ or ~/.codex/skills/
  109. │
  110. ├── scripts/
  111. │ ├── zos_design_primitives.py # Core: ZOSPy connection, analysis, optimization, save
  112. │ ├── automated_design_agent.py # Prime lens design controller (ZOSPy)
  113. │ ├── zoom_lens_design_agent.py # ★ Profile-driven zoom design controller (ZOSPy)
  114. │ ├── design_single_lens_pythonnet.py # ★ Lightweight pythonnet fallback singlet (no ZOSPy)
  115. │ ├── connection_smoke_test.ps1 # PowerShell ZOS-API health check
  116. │ ├── connection_smoke_test.py # Python ZOS-API health check (ZOSPy)
  117. │ └── design_single_lens_interactive.ps1
  118. │
  119. ├── references/
  120. │ ├── requirements-schema.md # Normalized input schema
  121. │ ├── merit-function.md # Staged merit-function rules
  122. │ ├── result-parsing.md # Analysis export & logging rules
  123. │ └── zos-api-patterns.md # ZOS-API 2024 R1 reference
  124. │
  125. ├── examples/
  126. │ ├── profiles/
  127. │ │ └── apsc_18_55_f14_zoom_profile.json # ★ APS-C 4-group zoom profile (new)
  128. │ ├── minimal_imaging_requirements.json
  129. │ ├── apsc_18-55_f1.4_zoom_requirements.json
  130. │ └── seeded_complex_zoom_requirements.json
  131. │
  132. ├── tests/
  133. │ ├── test_zos_design_primitives.py
  134. │ ├── test_automated_design_agent.py
  135. │ ├── test_requirements_schema.py
  136. │ └── test_zoom_lens_profile.py # ★ Profile loading & gap init tests (new)
  137. │
  138. └── output/ # ★ Design outputs (gitignored)
  139. ```
  140. ---
  141. ## Supported Design Types
  142. | Type | Agent | Connection | Features |
  143. |------|-------|------------|----------|
  144. | Prime lens | `automated_design_agent.py` | ZOSPy (default) | Single-config, EFFL/BFL/F# targets |
  145. | Zoom lens | `zoom_lens_design_agent.py` | ZOSPy (default) | JSON profile-driven, MCE multi-config, variable air gaps, per-config EFL |
  146. | Seed-based | `automated_design_agent.py` | ZOSPy (default) | Load `.zmx` as starting point, adapt to targets |
  147. | Singlet (fallback) | `design_single_lens_pythonnet.py` | pythonnet direct | No ZOSPy dependency; lightweight verification |
  148. ---
  149. ## Optimization Stages
  150. | Stage | What It Does | Variables |
  151. |-------|-------------|-----------|
  152. | **Baseline** | Export analyses without optimization | None |
  153. | **Feasibility** | Hit EFL, F/#, BFL, image height targets | MCE gaps, BFL, profile-defined feasibility radii |
  154. | **Image Quality** | Minimize RMS spot, wavefront, chromatic error | Profile-defined radii + thicknesses |
  155. | **Field Balance** | Equalize performance across fields/configs | Full profile-defined radii + thicknesses |
  156. | **Manufacturability** | Enforce edge thickness, glass constraints | Profile-defined radii + thicknesses + glass substitutions |
  157. ---
  158. ## Zoom Lens Profile System (v1.3)
  159. The zoom agent is now fully profile-driven. Instead of a hardcoded prescription, swap a JSON file to design any zoom lens.
  160. ```json
  161. {
  162. "name": "my zoom profile",
  163. "image_surface": 12,
  164. "surfaces": [
  165. {"surface": 1, "radius": 60.0, "thickness": 5.0, "material": "N-BK7"},
  166. {"surface": 2, "radius": -80.0, "thickness": 8.0, "material": "", "variable_gap": "g1"},
  167. {"surface": 5, "radius": 55.0, "thickness": 4.0, "material": "N-BK7", "stop": true}
  168. ],
  169. "variable_gaps": [
  170. {"name": "g1", "surface": 2, "default_mm": 8.0, "per_config": {"wide": 6.0, "tele": 14.0}}
  171. ],
  172. "merit": {"bfl_surface": 11, "max_field_index": 3},
  173. "variables": {
  174. "feasibility_radius_surfaces": [1, 3, 5],
  175. "image-quality_radius_surfaces": [1, 2, 3, 4, 5],
  176. "image-quality_thickness_surfaces": [2, 4, 7],
  177. "material_surfaces": [1, 3, 5]
  178. }
  179. }
  180. ```
  181. Key profile fields:
  182. | Section | Purpose |
  183. |---------|---------|
  184. | `surfaces` | Complete prescription — radius, thickness, material, stop flag, group label, `variable_gap` tag |
  185. | `variable_gaps` | Which gaps vary with zoom position, default values, and per-configuration overrides |
  186. | `merit` | BFL surface reference and max field index for merit function construction |
  187. | `mce` | Multi-Configuration Editor settings (aperture/field operand inclusion) |
  188. | `variables` | Per-stage surface lists controlling exactly which radii, thicknesses, and materials are released |
  189. Each zoom configuration can override initial gap values via `gap_values_mm` or `per_config` name matching. See `examples/profiles/apsc_18_55_f14_zoom_profile.json` for a complete 4-group 24-surface example.
  190. ---
  191. ## Connection
  192. ### Default: ZOSPy (multi-version auto-discovery)
  193. All design agents use ZOSPy as the primary connection layer. ZOSPy automatically discovers your OpticStudio installation (v20.3 through v26+), loads the correct ZOSAPI DLLs, and returns a ready-to-use application object. No hardcoded paths, no version-specific configuration.
  194. ```python
  195. from zos_design_primitives import connect_zemax
  196. # Interactive Extension (OpticStudio must be open — recommended)
  197. app = connect_zemax(standalone=False)
  198. # Standalone (creates new OpticStudio instance)
  199. app = connect_zemax(standalone=True)
  200. system = app.PrimarySystem
  201. ```
  202. ### Fallback: pythonnet direct connection
  203. When ZOSPy cannot be installed (air-gapped environments, dependency conflicts), `design_single_lens_pythonnet.py` provides a lightweight fallback that loads the ZOSAPI DLLs directly via `clr.AddReference`. This requires manually specifying the OpticStudio install path via `--zos-root` and only supports a single version at a time.
  204. ```bash
  205. python scripts/design_single_lens_pythonnet.py \
  206. --zos-root "D:\Program Files\Ansys Zemax OpticStudio 2024 R1.00" \
  207. --out output/singlet
  208. ```
  209. The two main design agents (`automated_design_agent.py` and `zoom_lens_design_agent.py`) **always use ZOSPy** — there is no scenario where they silently fall back to pythonnet. The pythonnet path exists only in the standalone singlet script for environments that explicitly choose it.
  210. ---
  211. ## Known Limitations
  212. - **MCE operand API** — Python.NET 3.0 has limited enum-to-int conversion; MCE operand types must use `MultiConfigOperandType` enum values explicitly.
  213. - **Chinese paths** — OpticStudio `SaveAs` requires absolute paths; relative paths may silently fail with non-ASCII directory names.
  214. - **Optimization wizard** — properties use `OK()` (uppercase), `Ring`/`Arm`/`Data` (singular), `PupilIntegrationMethod` (full name) — not the intuitive names.
  215. - **Merit function access** — use `system.MFE` directly, not `system.Tools.OpenMeritFunction()`.
  216. - **Stop surface** — set via `system.LDE.StopSurface = N`, not `MakeSurfaceStop()`.
  217. ---
  218. ## Upgrading
  219. ```bash
  220. # Remove old Claude Code skill
  221. rm -rf ~/.claude/skills/ai-zemax-optical-design
  222. # Or remove old Codex skill
  223. rm -rf ~/.codex/skills/ai-zemax-optical-design
  224. # Pull latest
  225. cd ai-zemax-optical-design
  226. git pull origin master
  227. npm install
  228. ```
  229. ---
  230. ## License
  231. MIT © [Jerry](https://github.com/Jerry-del975)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.