Skip to main content

ZOS-API

Find and share your best practices for using the ZOS-API here!

  • 356 Topics
  • 1,112 Replies
356 Topics
Allie
Zemax Staff
AllieZemax Staff
posted in ZOS-API
Single Ray Trace in the ZOS-API

In the last few weeks, I have received questions regarding how we can use the ZOS-API to pull single ray trace information. For convenience, I will post my answers here in a single post. I pulled together three different methods for extracting single ray trace data. Below I will list the methods with sample code in Python and Mathematica. I’m happy to provide samples in other languages if needed! If you have other methods you use for this kind of analysis, feel free to add them as a reply! Method 1 - Use the Single Ray Trace analysisThis method can be used to pull the results of the Single Ray Trace analysis window.  The benefit of this method is that the results are pulled for all surfaces at once. The drawback of this method is that the data is provided in text form. The output is a TXT file which must be parsed back into the program you are using. This is discussed in a bit more detail here: How to set RayInfo.Vignetted in ZOS-API_Python Python########### Define the constants across

18562
S
Matt H
Matt HSingle Emitter
asked in ZOS-API
Group Selecting and Setting Specific Cells

Hi everyone, is there a way to select several cells of interest at once using ZOSAPI? Commands like GetObjectAt() and GetCellAt() allow you to select a certain object and certain cell, but - for instance - I want to select the Ref Object column in the NCE specifically for rows 2-5 and set a common value for them. Is there a command to select these cells at once (without having to loop through each object and set them individually) and then set a common value?

201
David.Nguyen
Luminary
PhWest
PhWestSingle Emitter
asked in ZOS-API
Error using ZOS-API in Python

My codes (that were working with the 2024 version) do not work anymore with the 2025 release.This is the error I get:Unhandled Exception: System.IO.FileLoadException: Could not load file or assembly 'ZemaxEngine.dll' or one of its dependencies. A dynamic link library (DLL) initialization routine failed. (Exception from HRESULT: 0x8007045A).

13111
joachim
I
Iari.MarinoInfrared
asked in ZOS-API
Abbe number of glass for thermal infrared

Hello,I have a question about a glass for the thermal infrared region, specifically IRG26 glass, present in the SCHOTT_IRG catalog.The Tolerance Wizard is not able to insert the tolerance on the Abbe number of this glass. Why? If the Abbe number is not clearly defined, can we trust the raytrace and therefore the evaluation of the chromatic aberrations?Thanks! 

251
Sean Turner
Ultraviolet
Alex.Tripsas
Alex.TripsasVisible
asked in ZOS-API
How to get a surface from one file and have it be the same surface in a different file Python PyZOS

Hi all, I’ve been modifying .zmx files using Python for a few years now and have been using my own module and PyZOS for a majority of it now.  However, my current project has a bit of a road block I’m not sure how to get around. What I would like to do is take a surface from a file I’ve already created and have it be the exact same surface in a different file.  I could have the code insert the surface, but if possible I’d like to avoid inserting and deleting surfaces as it may effect other parameters in the system (i.e. Merit Functions operands and whatnot).What I’m hoping to code is something like the followingimport zospy as zp zos = zp.ZOS()oss = zos.connect()oss.load(‘file1’)oss2 = zos.create_new_system()oss2.load(‘file2’) first_surface_file1 = oss.LDE.GetSurfaceAt(1)first_surface_file2 = oss2.LDE.GetSurfaceAt(1) #Modify somehow first_surface_file1 == first_surface_file2 #would like to be True I was thinking of somehow looping through the surface params but that’s proving difficult

845
MichaelH
Ansys Staff
mocquin
mocquinVisible
asked in ZOS-API
Zernike analysis setting name confusing

In the IAS_ZernikeStandardCoefficients settings, there is a setting called :      ReferenceOBDToVertex  (not sure what OBD means)while in the GUI it is called:     Reference OPD to vertexwhich makes more sense 

140
mocquin
K
KarenMonochrome
posted in ZOS-API
Retrieving Vignetting Data from Vignetting Analysis via ZOS.API with Python

