v1.3.0

This release adds support for retrieving images from the system viewers. Images can be accessed as arrays (default) or exported to a file.
Furthermore, support for the OpticStudio analyses Wavefront Map, Geometric Image Analysis and Physical Optics Propagation is added.

This release also adds a new, experimental interface for analyses that will be the default from ZOSPy 2.0.0. This change is necessary to streamline and simplify the process of adding new analyses. Please test this new interface and post your feedback in the discussion!

Added

• Wavefront analysis: zospy.analyses.wavefront.wavefront_map (!61)
• Extended scene analysis: zospy.analyses.extendedscene.geometric_image_analysis (!61)
• Physical optics analysis: zospy.analyses.physicaloptics.physical_optics_propagation (!61)
  • Helper functions to generate specific parameter dictionaries for these analyses: zospy.analyses.physicaloptics.pop_create_beam_parameter_dict, zospy.analyses.physicaloptics.pop_create_fiber_parameter_dict
• Convenience function to change the aperture type of a surface in sequential mode: zospy.functions.lde.surface_change_aperturetype
• Experimental new interface for analyses in zospy.analyses.new (#78, #15)
• Add support for system viewer exports in zospy.analyses.systemviewers.viewer_3d and
  zospy.analyses.systemviewers.cross_section (#80).

Changed

• Updated zospy.functions.lde.surface_change_type to also support surfaces that require the specification of a file to load. (!61)
• Added support for dictionary parameters in both zospy.tests and zospy.scripts.generate_test_reference_data. (!61)

Other contributors

• @crnh @jwmbeenakker @LucVV
• This release was in part funded by the Netherlands Organisation for Scientific Research (NWO) through the OPENOPTICS project.

v1.2.1

This release fixes some locale-related issues that occurred on German systems (#66, #67).
One of these issues (#66) caused the import of ZOSPy to fail on these systems.
@laser-axel thanks for reporting these issues!

Fixed

• Unsupported locale setting on import (#66, #69)
• Zernike Standard Coefficients analysis parses dates as floats under German locale (#70)

Changed

• Custom __dir__ method for zospy.analyses.base.Analysis.
  dir now shows both the wrapper members and the OpticStudio analysis members (!56)

Other contributors

• @jwmbeenakker
• @crnh
• This release was in part funded by the Netherlands Organisation for Scientific Research (NWO) through the OPENOPTICS project.

v1.2.0

In addition to some new features (new analyses and solvers), this release introduces some under-the-hood changes in ZOSPy, which resolve long-standing issues in the ZOS-API and Python.NET communication¹.
Additionally OpticStudio R2024 and Python 3.12 are now supported.

What's new

License change

ZOSPy is now licensed under the MIT license.
This license change was approved by all our contributors (see #57).

A definitive fix for problems related to Python.NET 3

Python.NET 3.0.0 introduced some breaking changes, which made parts of the ZOS-API not easily accessible anymore¹.
The current work-around is to use the __implementation__ attribute provided by Python.NET to access these parts of the ZOS-API.
This works, but it isn't great.
A part of this problem was already resolved in ZOSPy 1.0.0, where we patched the analysis objects to restore the old behavior of the ZOS-API.
While this fixed most of the problems, there appeared to be other cases where __implementation__ still needed to be used, for example to access the SurfaceData for a surface in the Lens Data Editor:

abcd_surface = oss.LDE.InsertNewSurfaceAt(3)
zp.functions.lde.surface_change_type(abcd_surface, zp.constants.Editors.LDE.SurfaceType.ABCD)

# Change the "A" value of abcd_surface for the x direction
abcd_surface.SurfaceData.__implementation__.Ax = 3

In ZOSPy 1.2.0 we introduce codecs that automatically customizes the object conversion behavior of Python.NET and automatically accesses the __implementation__ attribute for certain types.
The previous example now looks like this:

# Change the "A" value of abcd_surface for the x direction
# No __implementation__ needed anymore!
abcd_surface.SurfaceData.Ax = 3

We scanned the full ZOS-API and enabled this automatic conversion for all types that have the Python.NET 3 problem and do not offer an alternative way of accessing them.
Read more about this change and the types which are converted in our documentation.

This change deprecates zospy.functions.nce.get_object_data, which fixed this issue for the Non-sequential Component Editor's object data.
It will be removed in ZOSPy 2.0.0.

New unified connection method

Connecting to OpticStudio has become easier.
You now need only two lines:

import zospy as zp

# Initialize the ZOS-API
zos = zp.ZOS()

# Connect to OpticStudio
oss = zos.connect()

See how this was done before

For reference, this is how it was done before:

import zospy as zp

# Initialize the ZOS-API
zos = zp.ZOS()
zos.wakeup()

# Connect to OpticStudio
zos.create_new_application()
oss = zos.get_primary_system()

This method connects to OpticStudio and returns the primary optical system if the connection succeeds, or raises an exception if it fails to connect.
The connection mode can be supplied as an argument. Use zos.connect(mode="standalone") to connect in standalone mode (the default), or zos.connect(mode="extension") to connect as extension.

Additionally is is possible to connect to a specific OpticStudio version when multiple versions are installed on you system. By default, ZOSPy will connect with the newest version, but it is now possible to connect with an older version, by using the opticstudio_directory parameter of ZOS:

import zospy as zp

zos = zp.ZOS(opticstudio_directory="path/to/opticstudio/installation/directory")

This release deprecates ZOS.wakeup, ZOS.connect_as_extension, ZOS.create_new_application and ZOS.connect_as_standalone.
Please upgrade your code to the new connection method, as the deprecated methods will be removed in ZOSPy 2.0.0²

Disconnect from OpticStudio

It is now possible to disconnect from OpticStudio using the ZOS.disconnect method.

Smarter path handling

The ZOS-API leaves all file path handling to the user: it only accepts absolute paths, and does not throw an exception if a path does not exist. This was previously also the case when using the ZOS-API through ZOSPy: methods like OpticStudioSystem.load and OpticStudioSystem.save_as did not perform any path validation and failed silently.

This release adds path handling to these methods: relative paths are now allowed, and a FileNotFoundError is raised if a path does not exist.
This means you can now easily save an optical system in the working directory:

oss.save_as("optical_system.zmx")

or load an optical system using a relative path:

oss.load("systems/optical_system.zmx")

Support for OpticStudio 2024 R1 and Python 3.12

OpticStudio 2024 R1 is now officially supported.
The unit tests showed no changes in output between OpticStudio 2023 R1 and 2024 R1.
Furthermore, ZOSPy's autocomplete stubs were updated to include all features added in OpticStudio 2024 R1.
Please note that these features are also suggested by the auto-completion if you are using an older version of OpticStudio, although they are not available.
Additonally, support for Python 3.12 is added.

Other new features

• There is a new wrapper function for the Huygens MTF analysis: zospy.analyses.mtf.huygens_mtf. @noahrbn thanks a lot for your first contribution!
• The Pickup Chief Ray solver is now accessible through zospy.solvers.pickup_chief_ray.

Full changelog

Click to reveal full changelog

Added

• New, unified, connection method ZOS.connect. This method replaces the existing connection methods
  ZOS.connect_as_extension, ZOS.create_new_application and ZOS.connect_as_standalone.
  The connection mode is passed as an argument and the primary system is always returned (!47)
• The OpticStudio installation directory can be manually specified using the opticstudio_directory
  parameter of the ZOS class. This is particularly useful if multiple OpticStudio versions are installed
  on the same system and you want to use a specific version (!47)
  • Note: when this parameter is used, the ZOSAPI_NetHelper is not loaded and ZOS.ZOSAPI_NetHelper
    remains unset.
• zospy.api.codecs for customized conversions between ZOS-API types and Python types (!48)
• zospy.api.codecs.OpticStudioInterfaceEncoder for automatic downcasting of certain common generic interfaces
  to their implementation (e.g. the use of __implementation__ is no longer needed) (!48)
• MTF analysis: huygens_mtf (#55)
• pickup_chief_ray solver (!38)
• ZOS.disconnect to disconnect from OpticStudio (!47)
• Support for OpticStudio 2024 R1 (!51)
• Support for Python 3.12 (!54)

Fixed

• OpticStudioSystem.load fails silently when path is incorrect or relative (#34)
• Saving after connecting in extension mode fails because OpticStudioSystem._OpenFile is not set.
  When connecting in extension mode, _OpenFile is now set with the path to the opened system to prevent this (#41)

Changed

• Changed license to MIT (#57, #58) - 2023-12-22
• Deleting a zospy.zpcore.ZOS object now automatically calls ZOS.disconnect (!47)
• When connecting in extension mode, it is not necessary anymore to save the primary system with
  OpticStudioSystem.save_as before it can be saved with OpticStudioSystem.save (!47, #41)
• zospy.analyses.base.Analysis now uses zospy.api.codecs.OpticStudioInterfaceEncoder to downcast
  analysis interfaces to their implementation (!48)
• Accept relative paths and check if the path exists in OpticStudioSystem.load and OpticStudioSystem.save_as (!50)
• Use zospy.constants.process_constant for parsing the from_column argument of zospy.solvers.surface_pickup.
  This column can now be specified as either a value from zospy.constants or a string (!53)

Deprecated

• ZOS.connect_as_extension, ZOS.create_new_application and ZOS.connect_as_standalone.
  They have been replaced with ZOS.connect (!47)
• zospy.functions.nce.get_object_data is deprecated because its task is now performed by
  zospy.api.codecs.OpticStudioInterfaceEncoder (!48)

Other contributors

• @jwmbeenakker
• @LucVV
• @crnh
• This release was in part funded by the Netherlands Organisation for Scientific Research (NWO) through the OPENOPTICS project.

1. See e.g. https://community.zemax.com/zos-api-12/pythonnet-3-0-not-recommended-to-use-for-zosapi-python-3474, https://community.zemax.com/zos-api-12/zos-api-supporting-python-3-10-and-python-net-3-0-3407. ↩ ↩²

2. Which we plan to release this year. ↩

v1.1.2

This release fixes an issue with datagrid parsing. Previously, the row indices were reversed. As a result, accessing a value in the datagrid using its index (e.g. using pandas.DataFrame.loc) returned the wrong value. This bug affected the Huygens PSF and Surface Curvature analyses.

Fixed

• Reversed row index of datagrids in zospy.utils.zputils.unpack_datagrid (#56). Thanks for noticing this, @andibarg!

Other contributors

• @LucVV

v1.1.1

Added

• ZOS.connect_as_standalone as alias for ZOS.create_new_application (#26)
• New parameter return_primary_system for ZOS.connect_as_extension and ZOS.create_new_application. These methods return the primary optical system if this parameter is True. If the license is not valid for the ZOS-API, a ConnectionRefusedError is raised (#26)
• zospy.functions.nce.get_object_data to get the data of an NCE object (#30)

Fixed

• Erroneous parsing of analyses results when textfile encoding was not set to Unicode by implementing zospy.zpcore.ZOS.get_txt_file_encoding (!36)
• Bug that did not allow users to change the LensUpdateMode directly through OpticStudioSystem.LensUpdateMode (#40)

Changed

• Updated how and when constants in zospy.api.config are determined for more clarity (!39)
• Update the error message in zospy.ZOS to explain why only a single instance of ZOS is allowed (#24)
• Load ZOS-API DLLs in ZOS.__init__ (#26)

Deprecated

• Separate calls to ZOS.wakeup are now redundant. This method will be removed in a later release (#26)

v1.1.0

This release introduces a number of new analyses, a few helper functions in zospy.functions, and new number parsing methods for analysis result parsing.

Added

• Polarization analyses: polarization_pupil_map, transmission (#14)
• System viewer analyses: cross_section, viewer_3d, shaded_model, nsc_3d_layout, nsc_shaded_model (LUMCgit !20)
• Documentation for all examples (LUMCgit !25)
• version property for the ZOS class (LUMCgit !21)
• zospy.utils.pyutils.atox, zospy.utils.pyutils.xtoa and _config.THOUSANDS_SEPARATOR for locale-aware conversion between strings and numbers (LUMCgit !26)
  • These functions are used in parsing data files generated by OpticStudio analyses and are a first step towards more robust analysis result parsing.
• .zenodo.json to have more control over Zenodo (LUMCgit !32)
• zospy.functions.lde.find_surface_by_comment and zospy.functions.nce.find_object_by_comment to find LDE surfaces / NCE objects based on their comments (#18)

Fixed

• Bug when setting the MTF type though the ZOS-API for OpticStudio < 21.2; added zospy.analyses.mtf._correct_fft_through_focus_mtftype_api_bug (!21)
• Incorrect implementation of zospy.zpcore.ZOS.get_system (LUMCgit !30)
• Incorrect examples in the docstrings of zospy.functions.lde.surface_change_type and zospy.functions.nce.object_change_type (LUMCgit !31)

Changed

• Converted some examples into Jupyter notebooks
• Renamed _config.DECIMAL to _config.DECIMAL_POINT (LUMCgit !26)
• Use .zmx files instead of .zos files for unit test reference system files (LUMCgit !23)
• Updated compatibility information in README.md (LUMCgit !29)

Removed

• Empty method zospy.zpcore.ZOS.licence_check (LUMCgit !30)

New contributors

• @Omnistic added a method to find NCE objects by comment (#18), thanks!

Other contributors

@LucVV, @jwmbeenakker , @andibarg

v1.0.0

What's new

Support for Python.NET 3.0.x

From now on, ZOSPy supports Python.NET 3.0.x. Python.NET 3.0 introduced some breaking changes, which are reflected in ZOSPy. Most notably, analyses now need to be created in a slightly different (but more Pythonic!) way. Furthermore it is no longer possible to use integers instead of Enum values.

New interface for analyses

Zemax analyses that are not included in zospy.analyses now need to be created using the zospy.analyses.new_analysis function:

import zospy as zp

...

draw_3d = zp.analyses.new_analysis(oss, zp.constants.Analysis.AnalysisIDM.Draw3D, settings_first=False)

By default, this function returns an analysis without executing it, so its settings can be adjusted prior to running the analysis. This behavior can be overridden using the settings_first parameter.

The behaviour of analyses included in zospy.analyses remains the same.
ZOSPy 1.0 introduces a new Analysis object, which wraps the Zemax analysis object. Furthermore, analysis-related functions from zospy.utils.zputils were moved to this object, e.g.

# Old
zp.utils.zputils.set_field(analysis, 0)

# New
analysis.set_field(0)

Initial support for solvers

Initial support for solvers was added in zospy.solvers, providing a more Pythonic way to interact with them. For now, only the Fixed, Variable, MaterialModel and Position solvers are supported, but more are planned for future releases. Contributions are of course welcome, and it is actually quite easy to add support for the other solvers!

Autocomplete for the ZOS-API

This release introduces autocomplete for the full ZOS-API, which significantly improves the developer experience.

Other changes

Removed support for int values instead of constants

Following the upgrade to Python.NET 3.0.x, it is no longer supported to use integer values were a value from zospy.constants should be used. Removing these conversions keeps the code more maintainable, and the addition of autocomplete makes finding the right constant fairly straightforward.

Strings can still be parsed to constants with the new zospy.solvers.process_constant function:

zp.constants.process_constant(zp.constants.Analysis.AnalysisIDM, "Draw3D")
		  

Small changes to constant processing

Formerly, ZOSPy wrapped every constant in a pandas.Series object. This added unnecessary functionality to the constants, which resulted in degraded performance of ZOSPy and therefore has been removed. As a result, some methods to access constants do not work anymore, for example:

# This doesn't work anymore
zp.constants.Editors.LDE.CoordinateReturnType["OrientationOnly"]
zp.constants.Editors.LDE.CoordinateReturnType.loc[1]

# This is now the preferred way
zp.constants.Editors.LDE.CoordinateReturnType.OrientationOnly

# Integer indices do still work
zp.constants.Editors.LDE.CoordinateReturnType[1]

When a constant in Zemax includes a value named "None", it is renamed to None_ to prevent conflicts with Python's built-in None value.

# Old
zp.constants.Editors.LDE.CoordinateReturnType["None"]

# New
zp.constants.Editors.LDE.CoordinateReturnType.None_

Unit tests

Unit tests have been added for the core functionality and all analyses currently implemented in ZOSPy. Please refer to the test documentation for information on how to run these tests.

Python support

Only Python versions supported by both Pandas and NumPy are officially supported. This means that ZOSPy 1.0.0 supports Python 3.9+.

v0.6.2

What's Changed

• Added support for additional analyses:
  • Rays and spots, available via zospy.analyses.raysandspots:
    • single_ray_trace()
    • ray_fan()
• Added new example: Ray trace double gauss
• Added Config.py which holds configuration settings. Floating point separator is now determined on initiation of ZOSPy.

New Contributors

• @crnh made their first contribution in #10
• @andibarg made their first contribution in #11

Full Changelog: v0.6.1...v0.6.2

v0.6.2-alpha1

Pre-release of ZOSPy version 0.6.2, mainly intended to test the release action.

What's Changed

• V0.6.1 by @LucVV in #5
• Updated example to be in line with v0.6.1 by @LucVV in #6
• Update warning about Python.NET version by @crnh in #10
• V0.6.2 by @LucVV in #11
• Add a Publish to TestPyPI action by @crnh in #12

New Contributors

• @crnh made their first contribution in #10

Full Changelog: v0.6.1...v0.6.2-alpha0

v0.6.1

Temporary recommended version of pythonnet (2.5.2) as the newer versions break functionality