Custom object conversion between the ZOS-API and ZOSPy#
ZOSPy connects to the ZOS-API using Python.NET.
Python.NET converts .NET objects to Python objects and vice versa, and it allows to customize this conversion
behaviour using codecs.
ZOSPy defines these codecs in zospy.api.codecs
and loads them before loading the ZOS-API libraries in
zospy.api.apisupport
.
OpticStudioInterfaceEncoder
#
This encoder automatically downcasts generic interfaces to specific implementations. The ZOS-API often defines a generic interface which is implemented by many other, more specific interfaces.
Example
The ZOSAPI.Analysis.Settings.IAS_
interface specifies the properties and methods that should be
implemented by the settings object of all analyses.
Many analyses have settings that are specific to that analysis, and these settings are specified by a separate
interface.
For example, the Huygens PSF settings are specified by the ZOSAPI.Analysis.Settings.Psf.IAS_HuygensPsf
interface,
which also inherits from ZOSAPI.Analysis.Settings.IAS_
.
Starting with Python.NET 3, this leads to problems when the API returns objects implementing the generic interface,
but you need to access a method or property of the specific interface.
The solution to this problem is “downcasting” the generic interface to the specific interface.
Python.NET uses the __implementation__
attribute for this.
More information can be found on the OpticStudio community forum.
Example
Warning
This example does not work out of the box, because
zospy.api.codecs.OpticStudioInterfaceEncoder
solves this problem.
You need to modify ZOSPy’s source code to get this example working.
If you create a Huygens PSF analysis using the “raw” ZOS-API, you cannot access its analysis specific settings:
import zospy as zp
zos = zp.ZOS()
oss = zos.connect(mode="standalone")
huygens_psf = oss.Analyses.New_Analysis_SettingsFirst(zp.constants.Analysis.AnalysisIDM.HuygensPsf)
huygens_psf_settings = huygens_psf.GetSettings()
print(huygens_psf_settings.Normalize) # AttributeError: 'IAS_' object has no attribute 'Normalize'
By downcasting using the __implementation__
attribute, the Huygens PSF settings can be accessed:
print(huygens_psf_settings.__implementation__.Normalize) # False
Manually accessing __implementation__
is unintuitive, and decreases code readability.
The OpticStudioInterfaceEncoder
solves this problem by automatically casting from the interface to the implementation
class.
Interfaces that are automatically downcast#
Interfaces need to be registered before they will be converted by OpticStudioInterfaceEncoder
.
These interfaces are downcast by default:
ZOSAPI.Analysis.Settings.IAS_
Access via
zp.analyses.new_analysis(<analysis type>).Settings
Interface for analysis settings. PLEASE NOTE:
zospy.analyses
already performed downcasting before codecs were implemented.
ZOSAPI.Editors.LDE.ISurface
oss.LDE.GetSurfaceAt(<index>).SurfaceData
Surface data, which provides access to surface-specific settings (e.g. tilts and decenters of a Coordinate Break)
ZOSAPI.Editors.LDE.ISurfaceApertureType
Access via
oss.LDE.GetSurfaceAt(<index>).ApertureData.CurrentTypeSettings
Interface for surface aperture settings
ZOSAPI.Editors.LDE.ISurfaceScatteringType
Access via
oss.LDE.GetSurfaceAt(<index>).ScatteringData.CurrentTypeSettings
Interface for surface scattering settings
ZOSAPI.Editors.NCE.IObject
oss.NCE.GetObjectAt(<index>).ObjectData
Object data, which provides access to object-specific settings
ZOSAPI.Tools.ISystemTool
oss.Tools.CurrentTool
Interface for tool settings
Interfaces that are not automatically downcast#
The interfaces listed below provide “convenience properties” to access the specific interfaces.
They are therefore not handled by OpticStudioInterfaceEncoder
.
Consult the OpticStudio documentation for more information.
ZOSAPI.Editors.ISolveData
ZOSAPI.Editors.NCE.ISourceColorSettings
ZOSAPI.Editors.NCE.IObjectScatteringSettings
ZOSAPI.Editors.NCE.IVolumePhysicsModelSettings
ZOSAPI.Editors.NCE.IIndexModelSettings
Example
The ‘Pickup’ solver, which implements the ZOSAPI.Editors.ISolveSurfacePickup
interface, can be accessed in this way:
# ThicknessCell is only an example, you can use any cell that supports the Pickup solver
oss.LDE.GetSurfaceAt(<index>).ThicknessCell.GetSolveData()._S_SurfacePickup
Registering additional interfaces for automatic downcasting#
You can register additional interfaces using
zospy.api.codecs.OpticStudioInterfaceEncoder.register_interfaces
.
If you think you found an interface that should be converted by default, please file an issue or create a Pull Request.