About the Eclipse Scripting API

The Eclipse Scripting API is a Microsoft .NET^®^ class library that gives you access to the treatment planning data of Eclipse. It allows you to create scripts that leverage the functionality of Eclipse, and lets you retrieve plan, image, dose, structure, and DVH information from the Varian System database. The data is retrieved from the Varian System database also in stand-alone Eclipse installations. You can integrate the scripts into Eclipse, or you can run them as stand-alone executables.

With Eclipse Automation feature, you can also create scripts that allow you to create and modify structure and plan data, and execute dose calculation and optimization algorithms. These scripts are first created and tested in a non-clinical development environment, but can then be approved for clinical use.

WARNING
SYRS350.75: "The authors of custom scripts are responsible for verifying the accuracy and correctness of the scripts after developing a new script or after system upgrade for the existing scripts."

Features

By using the Eclipse Scripting API, you can:

• Write custom scripts and integrate them into the Eclipse user interface.

• Write stand-alone executable applications that leverage the Eclipse Scripting API.

You can access the following information with ESAPI scripts:

• Image and structure models, including their volumetric representations.

• Plans, fields, and accessories.

• Predecessor plans.

• Plan protocol information.

• IMRT optimization objectives and parameters.

• Clinical goals

• Doses, including their volumetric representations.

• Dose volume histograms.

• Optimal fluences.

• DVH estimates.

• Plan uncertainty information.

• Prescription Information.

• Treatment session information.

With Eclipse Automation, you can also create scripts that:

• Create and modify structures and structure sets.

• Create and modify plans and fields.

• Create and modify verification plans and copy images from another patient for those plans (for example, copy a scanned phantom image from a designated case).

• Create artificial phantom images.

• Generate DRRs.

• Create evaluation doses to evaluate dose calculated outside of Eclipse.

• Optimize plans by using the Eclipse optimization algorithms.

• Calculate leaf motions by using the Eclipse leaf motion calculation algorithms.

• Calculate dose by using the Eclipse external beam and BrachyVision TG-43 dose calculation algorithms.

• Set field and plan uncertainty parameters and calculate plan uncertainty doses.

• Execute DVH estimation.

• Modify raw and final scan spot lists for proton plans.

The Eclipse Scripting API provides you also the following:

• Possibility to use visual scripting.

• A wizard that makes it simple to create new scripts.

• Patient data protection that complies with HIPAA.

• Support for user authorization used in Eclipse and ARIA^®^ Radiation Therapy Management (RTM).

• API documentation.

• Example applications.

• Full 64-bit support.

System Requirements

The basic system requirements of the Eclipse Scripting API are the same as those of Eclipse. For more information, refer to Eclipse Customer Release Note.

Note

Microsoft Visual Studio is not needed for creating scripts. However, some features described in this document assume that Microsoft Visual Studio 2013 has been installed.

Clinical Environment

To run read-only ESAPI scripts in a clinical environment, you need the following:

• Eclipse 15.1 or later.

• A license for the Eclipse Scripting API 15.1 or later.

To approve and run ESAPI scripts created for Eclipse Automation, you need:

• Eclipse 15.1.1 or later.

• A license for the Eclipse Scripting API 15.1.1 or later.

• A license for Eclipse Automation 15.1.1 or later.

Development / Research Environment

To develop ESAPI scripts in a non-clinical development (research) environment, you need the following:

• Eclipse 15.1 or later (optional for creating scripts, mandatory for running them).

• A non-clinical Varian System database configured for research use.

• Eclipse Scripting API license.

• Eclipse Scripting API for Research Users license.

Version Compatibility

Note

If you use an obsoleted type, property, field, or method, the compiler shows a warning. In this case, the compilation of a single-file plug-in fails. If the script is a binary plug-in or a standalone executable, the compiler shows an error. This happens only if the "Treat warnings as errors" project setting is turned on in Microsoft Visual Studio.

ESAPI 17.0

The Eclipse Scripting API 17.0 is compatible with Eclipse 17.0.

Varian Medical Systems provides no guarantee that scripts written with this version of the Eclipse Scripting API will be compatible with future releases.

The target framework for the scripts must be Microsoft .NET Framework 4.8.

ESAPI 16.1

The Eclipse Scripting API 16.1 is compatible with Eclipse 16.1.

Varian Medical Systems provides no guarantee that scripts written with this version of the Eclipse Scripting API will be compatible with future releases.

The target framework for the scripts must be Microsoft .NET Framework 4.6.1.

ESAPI 16.0

The Eclipse Scripting API 16.0 is compatible with Eclipse 16.0.

Varian Medical Systems provides no guarantee that scripts written with this version of the Eclipse Scripting API will be compatible with future releases.

