Speos and Zemax Source file converter

This KBA explains how to convert the binary light source file between Speos & Zemax.  

Authored By Yuan Chen, Michael Cheng, Qiang Wang


The code is now available on GitHub: Ansys open project on GitHub | Zemax Community


In this article, a set of Python codes are provided for users to convert the source file between Zemax and Speos.  

Some light sources like .IES file are readable in both Speos and Zemax. However, the IES source file contains only angular data and is suitable only if the optical system is at the far-field of the source. If we want to include the position data in the source file, the corresponding source file formats are different in Speos and Zemax. In Speos, it’s the .RAY file. In Zemax, there are two file formats, which are .DAT (monochromatic) and .SDF (polychromatic). 

In section 1, the source file format of Zemax and Speos are described. 

In section 2, we demonstrated how to use the provided Python code to convert a Zemax light source to Speos light source. The sample source file use here is rayfile_LCB_G6SP_100k_20210701_Zemax.dat. 

In section 3, we demonstrated how to use the provided Python code to convert a Speos light source to Zemax light source. The sample source file use here is rayfile_LCB_G6SP_100k_20210701_Speos.ray. 

If there is any question regarding this converter, please contact Zemax via email box zemax.support@ansys.com or the website https://www.zemax.com/, or contact Speos via speos_support@ansys.com. 


Speos and Zemax source file format 

In this section, the source file format of Zemax and Speos are described. It’s not the main purpose of this article, but users could follow the described definition here to create their own source files for Speos or Zemax. 

The file format of .RAY, .SDF, and .DAT are all defined in binary form. The binary source file contains a header structure and then the data for each ray follows. Speos and Zemax source files contain different header information, and the ray data are defined in different orders. 

1.1 Speos source file format 

The Speos header structure has 28 bytes, which includes 7 double values. They correspond to:

1. radiometric power 

2, 3, 4, 5, 6: define the version of the ray file.  

7: photometric power 

Data of each ray is defined after the header. The data of each ray is described by 8 double values: 

  • X
  • Y 
  • Z 
  • L 
  • M 
  • N 
  • Wavelength 
  • Energy  

X, Y, Z indicate the ray position. 

L, M, N indicate the direction. 

Wavelength is the wavelength of the ray. 

Energy is the energy contained by the ray; the unit is in Watts. 

1.2 Zemax source file format 

The format definition of Zemax source file is defined in the following section in the help file. 

The Setup Tab > Editors Group (Setup Tab) > Non-sequential Component Editor > Non-sequential Sources > Source File 

In this article, we will also explain it shortly. The Zemax Binary Source File contains 208 Bytes, they correspond to: 


The description contains 100 Bytes. The size of other data is 4 bytes. Be careful with this when you create your own source file. 

The ray_format_type must be either 0 for flux only format, or 2 for the spectral color format. Other format types are not supported. If and only if the ray_format_type is 0, then the flux_type is 0 for watts, and 1 for lumens. For the spectral color format, the flux must be in watts, and the wavelength in micrometers. 

After the header follows the ray structure. The ray structure format depends upon the ray format type.  

Here is the ray format for a monochromatic source: 


The same as the Speos ray data, X, Y, Z indicate the ray position. And L, M, N indicate the direction. The flux in Zemax source file is equivalent to the energy data in Speos. 

The ray format for a polychromatic source is: 


1.3 Speos and Zemax spectrum file format

Sometimes we can find spectrum files supplied with the source file. So, we add this part so that the spectrum files can be converted and applied as well. Both spectrum files are in text format.

The Speos spectrum file ends in the extension *.spectrum. It contains this information: header, name,the total number of wavelengths and their weights, wavelength and weight.


The Zemax spextrum files end in the extension *.SPCD, and are placed in the <objects>\Sources\Spectrum Files folder. The files are used to describe a user-defined spectrum for source color modeling. The file format is pairs of numbers in the following format:

# comment <optional>
wavelength1 weight1
wavelength2 weight2

The wavelength values are in micrometers and must be listed in ascending order. The weight values are in dimensionless relative power units. At least 3 but no more than 200 pairs of data points may be defined.


Convert from Zemax to Speos

This section explains how to use the Python code to convert a Zemax source file to Speos source file. 

2.1 Run the Python code 

Open the IDLE from Python. Note the version of the Python used in this article is 3.9.2. 


Click File > Open. 


Choose the Python file named Convert_ZEMAX_to_SPEOS.py, from the attached zip file in this article. 

Before running the Python code, make sure you modify the path to the source file you want to convert. 


Modify theZemaxSpectrumPath  to the path of spectrum file in the PC if needed.


If you prefer to select the file in a graphic user interface, you can uncomment the following 3 lines too. 


Then click Run Module: 


In this attachment of this article, we provide the following source file to demonstrate the conversion. 


Note you can tell from the extension file name (.DAT) that this source file is monochromatic. We also support .SDF conversion.


During the conversion, some key information is printed. The converted ray file is saved at the same directory as the original source file. 


2.2 Result of angular, position distribution in Zemax 

To verify the consistency of the source before and after the conversion, the source file is imported and traced in Zemax OpticStudio as below. 

The source file is placed in the \Document\Zemax\Objects\Sources\Source Files folder so that it can be selected from the source file list. 

Select the Source File as source type. 


A detector polar is created to observe the angular distribution. Its maximum angle is set to 180 degrees and the radial and angular pixel numbers are set to 180. 

A detector rectangle is also created with Z = 1mm, X Half Width = Y Half Width = 10 mm and #X Pixel = #Y Pixel = 100. This allows us to check the light pattern of this source file at 1 mm far from the source file. 


Here are the angular and position distributions. 



2.3 Result of angular, position distribution in Speos

This are the sensor parameters in Speos. 


Here are the obtained angular and position distributions in Speos. 




Convert from Speos to Zemax

This section explains how to use the Python code to convert the Speos source file to Zemax source file. Since the Speos source file always contains the wavelength information, the generated Zemax file type shall always be .SDF. 

3.1 Run the Python code 

Again, we use IDLE Shell 3.9.2 to run the code. 

Choose the Python file named: Convert_SPEOS_to_ZEMAX.py 


Then modify the file path to the path of rayfile_LCB_G6SP_100k_20210701_Speos.RAY in the PC. 


Modify the SpeoSpectrumPath  to the path of spectrum file in the PC if needed.


Click Run Module. 


If there is no any warning or error in the Python window, usually the file is converted successfully. 


3.2 Result of angular, position distribution in Speos 

The same sensor parameters as the above example are applied to run the simulation. The angular and position distributions are the same as the one converted above. 




3.3 Result of angular, position distribution in Zemax 

The generated source file is placed in the <data>\Objects\Sources\Source Files folder and selected as the source file. 


The converted spectrum file: LCB_G6SP_20210701_spectrum.spcd shall be copied in the <data>\Objects\Sources\Spectrum Files folder and selected as the spectrum file. 


The same detector settings are applied. 


Here are the angular and position distributions. 


3.4 Other notes 

Please be aware that Speos is not the only software that generates the .ray file. 

If you get this warning message during the conversion: “Warning: File size is not 28 + 8 * 4 * N ? Please verify if it is a Speos .ray file.”, the source file conversion may lose some ray data. 

You may refer to the below website for more information:


Was this article helpful?
3 out of 3 found this helpful



Please sign in to leave a comment.