Welcome to ZOSPy’s documentation!

ZOSPy is a wrapper around the Ansys OpticStudio API that provides a more intuitive way to interact with the ZOS-API through Python using a .NET connection, as described in this Journal of Open Source Software paper. It thereby allows you to do more optics modelling with less coding.

In addition to full access to all the OpticStudio functions through the ZOS-API, ZOSPy provides the following features:

• Wrapper functions for several OpticStudio analyses in zospy.analyses;

• Easy access to solvers in zospy.solvers;

• Easy access to all API constants in zospy.constants;

• Autocomplete for all ZOS-API endpoints and constants;

• Solves common problems related to Python.NET 3 and interaction with the ZOS-API.

Compatibility

ZOSPy officially supports Python 3.10 - 3.14. It may work with older Python versions, but support is not provided for these versions. Furthermore, a working installation of Ansys Zemax OpticStudio is required.

See the below table for compatibility with different versions of Ansys Zemax OpticStudio. More information on compatibility can be found in the compatibility section.

OpticStudio	Compatibility
25.1.1	✔
24.2.2	✔
24.1.3	✔
24.1.0	✔

Older versions of OpticStudio are not tested, but they will likely work with ZOSPy.

Table legend

✔: This version works without problems.
ℹ: The output of all ZOSPy analyses matches the direct OpticStudio output, but the OpticStudio output has shown differences with the output of the reference version (currently OpticStudio 25 R1.01).
⚠: ZOSPy does not fully work.
❌: ZOSPy does not work at all.

Warranty and liability

The code is provided as is, without any warranty. It is solely intended for research purposes. No warranty is given and no rights can be derived from it, as is also stated in the MIT license.

Referencing

When publishing results obtained with this package, please cite our paper in the Journal of Open Source Software:

Vught, L. van, Haasjes, C. & Beenakker, J.W.M. (2024). ZOSPy: Optical ray tracing in Python through OpticStudio. Journal of Open Source Software, 9(96), 5756. https://doi.org/10.21105/joss.05756

Contact

Feel free to contact us via e-mail at zospy@mreye.nl for any inquiries, or visit mreye.nl to discover our research.

Getting started

• Installation
• Simple example
• Frequently Asked Questions

Usage

• Connecting to OpticStudio
• Creating an optical system
• Performing analyses
• Using ZOS-API constants
• Convenience functions
• Compatibility

Examples

• Simple thick lens
• Creating the Escudero-Sanz eye model with ZOSPy
• Retinal illumination in pseudophakic eyes with and without Negative Dysphotopsia
• Raytracing analyses on a Double Gauss lens
• Polarization prism with total internal reflection
• Modelling of a Shack-Hartmann Sensor for eye aberration evaluation
• Patient-specific mapping of fundus photographs to three-dimensional ocular imaging
• Relative peripheral refraction: a predictor for myopia progression - ray tracing simulation example
• Set fields
• Determine lens curvature to match central refraction
• Show model
• Calculate peripheral refraction
• Plot results

Advanced usage

• Logging
• Custom object conversion between the ZOS-API and ZOSPy

Contributing

• Contributing to ZOSPy
  • Contribution ideas
  • Code style
  • Workflow
• Developing analysis wrappers
• Unit tests for ZOSPy
  • How to run
  • Command line options
  • Generating test reference data

zospy.zpcore	Manage the connection with OpticStudio and interact with the optical system.
zospy.analyses	OpticStudio Analyses.
zospy.api.constants	Constants for the ZOS-API.
zospy.api.codecs	Custom object conversions between the CLR and Python.
zospy.functions	Utility functions for ZOSPy.
zospy.solvers	OpticStudio Solvers.

About

• License
• Changelog
• Contact us