Non-sequential Component Editor (NCE) Functions

The functions within this category are related operations in non-sequential mode, largely around configuration of NCE objects and ray tracing.

skZemax.skZemax_subfunctions._NCE_functions.NCE_AddNewObject(self) → ZOSAPI_Editors_NCE_INCERow

Adds a new NCE Object as the last object in the system.

Returns:

The newly made NCE object

Return type:

ZOSAPI_Editors_NCE_INCERow

skZemax.skZemax_subfunctions._NCE_functions.NCE_ChangeObjectType(self, ObjectNCE: int | ZOSAPI_Editors_NCE_INCERow, object_type: str) → None

Changes the type of the NCE Object

Parameters:

• ObjectNCE (Union[int, ZOSAPI_Editors_NCE_INCERow]) – The NCE object to change. Can be given as an index or an NCE object.

• object_type (str) – The changed NCE object

skZemax.skZemax_subfunctions._NCE_functions.NCE_ColocateObject(self, in_objToChange: int | ZOSAPI_Editors_NCE_INCERow, in_ReferenceObj: int | ZOSAPI_Editors_NCE_INCERow, use_reference_flag: bool = False) → None

Co-locates in_objToChange to in_ReferenceObj with or without a reference flag (depending on use_reference_flag).

Parameters:

• in_objToChange (Union[int, ZOSAPI_Editors_NCE_INCERow]) – A NCE object to co-locate. Can be given as an index or an NCE object.

• in_ReferenceObj (Union[int, ZOSAPI_Editors_NCE_INCERow]) – The reference NCE object. Can be given as an index or an NCE object.

• use_reference_flag (bool, optional) – If true the co-location will be done through the “Ref Object” property of the NCE column data, else rotation and position matrices is constructed and applied to do the co-location , defaults to False

skZemax.skZemax_subfunctions._NCE_functions.NCE_GetAllColumnDataOfObject(self, ObjectNCE: int | ZOSAPI_Editors_NCE_INCERow) → dict

Gets all column data of a Non-Sequential object and returns it as a dict. This was made for robustness, as direct reference calls on NCE objects (i.e. object.property) do not work correctly. So, a python dictionary interface was developed in skZemax which utilizes lower level function calls to get the same functionality.

See NCE_SetAllColumnDataOfObjectFromDict() for compliment.

Parameters:

ObjectNCE (Union[int, ZOSAPI_Editors_NCE_INCERow]) – The NCE object to change. Can be given as an index or an NCE object.

Returns:

dict of the NCE object’s column data.

Return type:

dict

skZemax.skZemax_subfunctions._NCE_functions.NCE_GetNumberOfObjects(self) → int

Get the number of non-sequential component objects.

Returns:

The number of NCE objects.

Return type:

int

skZemax.skZemax_subfunctions._NCE_functions.NCE_GetObject(self, ObjectNum: int) → ZOSAPI_Editors_NCE_INCERow

Gets the non-sequential component object at the provided index.

Parameters:

object_num (int) – The index of the NCE object to get.

Returns:

The NCE object.

Return type:

ZOSAPI_Editors_NCE_INCERow

skZemax.skZemax_subfunctions._NCE_functions.NCE_GetObjectColumnEnum(self, in_str: str, ObjectNCE: None | int | ZOSAPI_Editors_NCE_INCERow = None) → ZOSAPI_Editors_NCE_ObjectColumn

Returns the underlying enumerator of a NCE column object matching the input string.

If ObjectNCE is None, then assuming only searching for a base property or one named by ‘par#’. If ObjectNCE is not None, will search for the property in the surface by name and return the right enum.

Parameters:

• in_str (str) – The name identifying the object column.

• ObjectNCE (Union[None, int, ZOSAPI_Editors_NCE_INCERow], optional) – The NCE object. Can be index, the NCE object, or None. If None will assume in_str is one of: ‘Comment’, ‘RefObject’, ‘InsideOf’, ‘XPosition’, ‘YPosition’, ‘ZPosition’, ‘TiltX, ‘TiltY’, ‘TiltZ’, ‘Material’, or ‘Par#’ (# = 1 to 90). If not None will search for the property in the surface by name and return the right enum, defaults to None

Returns:

The column enumerator (attribute) specified by the given name.

Return type:

ZOSAPI_Editors_NCE_ObjectColumn

skZemax.skZemax_subfunctions._NCE_functions.NCE_GetObjectRotationAndPositionMatrices(self, in_Object: int | ZOSAPI_Editors_NCE_INCERow) → tuple[ndarray, ndarray]

Looks up an NCE object and returns the object’s rotation matrix and position information This can be used to co-locate objects without using reference object flags. See NCE_ColocateObject() and example 08.

Parameters:

