Creating Scripts for Eclipse Automation

You can use the Eclipse Automation features in the Eclipse Scripting API for the tasks listed in this chapter.

Adding and Modifying Structures

You can add, remove, and modify Structures by using the classes described below.

Adding and Removing Structures

Use the StructureSet class to add and remove structures:

Add structures with the AddStructure method. You can use the CanAddStructure method to check if the script is able to add a new structure to the structure set.
To specify the type of structure to add, give the string representation of the DICOM type as a parameter to the AddStructure method. Example values are EXTERNAL, ORGAN, and PTV. For a complete list of allowed values, refer to Eclipse Scripting API Online Help
Add structure code information with
```
AddStructure(StructureCodeInfo)
```
To construct StructureCodeInfo, you need to pass coding scheme and structure code, for example:
```
StructureCodeInfo scInfo = new StructureCodeInfo("99VMS_STRUCTCODE", "Support");
```
Remove structures with the RemoveStructure method.
You can convert an isodose surface to a structure. See Structure.ConvertDoseLevelToStructure

Modifying Structures

Use the Structure class to modify structures:

Add contours to a structure with the AddContourOnImagePlane method.
Input parameters:
- a list of points defining the contour, and the index
- of the image plane where the contours are to be added.
Subtract contours with the SubtractContourOnImagePlane method.
Input parameters:
- a list of points defining the contour, and the
- index of the image plane where the contours are to be subtracted.
Clear all contours for a structure with the ClearAllContoursOnImagePlane method.
Set a structure to the result of a Boolean operation with the And, Or, Not, and Xor methods. These methods are available also on the SegmentVolume class, which allows you to execute a combination of Boolean operations with an intermediate variable of the SegmentVolume type before assigning the final result to a Structure object. For more information, see the SegmentVolume property getter and setter of the Structure class.
Set a three-dimensional symmetric or asymmetric margin around a structure. First call the Margin or AsymmetricMargin method. Then set the resulting SegmentVolume object to the Structure object using the SegmentVolume property. For more information, see the get and set accessors of the SegmentVolume property of the Structure class.

Adding and Removing Artificial Phantom Images

Use the Patient class to add and remove artificial phantom images:

Add a phantom image with the AddEmptyPhantom method. Input parameters:
- patient orientation
- the size of the image set in X-and Y-directions in pixels and in millimeters
- the number of planes, and
- the separation between the planes in millimeters.
The image is created to a new Study. The return value of the AddEmptyPhantom is a new StructureSet where you can add structures and their contours. You can access the created Image using the Image property of the StructureSet class.
Remove a phantom image and associated StructureSet with the RemoveEmptyPhantom method. Input parameter:
- StructureSet. The StructureSet must not contain any Structures.
Before removing the phantom, you can use the CanRemoveEmptyPhantom method to check if the script is able to remove the phantom Image.

Copying an Image from Another Patient

Use the Patient class to copy a 3D image from another patient. This must only be used when creating Verification Plans with a script.

Specify the identifiers of the other patient, the study of the other patient, and the 3D image of the other patient. Validate the identifiers using the method CanCopyImageFromOtherPatient. Copy the image using the method CopyImageFromOtherPatient. Input parameters:
- the identifier of the other patient
- the identifier of the study of the other patient
- the identifier of the 3D image of the other patient.

Creating and Modifying Plans and Fields

You can create and modify external beam photon plans and fields by using the classes described below. For proton plans, you can only modify the scanning spot lists. Other modifications are not supported. For brachytherapy plans, no modifications are supported.

Adding and Removing Plans

Use the Course class to add and remove plans:

Add a new external beam photon plan with the AddExternalPlanSetup method. Input parameter:
- StructureSet
- A new primary reference point without a location is automatically created for the plan, or alternatively you can specify an existing reference point that will be used as primary.
You can use the CanAddPlanSetup method to check if the script is able to add a new plan to the course.
Add a new external beam photon plan as a verification plan with the AddExternalPlanSetupAsVerificationPlan method. Input parameters:
- structure set
- the verified plan.
Remove a plan with the RemovePlanSetup method. Input parameter:
- PlanSetup.
You can use CanRemovePlanSetup to check if the script is able to remove the plan from the course.

Adding Fields

Use the ExternalPlanSetup class to add fields:

Add a new static open field to the plan with the AddStaticBeam method.
Add a new arc field to the plan with the AddArcBeam method.
Add a field with static MLC shape with the AddMLCBeam or AddMLCArcBeam method.
Add an arc field with dynamic MLC shape using the AddConformalArcBeam method.
Add an IMRT field with the Multiple Static Segment delivery method using the AddMultipleStaticSegmentBeam method.
Add an IMRT field with the Sliding Windows delivery method using the AddSlidingWindowBeam method.
Add a VMAT field with the AddVMATBeam method.

