Skip to main content

Programming OpticStudio

Share your solutions or ask questions about the ZOS-API, ZPL, or DLLs. Code shared in these spaces is not reviewed by Zemax except for the Code Exchange.

735 Topics
S
Luminary
Sandrine AuriolLuminary
posted in Code Exchange
New to the Code Exchange? Read this!

The Code Exchange is a moderated community where Zemax users can find or share programming solutions to extend OpticStudio’s capabilities. It can be a macro to read the sag of a surface or a DLL to define a phase surface. Browse through our space to find out what we have or share your own!Just a few things before getting started:These solutions are mostly written by optical engineers and not developers. Use them as a starting point and feel free to improve them. Comment on the post if you make an improvement or find something interesting that could be useful to other users!  Do you have a solution to share? Create a topic in the Code Exchange category using the tag Code Exchange. Be sure to include a ReadMe doc. An example template is attached. Once posted, our team will verify it and comment if needed. 

6380
S
Luminary
Brian
BrianInfrared
asked in ZOS-API
Local Optimization failure

I am using the ZOS-API in C# with 4.8.1 framework using Zemax OpticStudio 2024 R1.02 and getting an error message when running the Local Optimization tool.The error message returned from running the tool is “Input settings are invalid”.This occurs only when I load from an Archive File (.ZAR).   If I load from a model file (.ZMX) then the Local Optimization tool works as expected.For the fields that I set, there are only 2; Algorithm = DampedLeastSquares and Cycles = AutomaticIt’s weird and I can’t understand the difference between accessing the model from an Archive would create this issue. NOTE, that I did load the ZAR file from the actual Zemax application and Optimization worked fine. If anyone has any ideas as to the issue then please let me know ThanksB.

442
Brian
S
simon.schroeder_01Infrared
asked in ZPL
ZPL Detector Viewer Update

Hi,I would like to use zpl to update my detector viewer and save it as an image.However, neither Ray Database nor Filter are adjusted in the detector viewer.#trace rays & evaluate Detectorfilter$ = "h3&h6&!x_hitface(8,0)&!x_hitface(8,2)&!x_hitface(4,0)&(x_hitface(7,1)|x_hitface(7,0))"filter2$="h3&h6&!x_hitface(8,0)&!x_hitface(8,2)&!x_hitface(4,0)"fileName$ = "ZMPRays.ZRD"NSTR 1, 0,0,0,0,1,0,1,fileName$temp = NSDD(1,0,0,0) ZRDPlayback fileName$,1,0,1, filter2$UPDATE ALLPRINT NSDD(1,9,0,0)ZRDPlayback fileName$,1,0,1, filter$UPDATE ALLPRINT NSDD(1,9,0,0)settingsFile$= "...\Zemax\Configs\DVR.CFG"MODIFYSETTINGS settingsFile$, DVW_ZRD, fileName$MODIFYSETTINGS settingsFile$, DVW_FILTER, filter$UPDATE ALLThe  PRINT NSDD(….) commands give the correct outputs, but the detector viewer is not updated.How can I use ZPL to update the detector viewer using the Ray Database fileName$ and the filter string filter$?

311
David.Nguyen
Luminary
Matt H
Matt HMonochrome
asked in ZOS-API
Updating Spot Diagram

The ray density of the spot diagram is not being updated as expected; I have tried two different methods: # spot diagramspot = TheSystem.Analyses.New_StandardSpot()spot.GetSettings.RayDensity = 15spot.ApplyAndWaitForCompletion() newSpot = TheSystem.Analyses.New_StandardSpot()print("Spot has analysis specific settings? ", newSpot.HasAnalysisSpecificSettings) # True; no ModifySettingsnewSettings = newSpot.GetSettings()newSettings.RayDensity = 15newSpot.ApplyAndWaitForCompletion() However, after being run the ray density of the spot diagram does not update as expected - any ideas?

281
David.Nguyen
Luminary
Xianglei
XiangleiMonochrome
posted in ZOS-API
API_Layout_plot_Python

