In Eclipse, the left panel is called the scope window, and it shows you the objects you have open. These objects include the patient, courses, plans, plan sums, images, and structure sets.
You can drag and drop a plan, plan sum, image, or structure set to the main view to make it active. You can also make it active by right-clicking on it and selecting "drop to view."
In a plug-in script (see Single-File Plug-In vs. Binary Plug-In vs. Stand-Alone App), you have access to the objects that are open and active in Eclipse. These objects are accessed via a ScriptContext object, which is passed to you as a parameter in the Execute method.
In this post, I will describe in detail the ScriptContext class in ESAPI v. 13.6. Let's start by looking at its class definition (as shown by Visual Studio):
public sealed class ScriptContext
{
public ScriptContext(object context, object user, string appName);
public User CurrentUser { get; }
public Course Course { get; }
public Image Image { get; }
public StructureSet StructureSet { get; }
public Patient Patient { get; }
public PlanSetup PlanSetup { get; }
public ExternalPlanSetup ExternalPlanSetup { get; }
public BrachyPlanSetup BrachyPlanSetup { get; }
public IEnumerable<PlanSetup> PlansInScope { get; }
public IEnumerable<ExternalPlanSetup> ExternalPlansInScope { get; }
public IEnumerable<BrachyPlanSetup> BrachyPlansInScope { get; }
public IEnumerable<PlanSum> PlanSumsInScope { get; }
public string ApplicationName { get; }
public string VersionInfo { get; }
}These are the properties you have access to from your script. Notice that you can only get the values of these properties; you cannot change them. I will now describe what each of these properties represent (in a different order than above).
CurrentUser
CurrentUser represents the user that is logged in to Eclipse and started the script. The only thing useful I found in this class is the user's ID. The user's name, which I've needed before, is unfortunately not available. If you need it, you can use the ARIA database directly (see Access the ARIA Database with the Entity Framework).
Patient
Patient represents the opened patient. With the Patient object, you can access all of his or her courses, plans, images, and structure sets, regardless of whether they're open in Eclipse. In many cases, though, you want to use what's in the ScriptContext because this is what the user has open and is most likely interested in.
In Eclipse, it's possible to run a plug-in script without an opened patient. In this case, Patient has a value of null. Therefore, if your script uses any patient information, it's a good idea to check whether Patient is null. Otherwise, you may access a null value, which crashes your script and shows the user the following confusing error message:
(Image to be added.)
In a plug-in script, you have access to only one patient. If you need access to more than one patient, you need to create a stand-alone script (see Single-File Plug-In vs. Binary Plug-In vs. Stand-Alone App).
Course
Course represents the active course. In most cases, this is the course of the plan that is active. Like the patient, you're not required to have any courses or plans open in Eclipse. In this case, Course will be null.
As I mentioned above, you have access to all the patient's courses via the Patient object. Therefore, you can write a script that analyzes all courses (and containing plans) without the need to have anything open other than the patient.
PlanSetup
PlanSetup is the active plan. It may be null if there aren't any plans open. PlanSetup may represent an external beam plan or a brachytherapy plan, depending on what is active.
ExternalPlanSetup and BrachyPlanSetup
If the active plan is an external beam plan, ExternalPlanSetup returns the same object as PlanSetup but as type ExternalPlanSetup. If the active plan is not an external beam plan, ExternalPlanSetup is null.
Similarly, if the active plan is a brachytherapy plan, BrachyPlanSetup returns the same object as PlanSetup but as type BrachyPlanSetup. Otherwise, BrachyPlanSetup is null.
These are convenience properties that are not strictly needed. They're equivalent to:
var externalPlan = context.PlanSetup as ExternalPlanSetup;
var brachyPlan = context.PlanSetup as BrachyPlanSetup;The reason you may want to access the active plan as a specific type is that ExternalPlanSetup and BrachyPlanSetup have specific properties that apply to only that type of plan. For example, the property Catheters is only available in the BrachyPlanSetup class, not in ExternalPlanSetup or in the generic PlanSetup.
The generic PlanSetup has properties that apply to all plan types (e.g., the property TotalPrescribedDose). Therefore, if it's not important whether you're dealing with an external beam plan or a brachytherapy plan, you can just use PlanSetup.
PlansInScope
PlansInScope represents all the plans from all courses that are open in Eclipse, including the plan that is active. The documentation doesn't specify the order they're in, so don't assume any specific order. If you want to sort them in a specific way, use the C# OrderBy method. For example:
// Sort plans alphabetically by ID
var plans = context.PlansInScope.OrderBy(p => p.Id));
// Sort plans by creation date/time
var plans = context.PlansInScope.OrderBy(p => p.CreationDateTime));ExternalPlanSetups and BrachyPlanSetups
ExternalPlanSetups and BrachyPlanSetups are convenience properties that contain the opened plans of a specific type (external beam or brachytherapy plans).
PlanSumsInScope
PlanSumsInScope represent all the plan sums from all courses that are open in Eclipse. Again, you also have access to all the plan sums that are not open, but you have to go through the Patient and Course objects.
Interestingly, there's no PlanSum property in ScriptContext that accesses the active plan sum. This is odd because you're able to make a plan sum active in Eclipse by dropping it to the main view. This limitation may be a remnant from previous versions of Eclipse, where it was not possible to make a plan sum active.
Image
Image represents the active image in Eclipse. Usually, this is the image of the active plan. But Eclipse lets you open an image without opening a plan. The Image property will give you access to this image even if nothing else (other than the patient) is open. As with other properties, if there's no active image, the Image property is null.
StructureSet
StructureSet represents the active structure set in Eclipse. In most cases, this is the structure set of the active plan. Similar to the image, Eclipse lets you open a structure set without having to open a plan. Structure sets have a related image, so the Image property in the ScriptContext will also be available when a StructureSet is present.
ApplicationName
For ApplicationName, the ESAPI documentation says, "The name of the active application." In Eclipse, this value is "External Beam Planning." But isn't the active application always Eclipse? Apparently not.
I couldn't find a list of the applications in which you can run an ESAPI script, so I tried several myself. I found that the following applications worked: Brachytherapy Planning, Brachytherapy 2D Entry, and Plan Evaluation. In each case, ApplicationName correctly returned the name of the application.
Other applications, such as Contouring and Portal Dosimetry, were not able to run ESAPI scripts. However, they do have their own API.
VersionInfo
VersionInfo represents the version of Eclipse where the script was started. This value may be useful if your script depends on a specific Eclipse version and you want to alert the user if they're not running the correct version.
Final Thoughts
If you're running a version of Eclipse older than 13.6, some of the properties I discussed here won't be available. However, the properties that are available in previous versions should represent the same things I described.
If you're going to use the EclipsePlugInRunner to test your scripts from Visual Studio (see Run and Test Plug-In Scripts from Visual Studio), you won't be able to use the ScriptContext directly. But that's OK because you have access to the individual properties of the ScriptContext passed as parameters to your main method.
Comments