Structure Builder - An open-source Boolean-based structure creation tool

One of the first pieces of code introduced on Gateway Code webpage was the Structure Builder application. For those that have already downloaded and become familiar with the Simple Structure Builder tool, there are some new features to be listed up front.

1. Steps can be removed using a Delete Step button.

2. Structure Details can be added to created structures such as the structure code and the structure color.

3. The open-source version of the code has a branch that allows for the structure builder to utilize the Structure ID Dictionary in Visual Scripting to help match up structure Ids.

Simply stated, the behavior of the Simple Structure Builder, which is also found on the Simple Structure Builder Github, is as follows.

A. To start building out the steps needed to auto-generate the structures in this tool, click the button to add a step.

New Feature: a remove button has been added to the tool. If a step needs to be removed, select the entire step row and the button will become active.

B. Once all the steps have been added, click Run to execute the steps.

C. If a template is created that can be useful again, export the structure creation steps to a json template.

D. The next time the Simple Structure Builder is run, those json templates can be imported.

When a new step is added, the following settings are customizable within the UI.

A. Result - This is the name of the structure that you'd like to create.

Note: If the structure with the same ID of the result structure already exists, this structure's contour is updated

B. Base Structure - This is the structure on which the operation is going to be applied.

C. Operation - Operation to perform. This could be And, Or, Sub, Margin, or Asymmetric Margin.

D. Target Structure or Margin

i. If And, Or, or Sub are selected in the operation, the Target structure defines the structure with which the operation is completed.

ii. If Margin or Asymmetric Margin are selected, this box in which the margin value is defined.

E. If the structure could be removed prior to the end of the running script, mark that structure as temp.

Note: Some structures require two operations. For example, a ring structure is a margin step followed by a sub step from the original structure. If the initial step is to be deleted, it can be made a Temp structure.

F. Details (New Feature) - Update structure's code and/or color from the a popup UI.

Now that the basics of the UI features have been explored, the rest of this post will discuss some details about the Simple Structure Builder tool, as well as a basic tutorial for those who want to download the already compiled code and those who are able to compile the tool in Visual Studio.

Before the details of the tool, it is important to highlight the other open-source code bases that can perform similar functions. The Simple Structure Builder is not the only option for the development of optimization structures, and readers should find the tool that works best for your clinic's needs. There could certainly be more tools out there, but this is from a basic search of the ESAPI subreddit.

• CC gen - a format-based tool for the generation of contours.

