optiland.fileio.zemax

Zemax file format support for Optiland.

Public re-exports for the zemax subpackage.

class OpticToZemaxConverter(optic: Optic)

Converts an Optic object to a ZemaxDataModel.

This is the mirror of ZemaxToOpticConverter and constitutes the first stage of the write pipeline (Optic -> ZemaxDataModel -> text lines).

Parameters:

optic – The Optic to convert.

convert() → ZemaxDataModel

Build and return the ZemaxDataModel for the optic.

Returns:

A populated ZemaxDataModel ready for ZemaxFileEncoder.

class ZemaxDataModel(name: str | None = None, aperture: dict[str, ~typing.Any] = <factory>, fields: dict[str, ~typing.Any] = <factory>, wavelengths: dict[str, ~typing.Any] = <factory>, surfaces: dict[int, dict[str, ~typing.Any]] = <factory>, glass_catalogs: list[str] | None = None, mode: str = 'Sequential')

Intermediate representation of a Zemax OpticStudio optical system.

This dataclass is the stable lingua franca shared between the read and write paths. The reader populates it from a parsed .zmx file; the writer produces it from an Optic object.

name

Optional system name (from the NAME operand).

Type:

str | None

aperture

Aperture information keyed by Optiland aperture type string (e.g. {"EPD": 8.0}).

Type:

dict[str, Any]

fields

Field configuration including type, x/y coordinates and vignetting arrays.

Type:

dict[str, Any]

wavelengths

Wavelength data including values in microns, weights, and the primary wavelength index.

Type:

dict[str, Any]

surfaces

Mapping from surface index to a raw operand dict used by the encoder / converter.

Type:

dict[int, dict[str, Any]]

glass_catalogs

List of Zemax glass catalog names (GCAT operand).

Type:

list[str] | None

mode

Optical mode string; always "Sequential" for v1.

Type:

str

aperture: dict[str, Any]

fields: dict[str, Any]

glass_catalogs: list[str] | None = None

mode: str = 'Sequential'

name: str | None = None

surfaces: dict[int, dict[str, Any]]

to_dict() → dict[str, Any]

Return the data model as a plain dictionary.

Returns:

A plain dict representation suitable for use with ZemaxToOpticConverter.

wavelengths: dict[str, Any]

class ZemaxDataParser(filename: str)

Parses a Zemax .zmx file into a ZemaxDataModel.

Parameters:

filename – Path to the .zmx file to parse.

filename

The file path being parsed.

data_model

The ZemaxDataModel being populated during parsing.

parse() → ZemaxDataModel

Read the Zemax file and extract optical data into a ZemaxDataModel.

Tries UTF-16 LE, UTF-8, and ISO-8859-1 encodings in that order.

Returns:

A populated ZemaxDataModel.

Raises:

ValueError – If the file cannot be read or contains no aperture data.

class ZemaxFileSourceHandler(source: str)

Handles source input resolution for Zemax files (local vs URL).

source

The original source string (file path or URL).

cleanup() → None

Remove the temporary file if one was created.

get_local_file() → str

Resolve the source to a local file path.

Downloads the file to a temporary location if the source is a URL.

Returns:

The local file path.

Raises:

ValueError – If the URL download fails.

class ZemaxToOpticConverter(zemax_data: dict[str, Any] | ZemaxDataModel)

Converts a ZemaxDataModel into an Optic object.

Also implements BaseOpticReader so that the full pipeline (source resolution -> parsing -> conversion) can be triggered via read().

Parameters:

zemax_data – A plain dict (legacy) or ZemaxDataModel containing the Zemax optical system data.

data

The Zemax data as a plain dict.

optic

The Optic instance built by convert().

current_cs

Running cumulative CoordinateSystem used when processing coordinate-break surfaces.

convert() → Optic

Convert the stored Zemax data dict into an Optic object.

Returns:

The fully-configured Optic instance.

read(source: str) → Optic

Read a Zemax file and return a fully-configured Optic.

Parameters:

source – Local file path or URL to a .zmx file.

Returns:

A configured Optic instance.

save_zemax_file(optic: Optic, filepath: str) → None

Export an Optic to a Zemax OpticStudio .zmx file.

The file is written in UTF-16 LE encoding to match OpticStudio’s default. Warnings are issued via Python’s warnings module for:

• Glasses with no Zemax catalog entry (written as MODEL glass).

• Pickups or solves that cannot be represented (resolved values exported).

Parameters:

• optic – The optic to export.

• filepath – Destination path (should end in .zmx).

Raises:

• NotImplementedError – If the optic contains a surface type not yet supported by the writer.

• ValueError – If a coordinate system cannot be decomposed into COORDBRK surfaces.