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:
 

 OPENANALYSISWINDOW "Sim"

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

 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):

! Retrieve current file path
file_path$ = $FILEPATH()

! Retrieve existing configuration (*.CFG) file
n_char     = SLEN(file_path$)
cfg_file$  = $LEFTSTRING(file_path$, n_char-4) + ".cfg"

! Verify that configuration file exists. Alternatively,
! it could also be specified directly
FINDFILE temp_file$, cfg_file$

! If the configuration file exists
IF (SLEN(temp_file$))
    ! Specify output filename
    ima_file$ = "ImageToBeCopied.PNG"
    MODIFYSETTINGS cfg_file$, ISM_OUTPUTFILE, ima_file$

    ! Open and run the Image Simulation
    OPENANALYSISWINDOW "Sim"    

    ! Wait for the analysis to terminate and start saving the image
    PAUSE THREADS    

    ! Image path
    ima_path$ = "<Replace with your path>\Documents\Zemax\IMAFiles\"
    ima_path$ = ima_path$ + ima_file$
    
    ! Put image path in STRING buffer
    CALLSETSTR 1, ima_path$    

    ! Setup timeout in seconds
    timeout = 120    

    ! Start timer
    TIMER   

    ! Waiting loop
    LABEL 1    

    ! Run FINDFILE in a separate macro
    CALLMACRO FINDFILE_CUSTOM.ZPL    

    ! Retrieve a boolean which says if the file was found
    ima_flag = CALD(1)    

    ! If the file is found, copy it, otherwise loop
    IF (ima_flag == 1)
        ! Once found, wait for the file to be complete
        PAUSE THREADS
        ! Copy the file
        COPYFILE ima_path$, "C:\Zemax\ImageCopied.PNG"        
        ! Print success message
        PRINT "Image file copied successfully."
    ELSE
        IF (ETIM() > timeout)
            PRINT "Image file not copied. The Image Simulation did not complete before timeout."
        ELSE
            GOTO 1
        ENDIF
    ENDIF
! Otherwise print an error message
ELSE
    PRINT "Error: configuration file missing!"
ENDIF

Child macro (FINDFILE_CUSTOM.ZPL):

ima_path$ = $CALLSTR(1)

FINDFILE temp_file$, ima_path$

IF (SLEN(temp_file$))
    CALLSETDBL 1, 1
ELSE
    CALLSETDBL 1, 0
ENDIF 

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