Raytrace and analysis loop
This example demonstrates how to use FRED's scripting language to automate the task of performing a raytrace and analysis inside of a loop. A Plane Wave (coherent) type Source Primitive will be tilted over a range of angles inside of the loop and the resulting irradiance distributions for each configuration will be saved to a FRED Grid Data (FGD) file on disk.
The simple model consists of a plane wave source incident on a singlet lens element and coming to focus on an absorbing plane. An analysis surface, "Plane_Surface", is located on the image plane and will be used when performing an irradiance calculation. Shown below is the raytraced model when the source is configured to be aligned with the z-axis.
A common, repetitive task to be performed is to tilt the source to some incident angle with respect to the optical system and then perform a new raytrace and analysis. In this model, a Plane Wave (coherent) type Source Primitive is used for the source representation (see image below). The source tilt angle will be controlled by modifying the source's Location/Orientation settings. At the bottom of the source dialog, three Location/Orientation operations are defined that have the following purpose:
|0||Operation #0 sets the starting coordinate system of the source when it gets inserted into the model. In this case, the source begins its life in the coordinate system of the Lens 1 node.|
|1||Operation #1 specifies a z-shift of -0.5 mm in the coordinate system of Lens 1. The purpose of this operation is to move the source node off of the vertex of Lens 1 and break the source/lens coincidence.|
|2||Operation #2 specifies a right handed rotation about the x-axis in the coordinate system of Lens 1. The script will update this value inside of a loop in order to apply a new tilt angle to the source.|
Note that each of these operations has an index (0-2) associated with it, which we will be using in the script in order to "point" to one of these specific operations for manipulation.
There are three scripts that can be found in the Embedded Scripts folder of the example file. For the purposes of this KB article, we will be looking at the embedded script named, "Generate FGD files". Double click on this script to open it in the editor.
The first portion of the script performs the following tasks:
- Update the preference setting responsible for the retention of Analysis Results Nodes in the Analysis Results folder (refer to the Help system for more information on this)
- Retrieve the node number for the source to be raytraced and store it in the "src" variable. Retrieve the node number for the analysis surface to be used in the analysis calculation and store it in the "ana" variable.
- Specify the output directory path where the analysis results will be written to FGD files on disk.
- Define the min/max angle scan range and the angle steps. The source will be rotated over the specified range, with a raytrace and analysis being performed at each step.
Sub Main 'Set preference to retain all Analysis Results Nodes (ARNs) PrefsSetARNRetainCount( -1 ) 'Source to be raytraced and analysis surface used for irradiance Dim src As Long, ana As Long src = FindFullName( "Optical Sources.Plane Wave" ) ana = FindFullName( "Analysis Surface(s).Plane_Surface" ) 'Directory where output data will be written Dim outDir As String outDir = "C:\temp\fred\support\fgd_data\" 'Source angle scan limits and angle step resolution Dim minAng As Double, maxAng As Double, angStep As Double minAng = 0 'degrees maxAng = 1 'degrees angStep = 0.1 'degrees
The next block of code retrieves operation #2 from the source node and stores the information in a variable called "tOp". What information is stored in tOp? In the image of the source dialog above, operation #2 contains three pieces of information; the coordinate system that the operation is defined in, the type of operation being performed (an x-axis rotation in this case), and the value associated with the operation. The GetOperation command could also have been placed inside of the loop, though it isn't necessary to retrieve this data each time inside of the loop (and is therefore wasteful from a programming perspective). You can think of this GetOperation call as initializing the tOp variable values, which will then be modified and applied inside of the loop later.
'Retrieve the x-angle tilt operation definition from the source node Dim tOp As T_OPERATION GetOperation( src, 2, tOp )
The main work loop, shown below, performs three major tasks:
- The first task is to update the x-rotation angle in the tOp variable (tOp.val1 = curAng) and then apply this new value to the source node using the SetOperation( src, 2, tOp ) call. This SetOperation call can be read as: "take the definition in tOp and place it in operation #2 of the src node". The Update call makes sure that the FRED document views are up to date and reflect the new changes.
- The second task is to delete any rays that exist in the ray buffer and then trace new rays (the TraceCreate call generates rays from any active source and then traces them through the model without rendering any rays in the visualization view).
- The third task is to generate a unique name for the current analysis result, call the Irradiance analysis and store the result in an analysis result node (ARN), and then finally write the ARN out to an FGD file on disk in the output directory.
'Begin loop over angles of interest Dim arn As Long, curAng As Double, curName As String For curAng = minAng To maxAng Step angStep 'Update the source's x-angle tilt tOp.val1 = curAng SetOperation( src, 2, tOp ) Update 'Trace new rays DeleteRays() TraceCreate 'Calculate irradiance and write results to fies on disk curName = "Irradiance_" & CStr(curAng) & "_deg.fgd" IrradianceToARN( ana, curName, arn ) ARNWriteToFile( arn, outDir & curName, False, False ) Next
The last part of the script simply prints a message to the output window indicating that the script has finished its task and then deletes all of the analysis results nodes from the Analysis Results folder. Note that this last step is not necessary, of course. The user may wish to keep the analysis results in the Analysis Results folder for review after the script execution, in which case this code can simply be commented out or deleted.
Print "Finished writing ARN data to file." 'Delete all analysis results nodes from the model ARNDeleteAllNodes() Update End Sub
After executing this script, the output directory that was specified in the script will contain a collection of *.fgd files. There will be one FGD file for each source angle that was raytraced and analyzed.
It is important to note that FGD files can always be re-loaded back into a FRED document by right mouse clicking on the Analysis Results folder and selecting the option, "Create New ARN From a File".
FRED Example File: fgd_processing.frd