Dear all, in progress of fully automating my data export  for my customized documentation, I am trying to access the data generated by the Zemax analysis windows by a standalone API application in python. While this works for most of the analysis, I am having trouble to get data from the vignetting window for further processing by using the GetResults() function. There is not data retrieved. Debugging shows, that there is indeed no data listed in the respective item. I double checked by exporting the data to a text file - this is also empty with respect to data.   My Code therefore  (simple example based on the available python api example 1) works as follows: vig = TheSystem.Analyses.New_Analysis(ZOSAPI.Analysis.AnalysisIDM.VignettingDiagramSettings) vig.WaitForCompletion() vig.ToFile(sampleDir + '\\API\\Python\\TextResults.txt') However, when I save the lens file, and reopen with a Zemax Instance, the vignetting window is displayed correctly and the

1812
mocquin
L
Luca.OggioniMonochrome
asked in ZOS-API
Error using ZOS-API in Matlab

My codes (that were working with the 2024 version) do not work anymore with the 2025 release.this is the error I get in the function “InitConnection()”:Message: Could not load file or assembly 'ZemaxEngine.dll' or one of its dependencies. The dynamic link library (DLL) initialization routine failed. (Exception from HRESULT: 0x8007045A)Source: mscorlibHelpLink: None

2869
bostanem
KBL
KBLSingle Emitter
asked in ZOS-API
ZOS-API, Python Image simulation. No output

Hey, I’m very naïve to Zemax and ZOS-API. I just tried to find the setting and run the code, but I couldn’t see the results from the image simulation.I used the standalone application and here is my code.     # load local variables    ZOSAPI = zos.ZOSAPI    TheApplication = zos.TheApplication    TheSystem = zos.TheSystem        # Insert Code Here    file = "C:/2021/Zemax_Image_Simulation/test.zmx"    cfg = "C:/2021/Zemax_Image_Simulation/test.CFG"    TheSystem.LoadFile(file, False)    TheImageSimulation = TheSystem.Analyses.New_ImageSimulation()    analysisSettings = TheImageSimulation.GetSettings()        analysisSettings.ModifySettings(cfg, 'ISM_INPUTFILE', "Text_100p_3x3_2_g1196x1279_dist.png")    analysisSettings.ModifySettings(cfg, 'ISM_FIELDHEIGHT', '15')    analysisSettings.ModifySettings(cfg, 'ISM_FLIPIMAGE', '3')    analysisSettings.ModifySettings(cfg, 'ISM_OUTPUTFILE', 'Test1.png')        analysisSettings.LoadFrom(cfg)    a = TheImageSimulation.ApplyAndWaitForCompletion()   

1472
L
B
Begad.ElmelligyInfrared
asked in ZOS-API
ZOSAPI Python LSP

Hi, I started working with ZOSAPI in Python. I am aware that since I am using clr.AddReference(<Module>) that means that they are dynamically being imported but is there a way to achieve autocomplete and error checking?

511
B
L
Luc.van VughtVisible
asked in ZOS-API
Incorrect datagrid.MinY for Geometric Image Analysis

We recently implemented the Geometric Image Analysis in ZOSPy 1.30. While doing so, we noticed that IAR_DataGrid.MinY does not return the lower bound of the y-axis for the output (at least when compared to the output in OpticStudio itself). It seems to be returning either the upper bound or the abolute value. E.g., when the analysis is centered at (0,0), the x- an y-axes in OpticStudio start at -25 while the API returns -25 for MinX and 25 for MinY.  Could you elaborate on what MinY (and to an extend MinX) correspond to. So far, we thought the datagrids and their axes follow the normal matrix conventions, which was the case for all analyses we implemented and used. Is this not the case for Geometric Image Analysis, or is there an error in the API?

20511
L
Jeff.Wilde
Luminary
Jeff.WildeLuminary
asked in ZOS-API
ZOS-API Initialization Error in Matlab

It appears that there is a known ZOS-API initialization error when using OpticStudio 2025 R1.  Here’s what is stated in the 2025 R1 release notes: I’m currently using OpticStudio 2025 R1.01 and encountering this problem with Matlab R2021a (which previously worked fine with OpticStudio versions prior to 2025).Does anyone know if updating to the latest Matlab release will solve the problem?  If not, I wonder how/when this bug will be resolved?Thanks,Jeff

1013
Jeff.Wilde
Luminary
L
Luc.van VughtVisible
asked in ZOS-API
What is the use of ZOSAPI.AnalysisSettings.IAS_Surface.UseObjectiveSurface()

