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.

Variables:

• name (str | None) – Optional system name (from the NAME operand).

• aperture (dict[str, Any]) – Aperture information keyed by Optiland aperture type string (e.g. {"EPD": 8.0}).

• fields (dict[str, Any]) – Field configuration including type, x/y coordinates and vignetting arrays.

• wavelengths (dict[str, Any]) – Wavelength data including values in microns, weights, and the primary wavelength index.

• surfaces (dict[int, dict[str, Any]]) – Mapping from surface index to a raw operand dict used by the encoder / converter.

• glass_catalogs (list[str] | None) – List of Zemax glass catalog names (GCAT operand).

• mode (str) – Optical mode string; always "Sequential" for v1.

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.

Variables:

• 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).

Variables:

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.

Variables:

• 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.