Authored By: Derek Griffith
Published On: January 3, 2006
There are a few modes of DDE interaction, the simplest being the exchange of text strings of data. One of the applications must set itself up as a server. Zemax is the DDE server in this case, so you don't have to do anything except start Zemax. Once you have started Zemax, the DDE server is ready and waiting for a client to connect and make requests for services. The client application in this case is MATLAB.
Accessing Zemax from MATLAB
If you look in the Zemax manual in the chapter on "Zemax Extensions" in the section called "The Data Items", you will see the various request strings you can send to Zemax from MATLAB (or from other DDE clients). The manual also documents the reply that Zemax will send back to the client application. The requests can be for Zemax to perform a particular function or computation, or simply to send back data on the lens currently stored in the Zemax DDE server.
Now here is an important point to note. Zemax always maintains a separate copy of the lens data in the DDE server memory to that available to the user in the Zemax Lens Data Editor (LDE). This is a very good policy, since you don't want some DDE client coming in unexpectedly and altering your lens data. There are functions that explicitly copy the lens in the LDE to the DDE server or the other way around. The PushLens item instructs Zemax to copy the lens data in the Zemax DDE server into the LDE, and the GetRefresh item will copy the lens data in the LDE into the DDE server. As you develop your application in MATLAB, it is important to keep track of your data and take care how you use the PushLens and GetRefresh items.
From the Zemax Preferences dialog, you have control over whether extensions (MATLAB in this case) are allowed to tell Zemax to push lens data from the DDE server into the LDE. Go to the Editors tab on the Preferences dialog and look for a check box labeled "Allow Extensions to Push Lenses".
MATLAB has a few basic functions for performing DDE client operations. They include the following.
ddeinit - This function is used to initiate a DDE conversation
ddereq - Used to request data from the DDE server
ddeterm - Terminates the DDE link
The basic sequence for accessing Zemax from MATLAB is
1) Start Zemax and MATLAB.
2) Initiate the DDE link from MATLAB using the ddeinit function.
3) Send requests and obtain replies from Zemax using the ddereq function.
4) Terminate the link to Zemax using the ddeterm function.
The ddereq function is used in the text mode, that is, you send data to Zemax in the form of a text string and the answer is returned in the form of another string. To get the strings into object classes that are more useful in MATLAB (floats, doubles, integers etc.) you will use the sscanf function or other functions for string data conversion e.g. str2num.
Note that the toolbox function names are capitalized for readability. MATLAB function names are case insensitive under Windows?, so that zddeinit is equivalent to zDDEInit. This is convenient at the MATLAB command line, but the capitalization helps for readability in functions and scripts. The source code for all of the functions is available for modification and reuse, and you can examine the source to see how the basic MATLAB DDE calls are used.
Every DDE call made by MATLAB to Zemax is subject to a timeout limit. The default is set in the zDDEInit function to 3 seconds. That is, if Zemax does not respond to the DDE request within 3 seconds, the MATLAB call will return empty-handed. You will want to increase the timeout limit if you are calling on Zemax to do time-consuming computations. This can be done using the zSetTimeout function call.
Here is a simple example of an interaction with Zemax at the MATLAB prompt. Having started Zemax in the usual way, enter the following commands in MATLAB.
>> zLoadFile('C:/Zemax/Samples/Sequential/Objectives/Cooke 40 degree field.zmx')
>> [x, y] = SpiralSpot(0.4, 0, 1, 10, 10000);
You should get a plot something like this ...
Firstly the DDE link was initialized and the result of 0 indicated success, then Zemax was asked to load a lens into the DDE server with the zLoadFile function call. Now, a pretty way of representing a spot diagram is to trace a spiral of rays through the lens pupil and to plot the ray intercepts at the image plane. This is implemented in a toolbox function called SpiralSpot. Get help for the function by typing help spiralspot at the MATLAB prompt. Because SpiralSpot acts on the lens in the LDE by starting out with a zGetRefresh, it is necessary to perform a zPushLens before calling SpiralSpot. A timeout of 1 second was specified for zPushLens to complete in this case.
Note that in this example you would get the same result if you had loaded the same lens into Zemax from the Zemax File menu rather than using the zLoadFile call.
Type help zArrayTrace to get more information on bulk ray tracing. It will also be useful to consult the corresponding section in the Zemax manual. To help set up the ray input data for zArrayTrace mode 0, there is a function called genRayDataMode0.
Compiling Standalone Zemax Extensions written in MATLAB
If you have the MATLAB compiler, it is possible to compile your MATLAB scripts written using the toolbox to standalone extensions that can be run from the Zemax Extensions menu. There are a few traps that must be avoided when attempting this.
Firstly, there are a few MATLAB functions that cannot be compiled, and you will have to think of workarounds for such functions (fortunately not many).
Secondly, while your standalone extension should run fine on a machine on which MATLAB is installed, it will not run on a machine that does not have the MATLAB runtime libraries. You must therefore package your extension together with the MATLAB runtime libraries to make it fully portable. MathWorks makes this easier by packaging most of the required runtime libraries in a self-extracting archive called mglinstaller.exe (typically found in C:/MATLAB/extern/lib/win32 or thereabouts).
The final trap is that the regular MATLAB runtime libraries do not contain the code for the DDE functions mentioned above. These .dll files can be found by searching your MATLAB installation for files matching dde*.dll (typically C:/MATLAB/Toolbox/matlab/winfun or thereabouts). The runtime libraries, including the DDE libraries, must be installed to a directory that is on the Windows search path.
Things to Remember when using the Toolbox
1) Your first call after starting up Zemax and MATLAB must be to zDDEInit.
2) Timeouts can be a problem. Increase the DDE timeout limit using zSetTimeout if necessary.
3) Zemax has two copies of the lens data, one displayed in the Lens Data Editor, and the other stored in the DDE server. Your can copy the one to the other using the zPushLens and zGetRefresh functions. zPushLens always requires a single parameter giving the timeout in seconds.
4) zPushLens will only work if you have granted Zemax extensions permission to push lenses by checking the box on the Editors tab of the Zemax Preferences dialog.
I don't think there's anything we can do about that on the Zemax end. No other extensions show that behavior, so it would probably be worth posting on a MatLab forum to see if anyone there has some advice for you.