Keyword management of source nodes

Introduction

FRED has no restriction on the number of optical source definitions that can be present in a single model and it is not uncommon for complex models to contain upwards of a hundred different source definitions. As of FRED version 18.11, however, this is no way to group sources together into subfolders within the Optical Sources folder on the object tree, which would be useful for turning on/off groups of sources together (you currently have to visit each source individually). This example demonstrates a way to use the Keyword construct to facilitate turning on and off groups of sources together.

Keywords

Keywords are a property type in FRED that is intended to help facilitate complex model construction and configuration by acting as pass-throughs for objects which have been assigned a keyword. This property type adds an additional level of organization and control over model configuration on top of the basic organizational hierarchy provided by the object tree structure itself. Furthermore, keywords can be applied to any type of node on FRED's object tree with the exception of Embedded Scripts and Analysis Results Nodes (ARNs).

As an example of the basic usage of the keyword property type, consider the scenario shown below where a collection of objects with the same fundamental optical property (painted black, in this case) are not located contiguously on the object tree. Without keywords, the user would have to assign the same set of properties to each individual node; a process that is both prone to operator error and unnecessarily repetitive. With keywords, the operator only has to assign the properties to the keyword itself and each of the objects having that keyword automatically inherit the property assignment.

In the example above, the Black Paint keyword is serving two purposes:

The keyword describes the intended optical behavior at a high level and implies a set of FRED properties (ex. Black Paint scatter model, Reflect Scatter raytrace control, Absorbing coating) that should be assigned to those objects.
The keyword facilitates assignment of the properties implied in (1) above by routing any properties dropped onto the keyword back out to the nodes in the object tree in one action.

Since Keywords are nothing more than labels that get applied to a collection of nodes in the tree, their usage is extremely general and flexible. You can, for example, right mouse click on a keyword and select, "Isolate and fit view to selection" from the menu, which will update the 3D view to show you only the objects with the associated keyword. This makes it convenient to easily isolate and view subsystems within the model. In the scripting language, it is straightforward to retrieve the objects associated with a particular keyword so that all of the objects can be looped over and modified. What action is taken within that loop on those objects is entirely up to you!

Source Grouping

The attached example file contains six plane wave source definitions in the Optical Sources folder. Lets say that the particular analysis task defines three groups of sources, with two sources in each group, and we would like to quickly turn on the source group of interest while turning off the other groups. Since FRED doesn't have any way of organizing the sources within the Optical Sources folder, we will use the Keyword functionality to accomplish this task.

In the image below, the six optical sources are shown in the Optical Sources folder and three keywords have been defined in the Keywords folder. The three keywords have been assigned to sources, two sources in each keyword group. Note that the assigned keywords show up in the Keywords column of the tree to the right of the source nodes. In the 3D view, the sources associated with the keyword, "group 1" are drawn in blue, "group 2" in red and "group 3" in green.

Embedded Script

An embedded script called, "Toggle Groups", exists in the Embedded Scripts folder. The script will be used to help facilitate quickly turning on one or more source groups by leveraging the keyword assignments.

This script will take the following actions:

Retrieve a list of all keywords in the model
Present a dialog to the user allowing them to choose which keyword group to make traceable
Turn off all source nodes
Turn on only the source nodes in the selected keyword group(s)

Double click on the embedded script node to edit it.

The script begins execution in the Main subroutine, as all FRED scripts do. The first block of code is a For loop that iterates over all nodes in the Keywords folder of the object tree and stores the names of each keyword in an array called "kwnames".

'#Language "WWB-COM"

Option Explicit

Sub Main

    Dim kwnames() As String, nKw As Long, curKw As Long
    nKw = KeywordCount()
    ReDim kwnames(nKw-1)
    For curKw = 0 To nKw-1
        kwnames(curKw) = KeywordGetName( curKw )
    Next

The next section of code defines a custom dialog that will be presented to the user containing a selectable list of the keywords in the document. After the user closes the dialog, an If statement is used to determine whether any action needs to be taken by the script (if the user didn't select anything in the dialog, then there isn't any work to be done).

    'user dialog
    Begin Dialog UserDialog 400,203 ' %GRID:10,7,1,1
        Text 10,0,380,21,"Select traceable groups (CTRL or SHIFT to select multiple):",.Text1
        OKButton 10,168,100,21
        CancelButton 140,168,110,21
        MultiListBox 20,28,360,126,kwnames(),.MultiListBox1
    End Dialog
    Dim dlg As UserDialog
    Dialog dlg

    'Were any groups selected?
    If UBound(dlg.MultiListBox1)<0 Then
        'Update the model and stop here
        Update
        Print "No groups selected to be traceable.  No action taken."
        End
    End If

If the user did select any of the keywords listed in the dialog, a report of the selected keyword groups is printed to the output window.

    'Report the selected kws and generate new array
    Dim kwsel() As Long
    ReDim kwsel(UBound(dlg.multilistbox1))
    Print ""
    Print "Groups selected to be traceable"
    For curKw = 0 To UBound(dlg.MultiListBox1)
        kwsel(curKw) = CLng(dlg.multilistbox1(curKw))
        Print kwnames(dlg.MultiListBox1(curKw))
    Next

A custom function call is used to turn off all source nodes.

    'Set all nodes associated with keywords as not-traceable to start
    MakeAllNotTraceable()

A second custom function call is made that turns on all sources associated with the selected keywords and the model is updated.

    'Now re-activate only those nodes associated with the selected KW groups
    MakeSelectKWTraceable( kwsel )

    'Update the model
    Update

End Sub

Example Usage

The starting configuration of the model is shown in the image below.

Now, right mouse click on the embedded script, "Toggle Groups", and select, "Run an embedded script". A dialog will be opened listing the available keywords. Use the CTRL or SHIFT keys on your keyword to select one or more of the keywords from the dialog and then press OK.

The updated model view is shown below. Notice that only the sources in groups 1 and 3 are traceable on the object tree.

In scenarios where you find yourself toggling on/off sets of sources for different analyses, this type of keyword script can be useful to help streamline your model interactions.

Example FRED file: sourceKeywords.frd