matlab-model-optics

# Optical Design and Simulation Library

Use this skill when the user is working with the **Optical Design and Simulation Library** to build, import, analyze, tolerate, or optimize optical systems in MATLAB.

This library may also be referred to as:
- **Optical Design and Simulation Library**
- **Optics Support Package**
- **Optics Add-On**
- **Optics Library**
- **Optics Toolbox**

Use **Optical Design and Simulation Library** as the canonical name in responses unless the user explicitly uses a different name.

## When to Use

Use this skill when the user asks about:
- Optical Systems
- Ray Tracing
- Geometric Optics based analysis like lens distortion, spot diagrams, chromatic aberration, astigmatism and ray fans
- Paraxial Optics
- Optical Coatings
- Polarization or EM analysis (computing Fresnel Coefficients)
- Glass Materials and Glass Catalogs
- Zemax import
- Optical Tolerancing
- Optical System Design and Optimization
- Dynamic optical systems in Simulink (see `references/dynamic-optical-systems-simulink.md`)

## When NOT to Use

Do **not** use this skill when:
- The user is working with physical optics or wave optics (diffraction, interference, coherence)
- The user is working with fiber optics or photonics
- The user needs image processing or computer vision (use Image Processing Toolbox instead)
- The task is purely about Simulink modeling without optical system involvement

## First Steps

When helping a user who is new to the library, start with discovery:
```matlab
help optics
```

To get more details for a specific function:
```matlab
help lensDistortion
doc lensDistortion
```

Many optics APIs are class methods. For class methods, use:
```matlab
help className/functionName
doc className/functionName
```

Example:
```matlab
help opticalSystem/add
```

Use examples in the documentation when the user asks for a larger end-to-end workflow.

## Sample ZMX Files

The Optical Design and Simulation Library ships sample Zemax (`.zmx`) files in the `opticsdata` folder within the support package install location. To find the path:

```matlab
spkgRoot = fullfile(matlabshared.supportpkg.getSupportPackageRoot, "toolbox", "images", "supportpackages", "opticsdata");
dir(fullfile(spkgRoot, "*.zmx"))
```

When a user asks to work with a standard optical system (e.g., "a Cooke triplet", "a doublet", "a telephoto lens") but does not provide their own file:
1. List the available `.zmx` files in the `opticsdata` folder
2. Pick the sample system that best matches the user's request
3. Import it using `zmximport`

This avoids asking the user for a file path when a suitable sample already exists.

## Core Concepts

### opticalSystem

`opticalSystem` is the central object representing a physical optical system.
```matlab
opsys = opticalSystem(Wavelengths=[486.134 587.562 656.281]);
```

### opticalMaterial

`opticalMaterial` represents a glass or optical material.
```matlab
mat = opticalMaterial([1.5168 64.17]);
mat = pickGlass("N-BK7");
```

### opticalCoating

`opticalCoating` represents a thin-film coating applied to surfaces.
```matlab
oc = opticalCoating(CoatingMaterial=["MgF2" "TiO2"], LayerMaterialIndex=[1 2 1 2], LayerThickness=[1 0.5 1 0.5], PrimaryWavelength=550);
oc = pickCoating("AR_MgF2_VIS");
addCoating(opsys, oc);
addCoating(opsys, oc, CoatingSide="front");
```

## Coordinate Systems

Refer to the MATLAB Documentation page called **"Coordinate Systems in Optical Design"** to learn about the coordinate system conventions used to construct optical systems.

### Field Point Angle Convention

When creating a field point with `fieldPoint(Angles=[Hy Hx])`:
- `Hy` — vertical field angle (degrees)
- `Hx` — horizontal field angle (degrees)

Example — a field point at 10 degrees vertical:
```matlab
fp = fieldPoint(Angles=[10 0]);
```

A field point at 10 degrees horizontal:
```matlab
fp = fieldPoint(Angles=[0 10]);
```

### TiltAngles Convention

`TiltAngles=[Rx Ry Rz]` specifies rotations in degrees about each axis:
- `Rx` (first element) — rotation about the X-axis
- `Ry` (second element) — rotation about the Y-axis
- `Rz` (third element) — rotation about the Z-axis

Example — a mirror tilted 45 degrees about the X-axis:
```matlab
addMirror(opsys, TiltAngles=[45 0 0]);
```

## Common Interaction Patterns

### Pattern: Build → Visualize → Analyze

Many user requests follow this sequence:
1. Build or import an optical system
2. Define field points and wavelengths
3. Run an analysis function
4. Inspect returned values
5. Visualize results

```matlab
%% 1. Build
opsys = opticalSystem(Wavelengths=587.562);
addRefractiveSurface(opsys, Radius=50, Material=pickGlass("N-BK7"), SemiDiameter=10, DistanceToNext=5);
addRefractiveSurface(opsys, Radius=-50, SemiDiameter=10, DistanceToNext=20);
addImagePlane(opsys, SemiDiameter=10);
opsys.FieldPoints = fieldPoint(Angles=[0 0; 10 0]);

%% 2. Visualize
h2 = view2d(opsys);

%% 3. Analyze
tra = rayAberration(opsys);
hra = show(tra);
```

### Pattern: Compute → Show

Many analyses follow a **compute first, visualize second** pattern.
```matlab
spotResult = spot(opsys);
spotDiagram(spotResult);
```

```matlab
ldResult = lensDistortion(opsys);
show(ldResult);
```

Use this pattern when the user wants both a numeric result and a plot.

### Pattern: Fresh Copy of Optical System

Explicitly create a fresh copy of the original system if you want to use it as a starting point for multiple different changes. This is particularly useful for tolerancing and sensitivity analysis, where parameters of the original system are mutated repeatedly.
```matlab
newSys = copy(opsys);
```

This avoids accumulating perturbations across trials unless accumulation is explicitly intended.

## Task: Construct Optical System from Prescription Table

Sequential optical systems are often specified as **prescription tables** (common in patent documents, textbooks, and optical design references).

Each row represents a surface or optical element, with columns such as:
- Radius of curvature
-