Wrapper for NSCRayTrace()

[JoachimBT]

In one of the examples here, you already use the NSCRayTrace()-Tool:

ZOSPy/examples/Retinal illumination in pseudophakic eyes with and without Negative Dysphotopsia/retinal_illumination.ipynb

Line 178 in 398cbb6

" RayTrace = oss.Tools.OpenNSCRayTrace()\n",

From a different repository, I was using this function to wrap RayTracing into a single function:
https://github.com/clazzoni/zemaxzcriptz/blob/master/zosPython.py#L151

I thought it would be cool to have everything in this library here. I rewrote it a bit, instead of including a try-catch routine for errors and to make sure the NSCRayTrace-Tool is properly closed afterwards, I am using a context manager and adding type hints:

from __future__ import annotations # needed for the type hints
from zospy.api import _ZOSAPI
from contextlib import contextmanager
from typing import Generator

@contextmanager
def ray_trace_window(tool: _ZOSAPI.Tools.IOpticalSystemTools) -> Generator[_ZOSAPI.Tools.RayTrace.INSCRayTrace, None, None]:
    """
        Context manager for the ray trace window. If used, you can be sure that the window is closed after usage,
        even if you experience an error.
    """
    NSCRayTrace = tool.OpenNSCRayTrace()
    try:
        yield NSCRayTrace
    finally:
        NSCRayTrace.Close()


def z_nsc_raytrace(tool: _ZOSAPI.Tools.IOpticalSystemTools, SplitNSCRays:bool=False, ScatterNSCRays:bool=False, UsePolarization:bool=False, IgnoreErrors:bool=False,
                   SaveRays:bool=False, SaveRaysFile:str='rays01.ZRD', Filter:str='', ClearDetectors:bool=True, NumberOfCores:int=23, PrintStatus:bool=False):

    with ray_trace_window(tool) as raytrace:

        if SplitNSCRays:
            UsePolarization = True
        raytrace.NumberOfCores = NumberOfCores
        raytrace.UsePolarization = UsePolarization
        raytrace.IgnoreErrors = IgnoreErrors
        raytrace.SplitNSCRays = SplitNSCRays
        raytrace.ScatterNSCRays = ScatterNSCRays

        raytrace.SaveRays = SaveRays
        raytrace.SaveRaysFile = SaveRaysFile
        raytrace.Filter = Filter

        if ClearDetectors:
            raytrace.ClearDetectors(0)

        raytrace.Run()
        last_value = -1

        if PrintStatus:
            while raytrace.IsRunning:
                current_value = raytrace.Progress
                if current_value % 2 == 0:
                    if last_value != current_value:
                        last_value = current_value
                        print('\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\bRaytracing: ', current_value, '%', end="")

        raytrace.WaitForCompletion()
        if PrintStatus: print(
            f'   Dead rays {raytrace.DeadRayErrors:.3e}  DeadRayThreshold: {raytrace.DeadRayThreshold:.3e}')
        if SaveRays: print(f'Saving rays to: {SaveRaysFile}')
        return {'is_valid': raytrace.IsValid,
                'DeadRayErrors': raytrace.DeadRayErrors,
                'DeadRayThreshold': raytrace.DeadRayThreshold}

I integrated it in a way, that I can load these small helper functions on top of the ZOSPy library.

If I wanted to add this officially, I would not know where to put this, zospy/analysis, or rather into zospy/functions/nce.py, or somewhere else?

I have some other functions I use in non-sequential mode, especially to read and analyze detector data.

What do you think?

[crnh]

Hi @JoachimBT,

Thanks for considering to contribute your solutions to ZOSPy! We are currently quite busy because we want to release ZOSPy v2 soon. We'll come back to you after the release!

[crnh]

Hi @JoachimBT,

It took a while before I had time to respond. Thanks for your patience, and thanks again for your proposal! Using a context manager looks like a proper way to manage OpticStudio tools.

Regarding the location where your tool implementation could be added: ZOSPy currently only wraps the system layout export tools. These are available through zospy.analyses.systemviewers. However, these tools are an exception, because they expose functions that are otherwise available as analyses in OpticStudio. For the NSCRayTrace tool, this may not be the best location, because ZOSPy's analysis abstractions don't really fit this (and many other tools). Although the OpticStudio interface does not distinguish between analyses and tools, it may still be better to create a new zospy.tools submodule for the NSCRayTrace tool (and possibly other tools in the future).

@LucVV I'd like to hear your opinion about this. Do you think this can be contributed as an analysis, is a new tools submodule the way to go, or do you see a different solution?