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 see AddStructure.

To construct StructureCodeInfo, you need to pass coding scheme and structure code, for example:

StructureCodeInfo scInfo = new StructureCodeInfo("99VMS_STRUCTCODE", "Support");

Modifying Structures

Use the Structure class to modify structures:

Input parameters:

  • List of points defining the contour
  • index of the image plane where the contours are to be added.

Input parameters:

  • List of points defining the contour
  • Index of the image plane where the contours are to be subtracted.

These methods are also available in 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:

Input parameters:

  • Patient orientation
  • Size of the image set in X- and Y-directions in pixels and in millimeters
  • Number of planes
  • Separation between the planes in millimeters.

An image is created into 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.

Input parameter:

  • StructureSet, The set must be empty.

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.

Input parameters:

  • Identifier of the other patient
  • Identifier of the study of the other patient
  • 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, as well as brachytherapy plans and applicators by using the classes described below. For brachytherapy plans, no additions or modifications are supported for solid applicators or seed collections.

Adding and Removing Plans

Use the Course class to add and remove plans:

Input parameter:

  • Structure set
  • Target structure (optional)
  • Primary reference point (optional)

  • If a target structure is not defined target structure is picked from structure set target volumes.

  • If a primary reference point is not passed as an argument a new primary reference point without a location is automatically created for the plan.

You can use the CanAddPlanSetup method to check if the script is able to add a new plan to the course.

Input parameters:

  • Structure set
  • Plan to verify

Input parameter:

You can use CanRemovePlanSetup to check if the script is able to remove the plan from the course.

  • Copy an external beam plan with CopyPlanSetup to create a plan in another image that is not registered.

  • Add a new brachytherapy plan with the AddBrachyPlanSetup method.

Input parameters:

Optionally

  • TargetStructure to be set as the target structure for the plan
  • PrimaryReferencePoint to set an existing reference point to be used as the primary reference point instead of creating a new one.

If not specified a new primary reference point without a location is automatically created for the plan. The CanAddPlanSetup method can be used to check if the script is able to add a new plan to the course.

Modifying Brachytherapy Plan Properties

Adding Reference Points in Brachytherapy Plans

Use the BrachyPlanSetup class to add reference points:

Input parameters:

  • location: The location of the reference point.
  • id: The identifier of the reference point.
  • Add a new reference point to a brachytherapy plan with the AddReferencePoint method.

Input parameters:

  • target: Indicates whether the reference point tracks treatment target (true) or organ at risk (false).
  • id: The identifier of the reference point.

Copying a Brachytherapy Plan to a New Image

Use the Course class to copy a brachytherapy plan to a new image:

  • Copy a brachytherapy plan with Course.CopyBrachyPlanSetup. The target image must be registered with the primary image of the source plan.

Adding Reference Lines

Add a new reference line to a structure set using the StructureSet.AddReferenceLine method.

Input parameters:

  • name: The name of the reference line.
  • id: The identifier of the reference line.
  • referenceLinePoints: The points of the reference line.

Adding Fields

Use the ExternalPlanSetup class to add photon fields:

Define the treatment machine configuration for added fields:

Input parameters:

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

Use the IonPlanSetup.AddModulatedScanningBeam to add modulated scanning fields to a proton plan.

Modifying Photon Fields

Use the BeamParameters class to modify a Beam:

Modifying Proton Fields

The following can be adjusted in a proton field:

Modifying Proton Scanning Spots

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

// 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

Modifying Proton Range Shifter Settings

Use the IonBeamParameters class to modify the range shifter settings of an IonBeam:

  • Call the IonBeam.GetEditableParameters method.

  • With the returned IonBeamParameters object, access property PreSelectedRangeShifter1Id/PreSelectedRangeShifter2Id to set the range shifter IDs and property PreSelectedRangeShifter1Setting /PreSelectedRangeShifter2Setting to set the range shifter settings.

When the range shifter settings have been changed as desired, call IonBeam.ApplyParameters(IonBeamParameters). If the call succeeds, range shifter beam line modifier settings have been updated.

DECT Features for Proton Plans

You can use the following Dual-Energy CT (DECT) specific methods:

Adding Field and Plan Uncertainty for Photon and Proton Plans

You can add new plan or field uncertainties with parameters. Supported uncertainty types are:

Field-specific plan uncertainty dose can be used only for RobustOptimizationUncertainty. In case of field-specific uncertainty, HUConversionError is overwritten to be always zero. In case of BaselineShiftUncertainty, the isocenterShift parameter is actually the target shift.

Functions to call to set plan or field uncertainties with parameters:

PlanSetup.AddPlanUncertaintyWithParameters(PlanUncertaintyType planUncertaintyType, bool planSpecificUncertainty, double HUConversionError, VVector isocenterShift)

For protons:

IonPlanSetup.AddPlanUncertaintyWithParameters(PlanUncertaintyType planUncertaintyType, bool planSpecificUncertainty, double HUConversionError, VVector isocenterShift)