The target framework for the scripts must be Microsoft .NET Framework 4.6.1.

ESAPI 15.5

The Eclipse Scripting API 15.5 is compatible with Eclipse 15.5.

Varian Medical Systems provides no guarantee that scripts written with this version of the Eclipse Scripting API will be compatible with future releases.

The target framework for the scripts must be Microsoft .NET Framework 4.5.

ESAPI 15.1.1

The Eclipse Scripting API 15.1.1 is compatible with Eclipse 15.1.1.

Varian Medical Systems provides no guarantee that scripts written with this version of the Eclipse Scripting API will be compatible with future releases.

ESAPI 15.1

The Eclipse Scripting API 15.1 is compatible with Eclipse 15.1.

Varian Medical Systems provides no guarantee that scripts written with this version of the Eclipse Scripting API will be compatible with future releases.

ESAPI 15.0

The Eclipse Scripting API 15.0 is compatible with Eclipse 15.0.

Varian Medical Systems provides no guarantee that scripts written with this version of the Eclipse Scripting API will be compatible with future releases.

Incompatibilities between ESAPI 15.0 and ESAPI 13.7:

• In prior versions, for stand-alone executables, the method Application.CreateApplication took two parameters, userid and password to identify a user. In Eclipse Treatment Planning System 15.0, a new security framework is introduced, and the logged-in user is automatically identified.
• Fractionation class has been removed, and its properties and methods have been moved to PlanSetup class.
• OptimizationSetup.AddStructurePointCloudParameter() method and Beam.ExternalBeam property that were previously marked as obsolete are now removed (the latter one is replaced by Beam.TreatmentUnit).

ESAPI 13.7

The Eclipse Scripting API 13.7 is compatible with Eclipse 13.7.

Varian Medical Systems provides no guarantee that scripts written with this version of the Eclipse Scripting API will be compatible with future releases.

Incompatibilities between ESAPI 13.7 and ESAPI 13.6:

• In prior versions, proton plans were represented as ExternalPlanSetup types. In version 13.7, a new class hierarchy for proton plans (IonPlanSetup) has been added. The consequence of this is that methods with return type ExternalPlanSetup that used to return proton plans now do not. The following methods and properties have been changed to return only photon external beam plans:
  • ScriptContext.ExternalPlansInScope
  • ScriptContext.ExternalPlanSetup
  • Course.ExternalPlanSetups The corresponding methods of ScriptContext and Course returning PlanSetup types continue to return external beam plans, brachytherapy plans, and proton plans as previously.

ESAPI 13.6

The Eclipse Scripting API 13.6 is compatible with Eclipse 13.6.

Varian Medical Systems provides no guarantee that scripts written with this version of the Eclipse Scripting API will be compatible with future releases.

ESAPI 13.5

The Eclipse Scripting API 13.5 is compatible with Eclipse 13.5.

Varian Medical Systems provides no guarantee that scripts written with this version of the Eclipse Scripting API will be compatible with future releases.

ESAPI 13.0

The Eclipse Scripting API 13.0 is compatible with Eclipse 13.0.

Varian Medical Systems provides no guarantee that scripts written with this version of the Eclipse Scripting API will be compatible with future releases.

Incompatibilities between ESAPI ESAPI 13.0 and ESAPI 11.0:

• The type VMS.TPS.Common.Model.Types.VRect has been changed to immutable. Scripts that use the set accessors of VRect properties are incompatible with the Eclipse Scripting API 13.0.

• The type VMS.TPS.Common.Model.ExternalBeam has been marked as obsolete. It is replaced by the VMS.TPS.Common.Model.ExternalBeamTreatmentUnit type.

• The property VMS.TPS.Common.Model.Beam.ExternalBeam has been marked as obsolete. It is replaced by the VMS.TPS.Common.Model.Beam.TreatmentUnit property.

ESAPI 11.0

The Eclipse Scripting API 11.0 is compatible with Eclipse 11.0.

Assembly Version Numbers

The Eclipse Scripting API is a Microsoft .NET class library that is also called an assembly. The .NET assembly can have several different version numbers. The three version numbers that are used in ESAPI are:

• AssemblyVersion: This is used by Visual Studio and .NET framework during building and at runtime to locate, link, and load the assemblies. The assembly version is visible, for example, in Visual Studio, in the properties of the assembly reference.
• AssemblyFileVersion: This is the version number of the file. It is displayed in Windows Explorer, in the file properties dialog of the assembly.
• AssemblyInformationalVersion: The product version of the assembly. It is displayed in Windows Explorer, in the file properties dialog of the assembly. Product version number is also visible in Eclipse Scripting API Online Help.