The usage of ZOSAPI.AnalysisSettings.IAS_Surface.UseObjectiveSurface() is not clearly documented. The only place where is appears is in the ZOSAPI introduction under “Changing Settings” to explain that an errormessage can be returned if it did not work. In contrast to ZOSAPI.AnalysisSettings.IAS_Surface.UseImageSurface(), which selects the image surface whenever available, it is unclear what UseObjectiveSurface() does. The only place where I have actually managed to get it to work is for the Start Surface in the PhysicalOpticsPropagation analysis, where it selects the Entrance Pupil. Is the intended use selecting surfaces that are not an actual surface within the model (such as the entrance pupil)?

372
L
L
Luc.van VughtVisible
asked in ZOS-API
Geometric Image Analysis with negative Image Size

I am implementing a fix for the incorrect MinY of the Geometric Image Analysis in Python, as discussed in this post. While doing so, I noticed an odd behavior. It is allowed to specify the Image Size as negative for the Geometric Image Analysis, but this causes problems with the resulting output. With the example Double Gauss 28 degrees field, I can create the following analyses using the API with slightly different settings:API output for 4 slightly different analyses Showing that the extent of the axis with a negative image size and the number of pixels set to 100 will always equal 100. First I thought this was an API problem, but this is the same output in OpticStudio:The same analyses in OpticStudio.  Field widths: Analysis 1: 50, Analysis 2: -50, Analysis 3: 100, analysis 4: -100 Note that the image width of Analysis 2 is 100 millimeters while it should be (-)50 millimeters:Settings for analysis 2 Increasing the number of pixels to 200 increases the field width of the analyses wit

310
L
clo
cloMonochrome
asked in ZOS-API
How to ignore Object in API ?

Hello to all,I read the topic about : “how to ignore Surface in API”. I tried to do something similar for non-sequential object but it is not working.         surf4 = TheSystem.NCE.GetObjectAt(4)        surf4.TypeData.IgnoreObjects = 1First TypeData.IgnoreObjects want a string but I don’t know what to write. Thank you very much in advance fir your answer. Clotilde 

2344
David.Nguyen
Luminary
Imaad
ImaadSingle Emitter
asked in ZOS-API
Zemax C++ ZOS API COM Error

Hi all,I am trying to run a simple standalone c++ application which gives  “Microsoft C++ exception: _com_error at memory location” The error is on line 29 // Create the initial connection classIZOSAPI_ConnectionPtr TheConnection(__uuidof(ZOSAPI_Connection)); Does someone have an idea on what could be the issue? I prefer to use C++ as I have to integrate other code with it. Thank you.

571
Imaad
Hans-Jürgen Feige
Hans-Jürgen FeigeVisible
asked in ZOS-API
ZOS-API Suppress UNDO files

Hello All,how can I suppress writing UNDO files in an interactive zosAPI extension?This is important to speed up the process!Thanks!Hans-Jürgen

532
Hans-Jürgen Feige
I
Iari.MarinoInfrared
asked in ZOS-API
Save eulumdat/ies file via ZOS-API

Hello,still can't we save polar detector data in eulumdat/ies files with ZOS-API? Is there an alternative solution? And most importantly, can we hope that it will be implemented?Thank you!

363
David.Nguyen
Luminary
Matteo
MatteoSingle Emitter
asked in ZOS-API
Universal 1-D Plot with NSD: ZOS-API in Python

Hi everybody,I need your advice / help for using the API.I am currently trying to run my Zemax file over the interactive mode with python. So far, I have managed with the help of the ZOS-API Syntax help and the examples presented there, but I am not getting any further at this point. The Zemax file I want to control is a non-sequential system.I would like to create a Universal 1-D Plot where I plot the value of one operand (=NSDD) in my merit function in dependence of the tilt angle of an object in my system. In the image attached at the bottom you can see the settings I would like to set over python. I am struggling with setting the field “NSC Data” with python. In the documentation under KEYWORDS-->MODIFYSETTINGS I cannot find any setting for this option: UN1_CATEGORY: Use 0 for surface, 1 for system, 2 for config.  I tried 3 for “NSC data” without success. You can find the python snippet I used below. My question boiled down:Is there a way to set the NSC category in an univ

1805
Matteo
Allie
Zemax Staff
AllieZemax Staff
asked in ZOS-API
Methods for extracting detector data through the API

How can I extract detector data using the API? And how can I be sure I'm using the correct settings?

328016
MRudolf
mocquin
mocquinVisible
asked in ZOS-API
Incident angle vs image Height analysis with ZOS API