Parameters example:

planUncertaintyType = PlanUncertaintyType.RangeUncertainty planSpecificUncertainty = true, The plan uncertainty dose is either plan-specific (true) or field-specific (false). HUConversionError = 3.0, Unit is %. isocenterShift = new VVector(0.3, 0.4, 0.5), Unit is cm.

Adding Brachytherapy Applicators and Seeds

Use the BrachyPlanSetup class to add brachy applicators:

  • Add a new applicator to the brachytherapy plan with the AddCatheter method.

Input parameters:

  • catheterId: a string defining the ID of the new applicator.
  • treatmentUnit: an object defining the brachy treatment unit for the applicator.
  • outputDiagnostics : A list of messages populated by the system to inform about the possible consequences of adding the applicator.
  • appendChannelNumToId: If true, the channel number is appended to the applicatorID. If false, the channel number is not included in the applicator ID.
  • channelNum: sets the channel number of the applicator with the given number.

The accepted range is from 1 to the maximum number of channels defined for the brachy unit in RT Administration.If the provided channel number is 0, the next available free channel number is assigned to the applicator. If the provided channel number is -1, the channel number is left empty.

  • Adding new solid applicator or seed collection is not supported yet. Applicators with different treatment units cannot be added in the same plan.

Modifying Brachytherapy Applicators

Use the Catheter class to modify brachytherapy applicators.

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

  • Applicator source positions can be accessed with (read only)

  • Source positions can be set with Catheter.SetSourcePositions method. Calling this method will also automatically recalculate the source positions.

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

  • 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 get through the new Equipment class, with the Equipment.GetBrachyTreatmentUnits method.

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

  • The ID property of class Catheter can now be set with the Catheter.SetID method. The ID must be unique within the plan. If not, the ID is not changed.

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

Input parameter:

  • RefLine (reference line to link with an applicator).

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

Input parameter:

  • RefPoint (reference point to link with an applicator).

Adding Prescriptions

  • Set the prescription with the SetPrescription method of the PlanSetup object.

Input parameters:

  • Number of fractions
  • Prescribed dose per fraction (using the dose unit defined for your system in the Varian Service Portal,
  • Prescribed percentage.

Using External Beam 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:

Input parameters:

  • Calculation type
  • Calculation model name.

The current calculation model can be retrieved with the GetCalculationModel method. 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:

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. 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 or IonPlanSetup class for executing DVH estimation.

Input parameters:

  • Identifier of the DVH estimation model
  • Dose level for target structure(s)
  • 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:

Optimizing an IMRT Plan

Use the ExternalPlanSetup class to optimize an IMRT plan:

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.

After optimization you can read the actual number of iterations from OptimizerResult.NumberOfIMRTOptimizerIterations.

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:

  1. Start from an optimized and calculated plan by using the TradeoffExplorationContext class.

  2. Select the trade-off objectives by using the AddTradeoffObjective(Structure) method. At least one objective is needed.

  3. Query if all pre-conditions to generate the plan collection are met by calling the CanCreatePlanCollection property.

  4. If CanCreatePlanCollection is true, generate the plan collection by calling the CreatePlanCollection method.

  5. If the plan collection is generated successfully, the HasPlanCollection property is set to true. The class is now ready for exploring different trade-offs.

  6. To evaluate the current trade-off, use the GetObjectiveCost, CurrentDose, and GetStructureDvh methods.

  7. To explore different trade-offs:

  1. 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.
  2. In case of a VMAT plan, call the CreateDeliverableVmatPlan method to apply the trade-off exploration result to the plan setup.
  3. 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:

  • 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:

  • 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:

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

Calculating Proton Plan Dose

Use the IonPlanSetup class for proton dose calculation:

Additionally, the proton plan has the following new methods:

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:

  1. Create a plan with Course.AddExternalPlanSetup
  2. Add imaging setup with ExternalPlanSetup.AddImagingSetup
  3. Insert couch with StructureSet.AddCouchStructures.
  4. 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);
    
    IReadOnlyList<Structure> addedStructures;    
    bool imageResized;
    
    context.StructureSet.AddCouchStructures("RDS_Couch_Top", PatientOrientation.HeadFirstSupine, RailPosition.In, RailPosition.In, null, null, null, out addedStructures, out imageResized, out error);
    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");
    }
}

Figure 14 Additional Halcyon setup

Using Brachytherapy Calculation Algorithms

You can use the methods described below for the dose calculation of brachytherapy plans.

Calculating Brachytherapy Plan Dose

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.

  • The CalculateTG43Dose method returns a CalculateBrachy3DDoseResult object that indicates if the operation was successful or not in the Success property.

  • For a successful dose calculation the RoundedDwellTimeAdjustRatio property indicates how the much the dwell times where adjusted. A value of zero (0.0) indicates that dwell times where not adjusted.

  • If the dose calculation was not successful, the reason(s) for the failure is included in the Errors property.