Skip to content

v1.2.0
Compare
Choose a tag to compare
@crnh crnh released this 19 Jan 12:32
· 40 commits to main since this release
v1.2.0
b78a44c
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Learn about vigilant mode.

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 communication1.
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 anymore1.
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.02

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

  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

  2. Which we plan to release this year. ↩

Contributors

noahrbn, crnh, and 2 other contributors
Assets 4
Loading