in_Object (Union[int, ZOSAPI_Editors_NCE_INCERow]) – The NCE object to change. Can be given as an index or an NCE object.

Returns:

tuple of object’s ([x, y, z], R matrix) as np.ndarrays

Return type:

tuple[np.ndarray, np.ndarray]

skZemax.skZemax_subfunctions._NCE_functions.NCE_InsertNewObject(self, insertObject: int | ZOSAPI_Editors_NCE_INCERow) → ZOSAPI_Editors_NCE_INCERow

Inserts a new non-sequential component object at the given location of the system.

Parameters:

insertObject (Union[int, ZOSAPI_Editors_NCE_INCERow]) – The location to insert the new NCE object. Specified by either an index or a NCE object.

Returns:

The newly inserted NCE object

Return type:

ZOSAPI_Editors_NCE_INCERow

skZemax.skZemax_subfunctions._NCE_functions.NCE_ReadZDRFile(self, in_ZDR_abs_path: str, should_print: bool = False) → dict

A NCE utility function which reads a ZDR file and stores it as a dictionary.

Parameters:

• in_ZDR_abs_path (str) – Path to ZDR file

• should_print (bool, optional) – If True will print the result to console, defaults to False

Returns:

dict of the ray trace structured as dict[Ray_#][Segment_#] with other relevant info in each section.

Return type:

dict

skZemax.skZemax_subfunctions._NCE_functions.NCE_RemoveObject(self, delObject: int | ZOSAPI_Editors_NCE_INCERow) → None

Removes the non-sequential component object from the system.

Parameters:

delObject (Union[int, ZOSAPI_Editors_NCE_INCERow]) – The location of the NCE object to delete. Specified by either an index or a NCE object.

skZemax.skZemax_subfunctions._NCE_functions.NCE_RunRayTrace(self, SplitNSCRays: bool = True, ScatterNSCRays: bool = False, UsePolarization: bool = True, IgnoreErrors: bool = True, SaveRays: bool = False, SavePaths: bool = False, NumberOfCores: int | None = None, SaveFileName: str = 'NCERayTrace.ZDR') → None

Runs a non-sequential ray trace. See the Zemax help pdf section 4.2.1. Ray Trace for more information. The underlying ZOS-API does not appear to support saving a file to a custom location. Any saved files will always seem to be put in the same folder as the zmx file.

Parameters:

• SplitNSCRays (bool, optional) – If checked, rays from NSC sources will be statistically split at ray-surface intercepts. Rays entering from the entry port are not affected by this setting, defaults to True

• ScatterNSCRays (bool, optional) – If checked, rays from NSC sources will be statistically scattered at ray-surface intercepts. Rays entering from the entry port are not affected by this setting, defaults to False

• UsePolarization (bool, optional) – If checked, polarization is considered (see pdf document section 2.1.1.5. Polarization (System Explorer)), defaults to True

• IgnoreErrors (bool, optional) – If checked, errors generated by ray tracing are ignored, and any errors that occur will not terminate the ray trace. This should be turned on with caution, since errors may indicate a serious flaw in the system being traced. However, some perfectly good systems occasionally have a few rays fail because of finite computer precision or other minor problems. If the “lost energy (errors)” given at the end of the ray trace is small relative to the total power of all sources defined, then the few rays which trigger errors can be safely ignored. See “Lost energy”, defaults to True

• SaveRays (bool, optional) – If checked, ray data will be saved to the file name specified. The file name only should be provided with the proper extension (ZRD, DAT, SDF or TM25RAY) and no folder name, defaults to False

• SavePaths (bool, optional) – If checked, ray data will be saved as a PAF file to the file name specified. A PAF file contains the same information, and the path data is saved and loaded more quickly from a PAF file from a ZRD. Currently, a PAF file can be used in the Path Analysis tool. The PAF generated ignores the Filter option during the ray trace, defaults to False

• NumberOfCores (int, optional) – The number of computer cores to use in the ray trace. None will use all available cores, defaults to None

skZemax.skZemax_subfunctions._NCE_functions.NCE_SetAllColumnDataOfObjectFromDict(self, ObjectNCE: int | ZOSAPI_Editors_NCE_INCERow, ObjectNCE_dict: dict) → None

Sets all column data of a Non-Sequential object from a dict. This was made for robustness, as direct reference calls on NCE objects (i.e. object.property) do not work correctly. So, a python dictionary interface was developed in skZemax which utilizes lower level function calls to get the same functionality.

See NCE_GetAllColumnDataOfObject() for compliment.

Parameters:

• ObjectNCE (Union[int, ZOSAPI_Editors_NCE_INCERow]) – The NCE object to change. Can be given as an index or an NCE object.

• ObjectNCE_dict (dict) – dict of column data and values. Expected to be the same format as the output of invoking NCE_GetAllColumnDataOfObject() on the same object.