Define the TreatmentMachine configuration for added fields:

Create an ExternalBeamMachineParameters object and use it as input for the above mentioned beam adding methods of the ExternalPlanSetup class. Input parameters for the ExternalBeamMachineParameters object:
- The treatment machine identifier
- energy mode identifier
- field technique identifier
- dose rate,
- and optionally, the primary fluence mode identifier.

For information about other input parameters for the beam adding methods of the ExternalPlanSetup class, refer to Eclipse Scripting API Online Help.

Modifying Fields

Use the BeamParameters class to modify a Beam:

Call the GetEditableParameters method.
Modify the returned BeamParameters object.
Call ApplyParameters. If the call succeeds, the beam data is updated.

Set the optimal fluence of an IMRT field with the SetOptimalFluence method.

Modify control points using the ControlPoints property of the BeamParameters class. Each ControlPoint has one ControlPointParameters object.
Call ApplyParameters.
If the call succeeds, the beam data is updated.

Methods to perform MLC fitting are available. See Beam.FitMLCToStructure and Beam.FitMLCToOutline.

Modifying Proton Scanning Spots

Use the IonBeamParameters class to modify the scanning spots of an IonBeam:

Call the IonBeam.GetEditableParameters method.
With the returned IonBeamParameters object, call property IonControlPointPairs to get a list of editable control point pairs.
Iterate over the list of control point pairs and get the editable spot lists using method IonControlPointPair.RawSpotList or IonControlPointPair.FinalSpotList.
Iterate over the scanning spot list and set the position or weight of each spot using setter properties IonSpotParameters.Weight, IonSpotParameters.X or IonSpotParameters.Y.
When the scanning spots have been changed as desired, call IonBeam.ApplyParameters(IonBeamParameters). If the call succeeds, the proton beam / control point / scanning spot data resident in Eclipse memory has been updated.

// unrealistic example shows how to edit the raw scanning spot lists

foreach (IonBeam ionBeam in context.IonPlanSetup.IonBeams)

{
    IonBeamParameters beamParams = ionBeam.GetEditableParameters();
    IonControlPointPairCollection cpList = beamParams.IonControlPointPairs;
    foreach (IonControlPointPair icpp in cpList)
    {
        IonSpotParametersCollection rawSpotList = icpp.RawSpotList;
        foreach (IonSpotParameters spot in rawSpotList)
        {
            spot.Weight = 1; // set weight to desired
            spot.X = 1; // set X position of scanning spot
            spot.Y = 1; // set Y position of scanning spot
        }
    }
    // apply scan spot changes to Eclipse
    ionBeam.ApplyParameters(beamParams)
}

Figure 13: Sample Script Code to Edit Raw Scanning Spots

Methods IonControlPointPair.ResizeFinalSpotList and IonControlPointPair.ResizeRawSpotList allow resizing the proton raw and final scanning spot lists.

Adding Prescriptions

Set the prescription with the SetPrescription method of the PlanSetup object.
Input parameters for the method: the number of fractions, the
- prescribed dose per fraction (using the dose unit defined for your system in the Varian Service Portal)
- prescribed percentage.

Using Calculation Algorithms

You can use the classes described below for IMRT and VMAT optimization, leaf motion calculation, and dose calculation.

Setting Calculation Models

Use the PlanSetup class to set the calculation models:

Set the calculation model with the SetCalculationModel method.
Input parameters:
- calculation type
- calculation model name.
- The current calculation model can be retrieved with the GetCalculationModel method.

Tip

All available models can be read with the GetModelsForCalculationType method of the ExternalPlanSetup class.

Set the calculation options using the SetCalculationOption method. The available options and their allowed values depend on the calculation model. Before setting the calculation options, set the calculation model.
Clear the calculation model of a plan with the ClearCalculationModel method.

Viewing Calculation Logs

Use the following classes to read the messages from the algorithms:

Beam
- Access the calculation logs after calculation with the CalculationLogs property. It returns a collection of BeamCalculationLog objects that can be filtered using the Category property. The category for the optimization log is, for example Optimization.
System.Diagnostics.Trace
- Use the Trace class of the .NET framework to receive messages from the algorithms during the calculation. For more information about how to use Trace Listeners, consult the Microsoft Developer Network (MSDN) documentation.

Executing DVH Estimation

Use the ExternalPlanSetup class for executing DVH estimation.