Starting from ESAPI release 15.0, assemblies have used the .NET strong naming. The strong (or full) name of the assembly consists of name, version, culture, and public key token. Originally, these three version numbers have been the same in ESAPI, but starting from the ESAPI release 15.1, the AssemblyVersion is different. This enables changing the AssemblyVersion based on changes in ESAPI, in comparison to the file and product versions that are automatically updated based on Eclipse release.

The following table contains the version numbers per release starting from ESAPI 15.1 release:

ESAPI Release	AssemblyVersion	AssemblyFileVersion	AssemblyInformationVersion
17.0	1.0.500	17.0	17.0
16.1	1.0.450	16.1	16.1
16.0	1.0.400	16.0	16.0
15.5 MR1	1.0.200	15.5	15.5
15.5	1.0.100	15.5	15.5
5.5	1.0.7	15.1	15.1
15.1	5.	15.1	15.1

Upgrade to ESAPI 17.0

Binary plug-in scripts and stand-alone executable scripts that have been compiled using versions 15.5 and later of Eclipse Scripting API will work after upgrading to the Eclipse Scripting API 17.0 without recompilation since the major version of the API has not been changed, there are no breaking changes, just additions to the API.

Stand-alone scripts that have been compiled using versions older than 15.5 of Eclipse Scripting API do not work after upgrading to the Eclipse Scripting API 17.0. Additionally, binary plug-ins for older versions do not compile after the upgrade.

To make the scripts work with ESAPI 17.0, you need to update the Visual Studio projects to reference the new ESAPI 17.0 assemblies.

Do the following:

1. Open the Eclipse Script Visual Studio project.

2. Expand the References item in the Solution Explorer. You should see the existing references to VMS.TPS.Common.Model.API and VMS.TPS.Common.Model.Types.

3. Remove both references from the project.

4. Add new references to the ESAPI 17.0 assemblies.

In the Add Reference dialog box, select the Browse tab. The assemblies are located under the installation directory of the Eclipse Scripting API, in the API subdirectory.

5. Add references to both VMS.TPS.Common.Model.API.dll and VMS.TPS.Common.Model.Types.dll.

6. In the properties of the solution, make sure that the Target Framework is NET 4.8.

7. Recompile the project.

If you are using a script provided as a part of an earlier Eclipse version and you have copied the script to another location, you need to re-fetch the script from the same location of the new Eclipse version.

What Is New in Eclipse Scripting API 17.0

Many new properties, functions, and classes have been added or changed in ESAPI 17.0. See the detailed documentation in Eclipse Scripting API Online Help. The most significant changes and additions are listed below.

Brachytherapy Planning

The following brachytherapy planning features were added to Eclipse Scripting API, or support for writable scripting was added to the already existing features.

Plans

• It is now possible to create brachytherapy plans using the Course.AddBrachyPlanSetup method.

• It is now possible to copy a brachytherapy plan using the Course.CopyBrachyPlanSetup method.

• It is now possible to copy a brachytherapy plan to a new image with the Course.CopyBrachyPlanSetup method.

• It is now possible to change the treatment unit of all applicators of a brachy plan with the BrachyPlanSetup.ChangeTreatmentUnit method. A list of the available brachy treatment units can be obtained through the new Equipment class, with the Equipment.GetBrachyTreatmentUnits method.

Plan Properties

• It is now possible to define the treatment time of the plan by setting the BrachyPlanSetup.TreatmentDateTime property.

• It is now possible to define the treatment technique by setting the BrachyPlanSetup.BrachyTreatmentTechnique property.

• Property PlanSetup.NumberOfFractions: For brachytherapy plans, it is now possible to set NumberOfFractions together with properties DosePerFraction and TreatmentPercentage, using the SetPrescription method.

• Property PlanSetup.DosePerFraction: For brachytherapy plans, it is now possible to set DosePerFraction together with properties NumberOfFractions and TreatmentPercentage, using the SetPrescription method.

• Property PlanSetup.TreatmentPercentage: For brachytherapy plans, it is now possible to set TreatmentPercentage together with properties NumberOfFractions and DosePerFraction, using the SetPrescription method.

Applicators

• It is now possible to add new applicators to the plan using the BrachyPlanSetup.AddCatheter method.

• It is now possible to link an existing reference line to an applicator in a brachytherapy plan using the Catheter.LinkRefLine method.

• It is now possible to unlink a linked reference line from an applicator in a brachytherapy plan using the Catheter.UnlinkRefLine method.

• It is now possible to link an existing reference point to an applicator in a brachytherapy plan using the Catheter.LinkRefPoint method.

• It is now possible to unlink a linked reference point from an applicator in a brachytherapy plan using the Catheter.UnlinkRefPoint method.

