Using Project Directories to organize OpticStudio files

Also available in 日本語, 简体中文

Introduced in OpticStudio 21.3 and revised in OpticStudio 2023 R2, the Project Directory system enables easy packaging and storage of important Zemax files so that they can be easily accessed and manipulated on a project-by-project basis. Project Directories help prevent overwriting data stored in common files accessed by multiple OpticStudio design files. 

Authored By Alissa Wilczynski, Updated by Biswajeet Mishra, Kevin Scales

Problems with conventional file organization

Problems with conventional file organization

The complete representation of an optical system in OpticStudio relies on data stored not only within the ZMX lens file, but also many other supporting files serving different purposes. These contain additional data, such as optical materials information, coating prescriptions, and CAD files.

In Zemax's conventional organizational system, many of these supporting files are located within the \Documents\Zemax\ folder structure. Often, the same file would be referenced by many different optical system models (ZMX files). When sharing files between users or machines, this structure can cause problems if the recipient has modified any of the underlying files on their computer. Upon opening an archive (ZAR) file, for example, they are given a choice to overwrite or skip any duplicate files when unpacking the ZAR. Overwriting the file may cause them to lose their edits and customization; skipping the file may prevent them from seeing a proper representation of the original system.

Each OpticStudio system will use different underlying files, but the full list of files used within a given system is accessible under Analyze...Reports..Prescription Data, in the Files Used section. A full listing of Zemax file types can be found here. 

Using the Project Directory file organization system

To avoid the problems described in the previous section, it is recommended that you organize your files in the Project Directory system. This allows for easy packaging and storage of all files associated with a given system so that those files can be easily accessed an manipulated on a project-by-project basis. When saving a system to a Project Directory, project-specific versions of the supporting files are saved to a unique folder of your choice, which prevents overwriting data stored in common folders. 

To save an existing system to a Project Directory, navigate to File...Convert to Lens Project. Pick an existing folder or make a new one; this will be the location for your ZMX, ZDA, and supporting files. 

Once you’ve selected a folder, you’ll be prompted on which files to include in the project. You need not include all of them, but for this example let’s just do everything. Use the sliding buttons to select Root or Project for each offered option, and then click OK:

Within your specified Project Directory, the software will create subfolders and files for supported file types that are used in your model. These may include ABG_DATA, COATINGS, and GLASSCAT folders.

Your \Documents\Zemax\ folder will continue to exist, and it will still contain all files included with your OpticStudio or OpticsViewer installation. For a file saved as a Project Directory, if any required file cannot be found within that directory, the software will next look within the folder specified under File...Project Preferences...Folders and use the appropriate folder or file. 

There are additional buttons in the Project Directory group that we will now look at. The first is the New Lens Project button. Functionally, this is similar to the Convert to Lens Project button except it creates a new project with a blank system. Be sure to save your working system if desired.

You can change the settings using the Lens Project Settings button. This opens the same window that we saw earlier during the project creation, setting Root or Project file sources for any files used.

Finally, the Save Lens Project As button allows you to save a duplicate project, including the same included folders. Functionally, this is much like the Save As button in most software packages, saving everything but under a different name or in a different location.

Using the project files option to create a lens profile creates some different options in OpticStudio. The first is in the Archive group, just to the left of the Project Directory group. The Create Archive button will now, instead of creating a .ZAR archive file, create a .ZPRJ archive file for the full project. Anything saved as part of the project will be included. The option to create a .ZAR file is not available for project files.

Finally, when the existing file is part of a project, the buttons in the Project Directory change to the following options:

Instead of converting to a lens project, we can now convert back to a lens file if we want to discard the project functionality and just work with the .ZMX file.

The new file will go in the same folder as the current .ZMX, but you may use the Browse button to select a different destination folder. When the file is converted back to a lens file, the associated project files will remain in their existing location. Root files may need to be overwritten, but the project files need to be removed manually. If you convert the file back to a lens file in the same folder you’ve been using for the project, you will see on your Windows Explorer that the file structure looks very much the same. However, you can verify using the Prescription Data report that the associated files have reverted to the \Documents\Zemax\ folder structure.

To see a list of supported file types, refer to product documentation. As of OpticStudio 2026 R1, the included files are:

Receiving files saved as Project Directories

When loading an archive file, you have the option to extract files to Project Directories or to the Root. It is recommended that you leave these boxes set to Project. Doing so will create the same file structure as previously outlined.

If you do not want your files organized as a Project Directory, you can decline this option. When the archive is restored, only your ZMX and ZDA files will be located within the "To Folder" specified. All other supporting files will be organized in the \Documents\Zemax\ folder hierarchy or, where applicable, the folders specified in the Project Preferences.

For more information on sharing files with colleagues, see the article How to share an OpticStudio file.