Run DVH estimation with the CalculateDVHEstimates method.
Input parameters:
- the identifier of the DVH estimation model
- the dose level for target structure(s) and
- the mapping between the structures of the estimation model and the structure set of the plan.
Use the Success property of OptimizerResult to check if the algorithm executed without errors.

Optimizing IMRT and VMAT Plans

Use the following classes for optimizing IMRT and VMAT plans:

Setting up the Plan

Before starting the optimization, create open fields for the plan with the AddStaticBeam or AddArcBeam method of the ExternalPlanSetup class.
Use the OptimizationSetup property of the PlanSetup class to access the OptimizationSetup object.

Adding and Modifying Optimization Objectives

Use the OptimizationSetup object to add and modify optimization objectives:

Add point objectives with the AddPointObjective method.
Add mean dose or gEUD objectives with the AddMeanDoseObjective or AddEUDObjective methods.
Add beam-specific parameters with the AddBeamSpecificParameter method.
Add a Normal Tissue Objective with the AddNormalTissueObjective method.
Remove optimization objectives with the RemoveObjective method.
Remove optimization parameters with the RemoveParameter method.

Optimizing an IMRT Plan

Use the ExternalPlanSetup class to optimize an IMRT plan:

Run the IMRT optimization algorithm with the Optimize method.
Input parameter:
- the number of needed iterations.
All existing optimal fluences are removed.
As a result of Optimize, the OptimizerResult object is returned. Use the Success property of OptimizerResult to check if the algorithm executed without errors.
You can continue IMRT optimization with the overloaded version of the Optimize method, for which you can give the OptimizationOption as a parameter. To continue optimization with existing optimal fluences, use the OptimizationOption.ContinueOptimization as a parameter.
You can continue IMRT optimization with the existing plan dose as an intermediate dose. To do this, use the overloaded version of the Optimize method, and define the OptimizationOption.ContinueOptimizationWithPlanDoseAsIntermediateDose as a parameter.
You can terminate IMRT optimization upon convergence. To do this, use the Optimize method that does not take any input parameters, or the overloaded version of the Optimize method that takes an OptimizationOptionsIMRT object as an input.
Construct the OptimizationOptionsIMRT object using the OptimizationConvergenceOption.TerminateIfConverged option.
After optimization you can read the actual number of iterations from OptimizerResult.NumberOfIMRTOptimizerIterations.
You can use intermediate dose calculation during IMRT optimization. To do this, create an OptimizationOptionsIMRT object and specify the numberOfStepsBeforeIntermediateDose. Then use the overloaded version of Optimize method that takes an OptimizationOptionsIMRT object as an input.

Optimizing a VMAT Plan

Use the ExternalPlanSetup class to optimize a VMAT plan:

Run the VMAT optimization algorithm with the OptimizeVMAT method. As a result of Optimize, the OptimizerResult object is returned. Use the Success property of OptimizerResult to check if the algorithm executed without errors.
You can use intermediate dose calculation during VMAT optimization. To do this, create an OptimizationOptionsVMAT object by specifying either the option OptimizationIntermediateDoseOption.UseIntermediateDose or the number of optimization cycles. Then use the overloaded version of method OptimizeVMAT that takes an OptimizationOptionsVMAT object as an input parameter.

Accessing Dose Volume Histograms

Use the OptimizerResult class to access the results of the optimization:

Use the StructureDVHs property to access the Dose Volume Histograms after optimization. The returned collection contains an OptimizerDVH object for each Structure that had optimization objectives defined. Use the CurveData property of the OptimizerDVH class to access the points of the Dose Volume Histogram.

Accessing Optimal Fluences after IMRT Optimization

Use the Beam class to access the optimal fluence information:

Read the optimal fluence matrix after optimization with the GetOptimalFluence method.

Using Trade-Off Exploration

Use the TradeoffExplorationContext class and its methods and properties for exploring trade-offs in plans:

Start from an optimized and calculated plan by using the TradeoffExplorationContext class.
Select the trade-off objectives by using the AddTradeoffObjective(Structure) method. At least one objective is needed.
Query if all pre-conditions to generate the plan collection are met by calling the CanCreatePlanCollection property.
If CanCreatePlanCollection is true, generate the plan collection by calling the CreatePlanCollection method.
If the plan collection is generated successfully, the HasPlanCollection property is set to true. The class is now ready for exploring different trade-offs.
To evaluate the current trade-off, use the GetObjectiveCost, CurrentDose, and GetStructureDvh methods.
To explore different trade-offs:
- Use the SetObjectiveCost method to reduce the cost of any objective.
- Use the SetObjectiveUpperRestrictor method to prevent the cost of an objective from exceeding a specified limit.
Save the trade-off exploration results by calling the ApplyTradeoffExplorationResult method. The method also applies the trade-off exploration result to the plan setup for IMRT plans.
In case of a VMAT plan, call the CreateDeliverableVmatPlan method to apply the trade-off exploration result to the plan setup.
To resume the trade-off exploration from a saved plan collection, call the LoadSavedPlanCollection method.