API support for the Cross-Section, 3D Layout, and Shaded Models is added to the OpticStudio API.  The support allow users to change the settings via the API and retrieve a static image.  Layouts in both sequential and non-sequential mode are supported. Some toolbar buttons, such as automatically setting camera viewpoints, will also be accessible via the API. Please download the following Python Standalone codes, including:PythonStandaloneApplication_SEQ_layout.py       (sequential mode and export 2D cross-section) TheSystem.Tools.OpenCrossSectionExport()   # the core command  PythonStandaloneApplication_SEQ_3DViewer.py (sequential mode and export 3D viewer) TheSystem.Tools.Open3DViewerExport() PythonStandaloneApplication_SEQ_ShadedModel.py (sequential mode and export shaded model) TheSystem.Tools.OpenShadedModelExport() PythonStandaloneApplication_NSC_3D.py              (non-sequential mode and export 3D layout) TheSystem.Tools.OpenNSC3DLayoutExport() PythonStandaloneApplication_NS

94127
mocquin
Ultraviolet
Samia.O
Samia.OSingle Emitter
asked in ZOS-API
Connection problems between Zemax and Matlab

Hello everyone,I can't connect Zemax and Matlab since I installed the new version of zemax 2025 R1.01. I am using Matalb version 2019a Updates 9 and it worked with previous versions of zemax.The error in question Unable to load one or more of the required types.My two applications are installed in 64bits I've already tried uninstalling and reinstalling the applications. Thanks for your help 

220
Samia.O
L
Leonid.PascarInfrared
asked in ZOS-API
retrieving pop beam via ZOS_API Python

Hi, I try to retrieve the output POP field distrubution via python. I looked in the help at IAS_PhysicalOpticsPropagation and couldn't find direct way to do it. I know I can manually save ZBF files and then load, but I need a script as I change parameters and want to retrieve the output beam. How would you advise to do so?   Thanks, Leonid

5193
SJ314
S
Sebastián.GedeonSingle Emitter
asked in ZOS-API
Ignoring multiple surfaces at once, ZOSAPI, python

Hello fellow optics enthusiasts,I’m currently working on a task where I need to ignore multiple surfaces in a Zemax optical system using the ZOS-API. At the moment, I’m using the following loop:for i in range(150, 160): surface = TheSystem.LDE.GetSurfaceAt(i) surface.TypeData.IgnoreSurface = TrueHowever, this approach seems to be quite slow. Has anyone found a more efficient way to ignore multiple surfaces at once?Any insights or suggestions would be greatly appreciated!Thanks in advance,Sebastián

422
S
A
Ultraviolet
AmitUltraviolet
asked in ZOS-API
Genarating Wavefront maps while varying sag on a surface

Hello Everyone,What is the best way to create sag on a lens surface (one of the two surfaces would be the beginning, and then I would move to both surfaces) and parametrize it using python so that i can create wavefront maps and the changes in the wavefront maps based on the localized changed in the sag?Here is what I want to do:Create sag on a lens surface that can be parametrized (conic constant and the other asphere constants can be varied) For each combination of these parameters, evaluate the wavefront mapSo far, the knowledgebase articles show how to use a .dat file to induce sag on surfaces, but there is nothing about parameterization.Is there a Python example that does something similar?Or is there any other method that would make more sense? Thank you for your insights.Amit

170
A
Ultraviolet
joshdfreeman
Ultraviolet
joshdfreemanUltraviolet
asked in ZOS-API
Access coating properties in ZOS-API?

Is there a way to access the properties of a coating in the ZOS-API? The article below shows how to access the name of the coating, but does not show how to get the properties of the coating.I’m not finding any handles that give the actual coating information. Thanks!

1423
mocquin
Ultraviolet
c​hris
c​hrisInfrared
posted in ZOS-API
ZOS API: says the coating is None in the API, but OpticStudio says there is a coating

In the API, I make some checks on the ZMX file before running simulations. One of the checks is that at least face 0 has a coating. The API tells me there is no coating, but I can see in OpticStudio that there is a coating. Here is the object in OpticStudio: And the coating from the API: I'm certain I have the right object - why is the coating incorrect in the API? How can I check for the existence of coatings on face 0? Right now I'm using face_data.Coating not in {'None', 'NULL'}.

