Matching via Structure Name Dictionary in Visual Scripting Action Packs

Introduction

In a prior post, it was discussed how the Structure Name Dictionary can be used to assist in structure matching. This post included finding, interpreting, and using the structure dictionary to find matches for structures within the context of RapidPlan structure matching or boolean operation structure creation. Not to be overlooked, there is another use-case with which the Structure Name Dictionary could be useful in structure matching -- within Visual Scripting action packs. The Structure Name Dictionary is most certainly intended to be used within the context of a Visual Scripting Action pack.

In this scenario, let's assume an action pack that performs a "sanity check" of dosimetric evaluations. These metrics are not planning specific, but perhaps a check on the DVH for structures that are hard constraints for any planning situation. Specifically, we can export the following metrics:

Structure	Metric	Tolerance
Brainstem	Dmax [cGy]	< 5400
Optics	Dmax [cGy]	< 5400
SpinalCord	Dmax [cGy]	< 5000

Building the Structure Dictionary

In order to use the Structure Name Dictionary to find these structures and evaluate the doses, the structures must be added to the Structure Name Dictionary. For a more complete introduction to the Structure Name Dictionary and how to access and use it within Visual Scripting, check out the prior blog post on using the Structure Name Dictionary. To access the dictionary, open Visual Scripting from External Beam Planning, drag in a PlanSetup context item, and connect the PlanSetup to a Calculate DVH Metrics action pack. Open the Design Time View of the Calculate DVH Metrics Action pack and click Structure ID Dictionary at the bottom.

In this structure dictionary, a few more entries will be added from the table above. Click OK when finished. There is no need to save the Visual Script itself, as the dictionary saves automatically.

The additions to the Structure Dictionary can be seen in the Structure Dictionary file at the following path.

"\\<Server Path>\VA_DATA$\ProgramData\Vision\VisualScripting\StructureNameDictionary.xml" 

where <Server Path> would be the location of your institutions image data repository. The most useful match we see here will be the matching of the Optics structure to multiple structures for the final evaluation.

Setting up the Visual Scripting Action Pack

Using the Eclipse Script Wizard for generating Visual Scripting Action Packs is highly recommended, as the Visual Scripting Action Pack template embeds many required libraries, properties, and methods that would be otherwise time-consuming to manually code. Open the Eclipse Script Wizard and select the Visual Scripting Action Pack Template. In this example, an Action Pack called Metric Checks is being created.

In Visual Studio, open the project generated by the wizard. Follow the initial prompt to change the class name and constructors to a unique class name. In order to understand how to use the Structure Dictionary, it would first be helpful to review the various constructors available in the visual scripting action pack class.

Parameterless Constructor or not Parameterless Constructor -- That is the question!

Visual Scripting Action Packs come with two constructors: one without parameters and another with the IVisualScriptElementRuntimeHost as an input parameter. The former is the constructor that runs when you drag the element into the Visual Scripting canvas, or when you open the Visual Script in the Visual Scripting workspace. The latter is accessed only when the Visual Script is run from Eclipse.

---

Try it out for yourself!

You can tell when the constructors are run with a simple piece of code placed into each constructor. Add these simple MessageBox items and test to see when the constructor is being accessed by Visual Scripting.

Please Note: For this example to work, the PresentationFramework library must be added to the project.

---

The IVisualScriptElementRuntimeHost is critical to the implementation of the Structure Dictionary as seen in the class definition below. Not only does this interface implement definitions for the StructureDictionary, but also the ScriptContext as well. Consider the utility of have the entire ScriptContext available to your Visual Scripts.

Back in the action pack, the host is available whether or not its used, but to access this object from outside the constructor, a member can be created and set to the value of the host inside the constructor.

Setting up the Return Class

Toward the bottom of the class file, the return data type may be created. This return type has a number of properties to describe the metric and its status to the plan, but also a property to inform whether the structure was determined by the structure dictionary. Other changes included in the screenshot below: (1) the returned value of the AllowedOptions property is commented out as the selection in the design time user interface is not necessary, and (2) the DisplayName has been updated for this script.

Set the return type of the Execute method to a new ConstraintModel IEnumerable collection, and instantiate a new ConstraintModel list.

Using the Structure Dictionary

The Execute method is initially set up with some local constraints that are hard-coded with respect to the structure ID and metric. These local constraints are iterated, and one-by-one a structure is first selected if a structure ID matches the current constraints structure ID.

After the if statement in line 52 has gotten a chance to match structure IDs directly, the script then looks to the Structure Name Dictionary to determine if the current constraint matches any Keys in the dictionary. If any key matches are found, the Values are iterated looking for a match within the structure set. If this value is found, the same evaluation code is run and the value is added to the constraints collection, with the single differentiation of DictionaryMatched being set to true.

In this code example, structure name matching is not case sensitive. This behavior is consistent with how the structure dictionary matches structures in the Calculate DVH Metrics action pack.

Running the Script

Compile the script, and move the script to the CustomActionPacks folder. This folder location should be in the same path as the Structure Name Dictionary above. Open Visual Scripting from the External Beam Planning workspace. Click Menu--> Load Action Packs and load the action pack called Metric Check. Drag the PlanSetup context item into view. The Check Constraints action pack should be available in your quick list to the right side. Connect this action pack to the To Table action pack, and then finally to the To View Action Pack. The resultant Visual Script should look as follows:

The To Table action pack can be configured to show all properties of our method, including a property for the dictionary matching with the label Matched from Dictionary. It may also be beneficial to change the table caption since this is a custom class collection being passed into the action pack.

Finally on running the application, the constraints can be evaluated. From the Matched from Dictionary column, the Brainstem is currently being matched on the structure ID. The Spinal Cord, and Optics are being matched through the structure dictionary to Cord, and Chiasm, OpticNerve_L, and OpticNerve_R, respectively.

Final Thoughts

The Structure Name Dictionary has shown utility both within Visual Scripting and through custom script solutions. Within Visual Scripting the utilization only requires a few lines of code, and allows us to discuss and understand the various constructors within the Visual Scripting action pack more closely. The challenge is to determine how to use the Structure Name Dictionary most effectively. Should the key values in the Structure Name dictionary represent the TG-263 structure IDs, RapidPlan model structure IDs, or structure names from an institutions structure templates?