Calculating Leaf Motions after IMRT Optimization

Use the ExternalPlanSetup class to execute the leaf motion calculation algorithm:

Calculate leaf motions with the CalculateLeafMotions method. The method uses the default calculation options of the leaf motion calculation model set in the plan. The method returns a CalculationResult object. This object has a Success property, which you can use to check if the algorithm executed without errors.
To run the Varian Leaf Motion Calculator algorithm, use the overloaded CalculateLeafMotions method.
Input parameter
- An LMCVOptions object. In LMCVOptions you can specify the usage of fixed jaws. Check that the leaf motion calculation model of the plan is Varian Leaf Motion Calculator.
To run the Varian Smart LMC algorithm use the overloaded CalculateLeafMotions method.
Input parameter
- a SmartLMCOptions object. In `SmartLMCOptions`` you can specify the usage of fixed field borders and jaw tracking. Check that the leaf motion calculation model of the plan is Varian Smart LMC.
To run the non-Varian MSS Leaf Motion Calculator algorithm, use the overloaded CalculateLeafMotions method.
Input parameter
- an LMCMSSOptions object. In LMCMSSOptions you can specify the number of calculation iterations. Check that the leaf motion calculation model of the plan is MSS Leaf Motion Calculator.

Calculating Photon Plan Dose

Use the ExternalPlanSetup class for dose calculation:

Calculate the volume dose using the CalculateDose method. The method returns a CalculationResult object. This object has a Success property that you can use to check if the algorithm executed without errors.
Calculate the volume dose with preset MUs using the CalculateDoseWithPresetValues method. Input parameter:
- a list of Beam identifier and MeterSetValue pairs of the Beam.

Calculating Proton Plan Dose

Use the IonPlanSetup class for proton dose calculation:

Calculate the volume dose using the CalculateDose method. The method returns a CalculationResult object. This object has a Success property that you can use to check if the algorithm executed without errors.

Creating an Evaluation Dose

Use the ExternalPlanSetup or IonPlanSetup class:

Create a new EvaluationDose using the CreateEvaluationDose method. The method returns an EvaluationDose object. This object has a SetVoxels method that is called to set the content of the dose grid.
Create a new EvaluationDose using the CopyEvaluationDose method. The method copies an existing Dose and returns it as an EvaluationDose object. Use the SetVoxels method to change the content of the dose grid.

Creating Halcyon Plans

Halcyon plans have additional requirements beyond standard photon plans before they can be approved. Halcyon plans need to have imaging setups and couch structures attached before they can be considered valid.

To create a Halcyon plan with ESAPI automation

Create a plan with Course.AddExternalPlanSetup
Add an imaging setup with ExternalPlanSetup.AddImagingSetup
Insert a couch with ExternalPlanSetup.GenerateCouchStructures
Check the validity of the plan with ExternalPlanSetup.IsValidForPlanApproval. See the code sample below:

public void Execute(ScriptContext context)

{
    context.Patient.BeginModifications();
    Course c = context.Patient.AddCourse();
    c.Id = "halcyon";

    var ptv = context.StructureSet.Structures.First(s => s.DicomType == "PTV");
    var eps = c.AddExternalPlanSetup(context.StructureSet, ptv, ptv, "refpt1");
    var machineparameters = new ExternalBeamMachineParameters("Hal2_SX2_D5");
    var flat = eps.AddFixedSequenceBeam(machineparameters, 20, 45, new VVector(0, 0, 0));

    var imagingparameters = new
    ImagingBeamSetupParameters(ImagingSetup.MVCBCT_Low_Dose, 0, 0, 0, 0, 140, 140);

    eps.AddImagingSetup(machineparameters, imagingparameters, ptv);
    eps.GenerateCouchStructures("Halcyon Couch");
    eps.CalculateDose();

    IEnumerable<PlanValidationResultDetail> reasons;
    if (!eps.IsValidForPlanApproval(out reasons))
    {
        string message = "";
        foreach (PlanValidationResultDetail pvrd in reasons)
        {
            message += pvrd.MessageForUser + "\n";
        }
        MessageBox.Show("Halcyon plan is not valid for approval. Messages = \n" + message);
    }
    else
    {
        MessageBox.Show("Halcyon plan is valid for approval");
    }
}