Applicator Properties

It is now possible to set some of the properties of the Catheter class.

• The applicator length can be defined by setting the Catheter.ApplicatorLength property.

• The length of the applicator dead space can be defined by setting the Catheter.DeadSpaceLength property. This property is not supported for solid applicators.

• The applicator step size (property Catheter.StepSize), first source position (property Catheter.FirstSourcePosition), and last source position (property Catheter.LastSourcePosition) can be defined with the Catheter.SetSourcePositions method. Calling this method will also automatically recalculate the source positions.

• It is now possible to define the applicator geometry by setting the Catheter.Shape property. This property is not supported for solid applicators.

• The applicator channel number can now be defined with the ChannelNumber property.

• The ID property of class Catheter can now be set with the Catheter.SetId method.

Reference Points

• It is now possible to add a new location to an existing reference point in a brachytherapy plan using the BrachyPlanSetup.AddLocationToExistingReferencePoint method.

• It is now possible to add a new reference point to a brachytherapy plan using the BrachyPlanSetup.AddReferencePoint method.

Dwell Positions and Times

• It is now possible to get/set the nominal dwell time for each dwell position using the SourcePosition.NominalDwellTime property.

• It is now possible to get/set the dwell time lock for each dwell position using the SourcePosition.DwellTimeLock property.

Dose Calculation

It is now possible to calculate the TG-43 dose for Brachy plans.

• The BrachyPlanSetup.CalculateTG43Dose method calculates the dose for the Brachy plan. The dose is calculated using the TG-43 dose calculation algorithm.

Approval Extensions

You can now create ESAPI Approval Extension plug-ins. These plugins are executed by the plan approval wizard of Eclipse just before and right after the plan changes state. See section Creating Approval Extension Plug-in Scripts for more details.

Script Administration

The following improvements have been made to the ESAPI Script Administration:

• You can now sort the scripts by their status to reduce the number of scrips visible on the screen at once. The filtering options are saved separately for the each user.

• It is now possible to delete scripts in that are in the Retired status if such scripts have no history of plan/structure set modifications.

• A new Varian Download Center tab is added to the ESAPI Script Administration dialog box. The tab provides access to downloading new features from cloud. See section Getting Software Add-Ons for more details.

• New Add-Ons menu item is added in Eclipse (Tools> Add-Ons) that allows browsing and executing Varian-provided software add-ons. These add-ons allow Eclipse users to access new features added from the Varian Download Center.

General Improvements

The following improvements have also been made to ESAPI:

• It is now possible to set field (protons) and plan uncertainty parameters and calculate plan uncertainty doses.

• It is now possible to add a new reference line to a structure set using the StructureSet.AddReferenceLine method.

Supported Script Types

Eclipse supports the script types listed below.

Plug-ins

Plug-ins are launched from the Eclipse user interface. After the launch, the plug-in gains access to the data of the currently open patient.

Eclipse supports three types of plug-ins:

• A single-file plug-in: A source code file that Eclipse reads, compiles on the fly, and connects to the data model of the running Eclipse instance.

• A binary plug-in: A compiled .NET assembly that Eclipse loads and connects to the data model of the running Eclipse instance.

• An approval extension plug-in: A binary plug-in that is executed during plan approval wizard operation. See section "Creating Approval Extension Plug-in Scripts" for more details.

Eclipse creates a Windows Presentation Foundation child window that the script code can then fill in with its own user interface components. The plug-in scripts receive the current context of the running Eclipse instance as an input parameter. The context contains the patient, plan, and image that are active in Eclipse when the script is launched. The plug-in scripts work only for one patient at a time in Eclipse.

Software Add-Ons

Software add-ons are features that can be downloaded from Varian Download Center. For more information, see sections Getting Software Add-Ons and Launch a Software Add-On.

Executable Applications

A stand-alone executable is a .NET application that references the Eclipse Scripting API class library. It can be launched just like any Windows^®^ application.

Stand-alone executables can be either command-line applications, or they can leverage any .NET user interface technology available on the Windows platform.

While the plug-in scripts are restricted to work for one single patient opened in Eclipse, the stand-alone executable can scan the database and open any patient.

Read-Only and Write-Enabled Scripts

Binary plug-ins and executables can be either read-only or write-enabled. Read-only scripts have only read access to the treatment planning data of Eclipse. Write-enabled scripts can be used for changing Eclipse objects.

Visual Scripts

Visual scripts are created in Visual Scripting Workbench and executed in Eclipse as single-file plug-in scripts. They can be either read-only or write-enabled. Visual scripts are launched from the Visual Scripting Workbench, or from Eclipse in the same way as ordinary single-file plug-in scripts.