I cannot find in the doc what are the names of the parameters in the API to change the field density and wavelength, especialy in the MODIFYSETTINGS which does not mention this type of analysisMaybe it is not implemented ?Also, the analysis results do not exihbit any data: print(analysis_results.NumberOfDataGrids)print(analysis_results.NumberOfDataGridsRgb)print(analysis_results.NumberOfDataScatterPoints)print(analysis_results.NumberOfDataScatterPointsRgb)print(analysis_results.NumberOfDataSeries)print(analysis_results.NumberOfDataSeriesRgb)print(analysis_results.NumberOfMessages)print(analysis_results.NumberOfRayData)all print 0, so is there a way to retrieve the results from this analysis ?

1044
L
Hans-Jürgen Feige
Hans-Jürgen FeigeVisible
asked in ZOS-API
What is the ZOS-API-solution of ZPL-RAYTRACE

So far I haven't found a way to calculate many rays through to the image surface and read out the ray data on each surface.In ZPL, the "RAYTRACE hx, hy, px, py, wavelength" provides ray data on all surfaces (RAY*(surface)).Have I overlooked a solution using ZOS API?Many Thanks!Hans

31111
Hans-Jürgen Feige
Kentaro
KentaroSingle Emitter
asked in ZOS-API
How to dispaly PSF, MTF and Zernike Standard Coefficients

Hi. I started to study ZOS-API with Matlab today. And I managed to set a specific material refractive index and get it to work without error. And My goal is to create code that can display PSF,MTF, Thorough Forcus Spot diagram and Zernike Standard Coefficients. Therfore, could you please give me some advice how to analyze them and receive their results in Matlab? import ZOSAPI.*;![endif]-->!--[if>% Set up primary optical systemTheSystem = TheApplication.PrimarySystem;![endif]-->!--[if>% AperturePupilDia = 8.0;TheSystemData = TheSystem.SystemData;TheSystemData.Aperture.ApertureValue = PupilDia / 2;![endif]-->!--[if>![endif]-->!--[if>% Lens dataTheLDE = TheSystem.LDE;% TheLDE.InsertNewSurfaceAt(2); % Surface_1 = TheLDE.GetSurfaceAt(1);Surface_2 = TheLDE.GetSurfaceAt(2);Surface_3 = TheLDE.GetSurfaceAt(3);![endif]-->!--[if>% Surf1 InfomationSurface_1.Radius = 24.397;Surface_1.Thickness = 9.915;%Setting RefractiveIndexnd = 1.52253; materialModel = Surface_1.Mat

420
Kentaro
Buddy
BuddySingle Emitter
asked in ZOS-API
Perform Image Simulation in ZOS-API

Please do me a favor. Zemax has the function "Image Simulation". I can do this interactively. Now, I want to use "Image Simulation" to simulate 2000 frame images. Therefore, I want to use SampZOS-API Matlab programming to automatically do it.  I have learned the code ZOS-API\Sample Code\MATLAB\MATLABStandalone_04_pull_data_from_FFTMTF.m" to acquire MTF curves. Would you please tell me how to program codes. The codes can realize to load, simulate and save 2000 frame images based on "Image Simulation" moduale. It would be appreciated if you could reply me as soon as possible.

7303
mocquin
C
Chase.CalviSingle Emitter
asked in ZOS-API
Zernike Alteration in Python API

Does anyone have an example (or is there one in the zemax documentation) for altering the number of zernike terms and the terms themselves using a python API?

3458
ejh

Badge winners

  • Allow me to introduce myself
    Yryxhas earned the badge Allow me to introduce myself
  • Allow me to introduce myself
    curiouslearnerhas earned the badge Allow me to introduce myself
  • Allow me to introduce myself
    Bharadwajhas earned the badge Allow me to introduce myself
  • Visibly Un-Polarized
    John.Hygelundhas earned the badge Visibly Un-Polarized
  • Allow me to introduce myself
    guangjun.gao_1has earned the badge Allow me to introduce myself
Show all badges
Community Posting GuidelinesCookie settings


Zemax Community

Need more help?

To Chinese users:

Do not provide any information or data that is restricted by applicable law, including by the People’s Republic of China’s Cybersecurity and Data Security Laws ( e.g., Important Data, National Core Data, etc.).


不要提供任何受适用法律，包括中华人民共和国的网络安全和数据安全法限制的信息或数据（如重要数据、国家核心数据等）。



Privacy policy   License Agreements    Terms of use    Cookie Policy   Zemax Account Licensing Policies