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 dose calculation algorithms.
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 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
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 16.1

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 16.1 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 16.1. Additionally, binary plug-ins for older versions do not compile after the upgrade. To make the scripts work with ESAPI 16.1, you need to update the Visual Studio projects to reference the new ESAPI 16.1 assemblies. Do the following:

Open the Eclipse Script Visual Studio project.
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.
Remove both references from the project.
Add new references to the ESAPI 16.1 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.

Add references to both VMS.TPS.Common.Model.API.dll and VMS.TPS.Common.Model.Types.dll.
In the properties of the solution, make sure that the Target Framework is NET 4.5.
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 16.1

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

Proton Support

The following proton features were added to Eclipse Scripting API:

It is now possible to set the range shifter of a proton beam through IonBeamParameters class.
Preselected range shifter 1 can be set by setting properties PreSelectedRangeShifter1Id and PreSelectedRangeShifter1Setting. Respectively, preselected range shifter 2 can be set by setting PreSelectedRangeShifter2Id and PreSelectedRangeShifter2Setting.
New method for reading the proton stopping power curve of the CT scanner associated with an image was added: `Image.GetProtonStoppingPowerCurve*.*
New getter property for IonBeam was added: IonBeam.BeamLineStatus.
New Dual-Energy CT (DECT) specific methods:
- Image.CalculateDectProtonStoppingPowers, that calculates the pixel-wise proton stopping powers from the planning CT and DECT Rho (relative electron density) and Z (effective atomic number) images.
- IonPlanSetup.CreateDectVerificationPlan, that can be used to evaluate the dose distribution of a proton treatment plan using DECT stopping power information.

General Improvements

The following improvements have also been made to ESAPI:

New getter properties for course were added: Course.ClinicalStatus, and Course.IsCompleted.
Improvements for Structure handling: Structure code can now be accessed and changed with the new Structure.StructureCode property, the approval status of a structure can be checked with the Structure.IsApproved property, and structure.IsCalculatedPlanExists can be used to determine if a structure is part of a plan.
It is now easier to find closed MLC leaves with the Beam::HasAllMLCLeavesClosed property.
New getter property for image was added:
- Image.ImageType: Returns a string describing the type of the calling image (for example "...\DERHOZ\RHO").

Halcyon Support

The 16.0 Eclipse Scripting API Reference Guide contained an incorrect method for adding support (couch) structures. The correct method for adding support (couch) structures is StructureSet.AddCouchStructures. The example script in section Creating Halcyon Plans is also updated accordingly.

Access to Algorithms and Models

The following improvements have also been made to ESAPI:

A new Calculation property is added to the ScriptContext, which has helpers to access the calculation models (Calculation.GetCalculationModels) and installed algorithms (ScriptContext.GetInstalledAlgorithms).
PlanSetup is extended by a DvhEstimationModelSummaries property, a GetDvhEstimationModelStructures function, and a GetDvhEstimationModelName function to provide information about the DVH estimation models.

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 two 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. 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.

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.