Recent Releases of ZOSPy
ZOSPy - v2.1.1
What's Changed
- Support ZOSPy constants for Huygens PSF by @crnh in https://github.com/MREYE-LUMC/ZOSPy/pull/158
- Add Huygens PSF with Strehl ratio analysis by @crnh in https://github.com/MREYE-LUMC/ZOSPy/pull/159
Full Changelog: https://github.com/MREYE-LUMC/ZOSPy/compare/v2.1.0...v2.1.1
Scientific Software - Peer-reviewed
- Python
Published by crnh 6 months ago
ZOSPy - v2.1.0
What's Changed
- Add FFT PSF analysis by @crnh in https://github.com/MREYE-LUMC/ZOSPy/pull/146
- Use ZOS.getinstance in copysystem by @crnh in https://github.com/MREYE-LUMC/ZOSPy/pull/149
- Add FFT MTF analysis by @crnh in https://github.com/MREYE-LUMC/ZOSPy/pull/150
Full Changelog: https://github.com/MREYE-LUMC/ZOSPy/compare/v2.0.2...v2.1.0
Scientific Software - Peer-reviewed
- Python
Published by crnh 7 months ago
ZOSPy - v2.0.0
A new major release: ZOSPy v2!
This release contains a lot of changes under the hood, making ZOSPy more reliable and easier to extend. For example, it is now easier to develop new analyses. This release also removes a few deprecated functions. As a result, some of the changes are not backwards compatible with older ZOSPy versions.
Backwards-incompatible changes
- Many functions use optional boolean arguments to enable or disable certain features. For example,
new_analysishas asettings_firstargument that allows to change the analysis settings before running them. These arguments are now keyword-only.new_analysis(<AnalysisType>, True)does not work anymore; usenew_analysis(<AnalysisType>, settings_first=True)instead. Here's a list of the impacted functions:zospy.analyses.new.new_analysis:settings_firstis now a keyword-only argument.zospy.api.apisupport.load_zosapi_nethelper:preloadis now a keyword-only argument.zospy.api.apisupport.load_zosapi:preloadis now a keyword-only argument.zospy.functions.lde.find_surface_by_comment:case_sensitiveis now a keyword-only argument.zospy.functions.nce.find_object_by_comment:case_sensitiveis now a keyword-only argument.zospy.utils.flatten_dict:keep_unflattenedis now a keyword-only argument.zospy.zpcore.OpticStudioSystem.load:saveifneededis now a keyword-only argument.zospy.zpcore.OpticStudioSystem.new:saveifneededis now a keyword-only argument.zospy.zpcore.OpticStudioSystem.close:saveifneededis now a keyword-only argument.zospy.zpcore.ZOS.__init__: all parameters are now keyword-only arguments.
zospy.zpcore.ZOS.wakeup,zospy.zpcore.ZOS.connect_as_extension,zospy.zpcore.ZOS.create_new_applicationandzospy.zpcore.ZOS.connect_as_standalonehave been removed. For more information, see New connection methodszospy.functions.nce.get_object_datahas been removed because it implements a conversion that is now done automatically byzospy.api.codecs.OpticStudioInterfaceEncoder.- The API for analyses has changed. For more information, see New analysis interface
New connection methods
A new connection method ZOS.connect has been introduced in ZOSPy 1.2.0.
All other connection methods (connect_as_extension, create_new_application and connect_as_standalone) have been removed.
New analysis interface
The analysis interface has been rewritten and is now object oriented. In general, an analysis that was previously run this way:
python
zp.analysis.category.some_analysis(oss, parameter_1=1, parameter_2="123")
now has to be run this way:
python
zp.analysis.category.SomeAnalysis(parameter_1=1, parameter_2="123").run(oss)
For more information about the new interface, see the documentation. The old interface contained a lot of duplicate code, which has been solved in the new interface. As a result, developing new analyses is a lot easier now. Furthermore, the new interface provides a unified way to parse analysis text output. Parsers are written in lark, and because ZOSPy provides predefined parsers for common constructs in the OpticStudio output, they can be quite concise. For example, this is the parser for the cardinal points analysis:
```lark start: "\ufeff"? NEWLINE? text _field+ text+ cardinalpoints
cardinalpoints: cardinalpointsheader _NEWLINE cardinalpoint+ !cardinalpointsheader: ("Object Space" | "Image Space")~2 -> stringlist cardinalpoint: /[\w -]+\w/ ":" _number _number _NEWLINE
%import .zospy (field, _number, text, STRING) %import common.NEWLINE -> _NEWLINE %import common (LETTER, WORD, WSINLINE) %ignore WS_INLINE ```
Improved documentation
We have largely rewritten and extended the documentation. Check it out at zospy.readthedocs.io!
Improved development workflow
ZOSPy now uses Hatch for project management. Hatch provides a unified interface for all development-related tasks, such as testing, formatting, building documentation, generating test reference data etc. Furthermore, it can manage Python interpreters, so unit tests can be run for all Python versions without having to install all interpreters manually. Read more in our contributing guidelines.
Contributors
- @jwmbeenakker @lucVV @crnh
- This release was in part funded by the Netherlands Organisation for Scientific Research (NWO) through the OPENOPTICS project.
Scientific Software - Peer-reviewed
- Python
Published by crnh 10 months ago
ZOSPy - v2.0.0b0
ZOSPy v2 - beta 0
This is the first beta release for ZOSPy v2, featuring a completely rewritten analysis framework and a refactored core. Analysis data parsing is now much more robust and has been standardized, which should considerably simplify the development of analysis wrappers. Please let us know if you experience any issues with this release.
Scientific Software - Peer-reviewed
- Python
Published by crnh 10 months ago
ZOSPy - 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
- Helper functions to generate specific parameter dictionaries for these analyses:
- 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_3dandzospy.analyses.systemviewers.cross_section(#80).
Changed
- Updated
zospy.functions.lde.surface_change_typeto also support surfaces that require the specification of a file to load. (!61) - Added support for dictionary parameters in both
zospy.testsandzospy.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.
Scientific Software - Peer-reviewed
- Python
Published by crnh about 1 year ago
ZOSPy - 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 forzospy.analyses.base.Analysis.dirnow 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.
Scientific Software - Peer-reviewed
- Python
Published by crnh almost 2 years ago
ZOSPy - 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[^1]. 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[^1].
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:
```python abcdsurface = oss.LDE.InsertNewSurfaceAt(3) zp.functions.lde.surfacechangetype(abcdsurface, zp.constants.Editors.LDE.SurfaceType.ABCD)
Change the "A" value of abcd_surface for the x direction
abcdsurface.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:
```python
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:
```python 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: ```python 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:
```python 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[^2]
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:
python
oss.save_as("optical_system.zmx")
or load an optical system using a relative path:
python
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.
Scientific Software - Peer-reviewed
- Python
Published by crnh almost 2 years ago
ZOSPy - 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
Scientific Software - Peer-reviewed
- Python
Published by crnh about 2 years ago
ZOSPy - v1.1.1
Added
ZOS.connect_as_standaloneas alias forZOS.create_new_application(#26)- New parameter
return_primary_systemforZOS.connect_as_extensionandZOS.create_new_application. These methods return the primary optical system if this parameter isTrue. If the license is not valid for the ZOS-API, aConnectionRefusedErroris raised (#26) zospy.functions.nce.get_object_datato get the data of an NCE object (#30)
Fixed
- Erroneous parsing of analyses results when textfile encoding was not set to
Unicodeby implementingzospy.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.configare determined for more clarity (!39) - Update the error message in
zospy.ZOSto explain why only a single instance ofZOSis allowed (#24) - Load ZOS-API DLLs in
ZOS.__init__(#26)
Deprecated
- Separate calls to
ZOS.wakeupare now redundant. This method will be removed in a later release (#26)
Scientific Software - Peer-reviewed
- Python
Published by crnh over 2 years ago
ZOSPy - 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)
versionproperty for theZOSclass (LUMCgit !21)zospy.utils.pyutils.atox,zospy.utils.pyutils.xtoaand_config.THOUSANDS_SEPARATORfor 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_commentandzospy.functions.nce.find_object_by_commentto 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_typeandzospy.functions.nce.object_change_type(LUMCgit !31)
Changed
- Converted some examples into Jupyter notebooks
- Renamed
_config.DECIMALto_config.DECIMAL_POINT(LUMCgit !26) - Use
.zmxfiles instead of.zosfiles 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!
Scientific Software - Peer-reviewed
- Python
Published by crnh over 2 years ago
ZOSPy - 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:
```python import zospy as zp
...
draw3d = zp.analyses.newanalysis(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.
```python
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:
```python 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:
```python
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.
```python
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. <!--TODO add link-->
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+.
Scientific Software - Peer-reviewed
- Python
Published by crnh over 2 years ago
ZOSPy - v0.6.2
What's Changed
- Added support for additional analyses:
- Rays and spots, available via
zospy.analyses.raysandspots: single_ray_trace()ray_fan()
- Rays and spots, available via
- 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 https://github.com/MREYE-LUMC/ZOSPy/pull/10
- @andibarg made their first contribution in https://github.com/MREYE-LUMC/ZOSPy/pull/11
Full Changelog: https://github.com/MREYE-LUMC/ZOSPy/compare/v0.6.1...v0.6.2
Scientific Software - Peer-reviewed
- Python
Published by LucVV almost 3 years ago
ZOSPy - 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 https://github.com/MREYE-LUMC/ZOSPy/pull/5
- Updated example to be in line with v0.6.1 by @LucVV in https://github.com/MREYE-LUMC/ZOSPy/pull/6
- Update warning about Python.NET version by @crnh in https://github.com/MREYE-LUMC/ZOSPy/pull/10
- V0.6.2 by @LucVV in https://github.com/MREYE-LUMC/ZOSPy/pull/11
- Add a Publish to TestPyPI action by @crnh in https://github.com/MREYE-LUMC/ZOSPy/pull/12
New Contributors
- @crnh made their first contribution in https://github.com/MREYE-LUMC/ZOSPy/pull/10
Full Changelog: https://github.com/MREYE-LUMC/ZOSPy/compare/v0.6.1...v0.6.2-alpha0
Scientific Software - Peer-reviewed
- Python
Published by crnh almost 3 years ago
ZOSPy - v0.6.0
Most important changes
- Implemented dynamical loading of all OpticStudio contstants and makes them available through
zospy.constants. This should be more robust than hardcoding them, especially for use with different OpticStudio versions - Moved all analyses to
zospy.analysesto prevent namespace cluttering - Added
zospy.analyses.surface.curvature()andzospy.analyses.reports.surface_data()analyses - Minor other functionality changes
Scientific Software - Peer-reviewed
- Python
Published by LucVV about 3 years ago