1264
mocquin
Ultraviolet
Ivair.Gontijo
Ivair.GontijoSingle Emitter
asked in DLLs
How do I calculate a ray intercept point with a standard surface?

I am trying to develop a UDS (User Defined Surface) DLL and have been reading the excellent articles in knowledge base about this. Taking as the starting point the “us_stand.c” code for the standard surface (available in the folder /Zemax/DLL/Surfaces), I understand that Zemax provides an intercept point to the tangent plane (x0, y0, z=0) and direction cosines (l0, m0, n0) for the ray at that point. Then the real ray trace is performed in case 5 and for complicated surfaces there is no analytical solution for the ray intercept point on the surface. Hence an iterative solution is needed.What I am struggling to understand is: how do those equations in case 5 work? I thought that there would be no analytical solution to find the ray intercept point with the standard surface. However, the equations in case 5 seem to be quite simple, although I was not able to derive them.  Therefore, my questions are:Is the algorithm in case 5 of “us_stand.c” implementing a closed-form analytical solution,

854
Ivair.Gontijo
Michael Cheng
Zemax Staff
Michael ChengZemax Staff
posted in Code Exchange
DLL (User-Defined Surface): Sequential Binary 1+2

This DLL provides a user defined surface that has planar substrate and a phase profile integrating both radial polynomial and extended polynomial. It can be considered as a combination of surface Binary 1 and Binary 2, but with only planar substrate. This is useful for metalens design.    Click here to download Date Version OpticStudio Version Comment 2020/08/07 1.0 20.2 Creation 2021/01/01 1.1 20.3.2 Fix bug by dividing phase by approaching refractive index

10201
J
Daniel Dominguez
Daniel DominguezSingle Emitter
asked in ZOS-API
How to perform Standard Zernike Analysis across multiple files simultaneously using Zemax Python API and Multiprocessing

Hi all - As the title states, I’m attempting to perform a Standard Zernike Analysis across multiple files simultaneously using the Zemax Python API and Multiprocessing (running 4 instances of Zemax). My attempt is shown below. Failures I’ve encountered include: *** FRU__delta_init(): Attempt to start when running!andUnboundLocalError: local variable 'zos' referenced before assignmentI’m not sure if my approach is flawed or if I’m just attempting something that’s not allowed with Zemax or something else. Any insight you can provide would be greatly appreciated. Thanks! Also, thank you to David Nguyen for his example code on performing a Zernike Standard Analysis here.if __name__ == '__main__': import multiprocessing as mp import os import glob from ShortZernMonolith import ShortZernMonolith documents_path = os.path.join(os.path.expanduser("~"), "Documents") directory_path = documents_path + "\\SenseCheck" # Create list of TSAV*.zmx files found in folder TSAV_File

471
chaasjes
Matt H
Matt HMonochrome
asked in ZOS-API
Cannot Set Source Sampling in NSC

I am unable to set the source sampling in NSC; here is my code: led_source = TheNCE.GetObjectAt(1)led_source_type = led_source.GetObjectTypeSettings(ZOSAPI.Editors.NCE.ObjectType.SourceRadial)led_source.ChangeType(led_source_type) led_source.SourcesData.PrePropagation = -1print("Preprop: ", led_source.SourcesData.PrePropagation)print("Sampling: ", led_source.SourcesData.SamplingMethod)led_source.SourcesData.SamplingMethod = "Sobol"print("Sampling: ", led_source.SourcesData.SamplingMethod) Note Pre-propagation can be [set, get] through SourceData, whereas SamplingMethod can only be [get]. When I execute this code I get the following: Preprop:  -1.0Sampling:  SobolTraceback (most recent call last):  File "C:\Users\matthew.haines\Documents\Zemax\ZOS-API Projects\PythonStandaloneApplication4\PythonStandaloneApplication4\PythonStandaloneApplication4.py", line 226, in <module>    led_source.SourcesData.SamplingMethod = "Sobol"TypeError: since Python.NET 3.0 int can not be converted to