• Optimate - Automated creation of optimization structures (and other derivative structures with template management.

• ESAPI_SimpleGUI_ContourUnions - A script to generate unions of contour structures with ESAPI

• Remove Empty Structures - A simple tool to remove any empty structures.

Additionally, if your intention is to use the Structure Dictionary Branch with this application, please see the update notes about this feature here.

In the sections below, varying features and instructions exist on whether or not the user wants to download the code from the Gateway Scripts code website or clone the code from Github and compile in Visual Studio. It is understandable that not all people have the capability to use Visual Studio in their clinic, so both of these workflows could be useful for slightly different audiences. Before those sections, let's discuss one more topic.

Remember to always review contours prior to planning or optimizing on them, especially if they will be used for evaluation of the treatment plans.

App Config Settings

There are a couple of settings that can be changed outside the application that will impact the behavior of the application. Both the downloaded compiled code, and the cloned source code will have a configuration file in the application directory called StructureBuilder.exe.config.

Opening this file in a text editor such as notepad or notepad++, two application settings can be seen. The first setting is regarding exclusion types. This means that any structure that is a PTV, GTV, CTV or ORGAN DICOM type will not be overridden if the Result Structure Id already exists in the current structure set. The second setting only controls a small part of the UI. Without this set to true the UI will display text at the bottom of the screen that says Not valid for clinical use. Please leave this setting to false if the tool has not been clinically validated for the structures to be created in your clinic. Remember to always review contours prior to planning or optimizing on them, especially if they will be used for evaluation of the treatment plans.

Downloading Compiled Code

The code can be found on the Gateway Code webpage. On this newly updated downloads page, please enter the requested information, read the user agreement and agree in order to download the code. The information provided is not shared with any third parties, but they're saved in a subfolder of the Gateway Scripts outlook inbox in case any significant issue with the code is found and must be shared with all users. After submitting all the information in the form, a download link will appear below the Submit button. Unzip (extract) the downloaded folder.

All code in this folder should go into the PublishedScripts folder of Eclipse. Inside of the External Beam Planning workspace, click on Tool --> Scripts, and then select Open Folder... In the PublishedScripts folder path that opens, create a new folder to hold the StructureBuilder application. Copy and paste all downloaded files into this new subfolder.

Within the downloaded files, there is a Resources folder, a file called StructureBuilder_Launcher.cs exists. Copy this file, and paste it back into the PublishedScripts folder. This launcher file is based on a Carlos J Anderson blog post from years ago to launch stand-alone executable files in Eclipse. At the bottom of the file, a string states "EXE Path goes here". Copy and paste the path of the StructureBuilder.exe path and paste it over the highlighted text. Please check that there are only one set of quotations around the text.

Note: by holding down the shift key, and right mouse clicking on the StructureBuilder.exe file, the windows menu will include a "Copy as path" option that will copy the full file path to clipboard.

Save the changes to the launcher file. The file should now show up in the scripts window when the System scripts radio button is selected. Prior to running the script, a structure set should be open in Eclipse.

Cloning Structure Builder from Github

(If you already know how to clone and compile ESAPI code, feel free to skip to the next section)

From the Github Structure Builder repository, click on the green Code button at the top right of the repository page. From here, copy the web URL. In Visual Studio, select the option to Clone A Repository and paste the repository location into an appropriate location. Once Visual Studio loads, the code can be compiled.

Notes on Compiling the Application

It may be the case that the Eclipse system where this script should run is not in version 16.1. In that case, some basic settings must be changed in order to prepare this application for the particular clinical version. From within Visual Studio, enter the project properties by clicking the Project dropdown and select the last option Structure Builder Properties. In the Application tab select the Target Framework for the specified version of ESAPI.

If you attempt to compile the code on a desktop that does not have ESAPI installed, for example a VIC virtual machine or a test box, you may have to manually attach the ESAPI reference libraries to the project. To do this, navigate to the Solution Explorer (this should be available on the right side of Visual Studio). Under the section labelled References find the references named VMS.TPS.Common.Model.API and VMS.TPS.Common.Model.Types. It is common to see a yellow warning arrow beside each of these dependencies. Remove these references from a right click option or by selecting the reference and clicking the delete key. Right click the references section in the solution explorer and choose the option Add Reference. Using the Browse button browse to the path of your VMS ESAPI libraries. Finally, compile the application from the Build menu at the top of Visual Studio and select Build Solution.

The VMS library hint path is the location where the project can look for the libraries if they're not available in the compiled application location prior to searching in the GAC. Here, enter the path to the ESAPI libraries on the clinic's production servers. If the VMS libraries cannot be resolved from the application location or the hint path, Varian also installs these libraries in the GAC to be found as the final check-down.

(Optional) .NET Framework projects will use the referenced libraries that are available in the build folder of the application. If a referenced library is missing that is available in the Windows Global Assembly Cache (GAC), the application will automatically reference the Framework Class Library from the GAC location. In addition to this, the project properties where the referenced libraries are collected for the project will also allow for the addition of a Hint Path. The project properties can be accessed in Visual Studio via right mouse click on the project and selecting Unload Project. The VMS library hint path is the location where the project can look for the libraries if they're not available in the compiled application location prior to searching in the GAC. Here, enter the path to the ESAPI libraries on the clinic's production servers. If the VMS libraries cannot be resolved from the application location or the hint path, Varian also installs these libraries in the GAC to be found as the final check-down.

Running the Application

Debugging in Visual Studio

Debugging the ESAPI Script in Visual Studio requires Visual Studio to be installed on the same system as Eclipse. This is only within Varian's scope of the product if you're working on a test-box or a research system (for example, the Varian Innovation Center). It is not advised to download and install Visual Studio on a production Eclipse environment. Prior to debugging the application, the patient and structure set context will need to be available to the application. These objects can be added as command line arguments.

To access command line arguments entering the application, select the Project dropdown and select Structure Builder Properties. Access the Debug tab and there find the Command line argument. The expected input would look as follows:

"<PatientId>;<3DImageId>;<StructureSetId>"

where <PatientId>, <3DImageId>, and <StructureSetId> represent the identifiers for the patient, 3D planning image, and structure set, respectively (note, do not replicate the brackets <>). At this point, the Start button at the top of Visual Studio should launch the application.

Installing the Application to Production

After compiling the application, the compiled code files, as well as a resources folder that houses a dictionary of potential structure codes and also a launcher file for users to launch the application. The upload of the compiled code and setting up the launcher file is described in detail in a prior section.

Utilizing the Structure Dictionary

When deploying templates that match based on Structure Id, it may be useful to utilize a structure dictionary to help match structure identifiers. The structure dictionary expected is the Visual Scripting Structure Dictionary as described in a prior blog post. If the code has been cloned from Github, a branch named "dictionary" is available that utilize these features. To access this branch, change the Solution Explorer tab to Git Changes. Next click the dropdown that says master and select dictionary.

Selecting this branch pulls a number of changes to the code-base, but the most significant is the following App.config file parameter. In the value parameter of this tag, type in the server name where the Visual Scripting Structure Dictionary is installed.

<add key="StructureDictionaryServer" value="Gateway-TBOX"/>

On running the application, a new button is available that will allow for the application to match structures coming in from a template via the structure dictionary. In order for this structure dictionary to work, the template being imported should contain the key to the dictionary, and the structure set should contain one of the possible values in the dictionary for that given key. Please note, only the first value in the dictionary will be matched if multiple matches exist.

The Structure Builder offers increased efficiency to automating the creation of boolean operation structures in Eclipse. Please consider creating an issue on Github if any issues arise, and also consider downloading for the new features offered.