Saving Image Simulation images in a ZPL macro

To output an image file from the Image Simulation tool in a macro, one needs to create a configuration file. This has to be done once manually by pressing Save from the settings menu of the analysis window (Fig. 1).


Figure 1 - Creation of a configuration file (*.CFG) from the settings menu of the Image Simulation window.

If an Output File is specified, the next time Image Simulation is called from a macro, a file will be saved in the image folder of OpticStudio, typically: User.Name\Documents\Zemax\IMAFiles\, with the corresponding name. The Image Simulation analysis can be called in a macro with the command line:
 

1 OPENANALYSISWINDOW "Sim"

If the Output File is to be specified in the macro, it can be done with this command line:
 

1 MODIFYSETTINGS name_of_cfg_file$, ISM_OUTPUTFILE, output_name$

Where the string variables name_of_cfg_file$ and output_name$ correspond to the configuration file full path, and the output file name, such as MyOutputImage.PNG (more details on the supported file formats can be found in the Help File of Image Simulation). Other settings are available to edit using the MODIFYSETTINGS keyword, and we refer the reader to the Help File for additional information on this matter.

Copy saved image

The above section will produce an image file from an Image Simulation analysis. If the resulting file is to be used within the same macro, for example to copy this file elsewhere in the computer, a special trick needs to be utilized to make this file appear in the macro environment.

In this thread, I am using the FINDFILE keyword, but I'm calling it through a sub macro that is called from within my macro, which saves the image of the Image Simulation. The sub macro will be executed in an environment where this new image file could be present. The other thing that needs to be checked before attempting to move the image file is that it will be created with a 0 kb size (a black image), and will take a moment to achieve its final size.

The two macros below are used to perform these tests, and illustrate how the image from Image Simulation can be copied from within the parent macro.

Parent macro (IS_Analysis.ZPL):

1! Retrieve current file path
2file_path$ = $FILEPATH()
3
4! Retrieve existing configuration (*.CFG) file
5n_char     = SLEN(file_path$)
6cfg_file$  = $LEFTSTRING(file_path$, n_char-4) + ".cfg"
7
8! Verify that configuration file exists. Alternatively,
9! it could also be specified directly
10FINDFILE temp_file$, cfg_file$
11
12! If the configuration file exists
13IF (SLEN(temp_file$))
14    ! Specify output filename
15    ima_file$ = "ImageToBeCopied.PNG"
16    MODIFYSETTINGS cfg_file$, ISM_OUTPUTFILE, ima_file$
17
18    ! Open and run the Image Simulation
19    OPENANALYSISWINDOW "Sim"    
20
21    ! Wait for the analysis to terminate and start saving the image
22    PAUSE THREADS    
23
24    ! Image path
25    ima_path$ = "<Replace with your path>\Documents\Zemax\IMAFiles\"
26    ima_path$ = ima_path$ + ima_file$
27    
28    ! Put image path in STRING buffer
29    CALLSETSTR 1, ima_path$    
30
31    ! Setup timeout in seconds
32    timeout = 120    
33
34    ! Start timer
35    TIMER   
36
37    ! Waiting loop
38    LABEL 1    
39
40    ! Run FINDFILE in a separate macro
41    CALLMACRO FINDFILE_CUSTOM.ZPL    
42
43    ! Retrieve a boolean which says if the file was found
44    ima_flag = CALD(1)    
45
46    ! If the file is found, copy it, otherwise loop
47    IF (ima_flag == 1)
48        ! Once found, wait for the file to be complete
49        PAUSE THREADS
50        ! Copy the file
51        COPYFILE ima_path$, "C:\Zemax\ImageCopied.PNG"        
52        ! Print success message
53        PRINT "Image file copied successfully."
54    ELSE
55        IF (ETIM() > timeout)
56            PRINT "Image file not copied. The Image Simulation did not complete before timeout."
57        ELSE
58            GOTO 1
59        ENDIF
60    ENDIF
61! Otherwise print an error message
62ELSE
63    PRINT "Error: configuration file missing!"
64ENDIF

Child macro (FINDFILE_CUSTOM.ZPL):

1ima_path$ = $CALLSTR(1)
2
3FINDFILE temp_file$, ima_path$
4
5IF (SLEN(temp_file$))
6    CALLSETDBL 1, 1
7ELSE
8    CALLSETDBL 1, 0
9ENDIF 

I had to add two PAUSE THREADS, I believe the first one waits for the Image Simulation to be terminated. Then, the loop waits until a 0 kb version of the output file appears. The second PAUSE THREADS is meant to wait until the file reaches its final size.

Let me know if the code isn't clear, or if you have a better solution to this problem.

Happy ray tracing,

PS: both macros are also attached to this thread in a *.ZIP archive. Line 25 of IS_Analysis.ZPL should be edited with your own document folder.

David