462
Matt H
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

47211
Prasath R
Zemax Staff
M
ma-sundeMonochrome
asked in ZOS-API
ZOS-API: NumSegs=0 from IRayTraceNSCData.ReadNextResult for All Manually Added Rays

Hi all,I'm using the ZOS-API in Python (OpticStudio 2024 R1) with IBatchRayTrace to trace manually defined NSC rays. I'm creating the interface using teh batch tool and adding rays using nscData.AddRay(...).The trace completes successfully (batchTool.Succeeded is True, and RunAndWaitForCompletion() doesn't crash ). However, when I read the results using nscData.ReadNextResult(), the numSegments output parameter is consistently 0 for all rays. This happens even when:The system is minimal (new file, 1 wavelength, 1 Standard Lens, 1 Detector Rectangle). Rays are defined with various trace options (None, UsePolarization, UseSplitting, UseScattering, and combinations). The ray path clearly interacts with objects (e.g., passes through the lens and hits the detector).It also doesnt show any errors...Is it expected that IRayTraceNSCData.ReadNextResult will return numSegments = 0 for simple interactions like refraction or absorption when rays are launched via AddRay? If so, what is the intended

595
MichaelH
Ansys Staff
S
Luminary
Sandrine AuriolLuminary
posted in Code Exchange
API (CS User Analysis): Sequential Through Focus PSF

This Zemax User Analysis calculates a longitudinal PSF, a PSF through focus.Author: @Michael.Humphreys   Click here to download Date Version OpticStudio Version Comment 2022/03/09 1.0 - Creation  

4034
J
Hans-Jürgen Feige
Hans-Jürgen FeigeVisible
asked in ZOS-API
ZOS-API "GETZERNIKE"

Hello,We are urgently looking for an alternative to ZPL-GETZERNIKE using ZOS-API.The point is that we cannot tell “TheSystem.MFE.GetOperandValue(MeritOperandType_ZERN, “ the maximum term of Zernike.“TheSystem.MFE.GetOperandValue(MeritOperandType_ZERN, “ always develops only up to the given coefficient :-(MAny ThanksHans-Jürgen

92317
Michael Cheng
Zemax Staff
Egis
EgisSingle Emitter
asked in ZPL
Through Focus Spot Diagrams separated by wavelengths

The current Through Focus Spot Diagram (TFSD) merges all wavelengths in the same plot, however it provides separation between fields. Right now I’m cloning windows and set the wavelength separate in each window.Is it possible to have a “simple” script to have them separate by wavelengths for a single field? What could be a command for the TFSD plot then?In principle it gives a different view to a Focal Shift.  

230
Egis
M
Marc.DerrienInfrared
asked in ZPL
ZRDPLAYBACK no longer works?

Hi,I would like to use the ZRDPLAYBACK function, but it doesn't seem to work, I think it doesn't take filters string into account.I have similar problem iy I use a function like  NSTR 1, 1, 0, 0, 1, 1, 1, 1, A$ ,”W1”,2Marc.

614
M
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

2025
B
mocquin
Ultraviolet
mocquinUltraviolet
asked in ZOS-API
Dispersion Diagram in ZOS API

Can you confirm that neither setting the paramters of a dispersion diagram or reading the results is possible through the API ?I couldn’t find any settings neither extract some dataseries results

181
mocquin
Ultraviolet
Brian
BrianInfrared
asked in ZOS-API
ZOS-API question : Turning off Axis when creating Bitmap

I’m using the ZOS-API (ver. 2024 R1) with C# and creating an Open3DViewerExport (I3DViewerExport) bitmap of the Ray Trace.The bitmap gets generated to a file but includes the axis (X,Y,Z) in the lower left corner of the image.The application allows to turn this access off but I don’t see the option within the API. Is there anyway that the API can turn this off as well?Thanks.B.

532
Brian
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

19892
S

Badge winners

  • Allow me to introduce myself
    Bharathas earned the badge Allow me to introduce myself
  • 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
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