TrajectoryLog.NET Part I: Introducing TrajectoryLog.NET

TrajectoryLog.NET is an open an open-source C# API to interpret the binary trajectory log files written by the Varian linear accelerators during treatment delivery. Here we will introduce the API and the methods available for reporting trajectory log file information.

Introduction to Linear Accelerator Machine Logs

Log files written by clinical linear accelerators in radiation oncology have been utilized for various purposes over the years from the evaluation of machine delivery accuracy during patient-specific quality assurance measurements and through the patient treatment verification. The Varian TrueBeam Linear Accelerator and the Varian Halcyon Linear Accelerator generate a new set of log data into each beam delivery log file every 20ms (one written log for every two machine control point logs). One the beam has completed delivery, this log file is packaged into a single binary file and stored on a transfer folder accessible to the clinician and engineers. These files are named trajectory logs. The trajectory logs have information about all physical axes of the machine that can vary during treatment (e.g. jaw positions, gantry rotation angle, MLC positions) and dosimetric components such as the monitor unit value at each control point.

The Varian TrueBeam Linear Accelerator and the Varian Halcyon Linear Accelerator generate a new set of log data into each beam delivery log file every 20ms (one written log for every two machine control point logs).

The interpretation of these trajectory log files requires the known schema of the binary file, which is published by Varian, and that schema, along with a little bit of trial and error can interpret the binary file properly. Popular libraries currently exist for the interpretation of the binary file logs. Pylinac is a popular log file interpretation library for python. Pylinac has many built-in methods for the comparison of expected and actual motion axes, and generation of read-able file formats such as CSV or PDF.

There are other reliable and useful libraries, but the need for TrajectoryLog.NET stems from integration of trajectory log file reading with the .NET environment of the Eclipse Scripting API and the Portal Dosimetry Scripting API.

Accessing TrajectoryLog.NET

The TrajectoryLog.NET API can be accessed through GitHub using the link here. In the upper right, click on the green code button, and copy the path of the repository.

Open Visual Studio and choose the option Clone A Repository. Paste the path of the repository and select a location to which to clone the repository. Click Clone and the GitHub project will be cloned to your local machine.

This project was built to target version 15.6 of the Eclipse Scripting API (ESAPI). If planning to use another version of ESAPI, the .NET Framework target version may need to be changed in the project properties. Please feel free to target the .NET framework version to match any ESAPI projects where trajectory log file analysis will be useful. Finally, compile the project from the build menu.

For version 16.1, change the .NET Target Framework Version to .NET framework 4.6.1. .NET Framework 4.8 is appropriate for ESAPI V18.

Building the Client

Next, we will build a client to test the public methods of the API. This can be done as a stand-alone application disconnected from ESAPI or PDSAPI for the moment. All that is needed is a single trajectory log file.

Open a new instance of Visual Studio, and select the option Create a new project. For this application, the project type Console App (.NET Framework) is selected. In this example, the project is named TrajectoryTestClient and the .NET Framework is set to the same .NET Framework used to compile the open-source API source-code.

In this test client, first add the TrajectoryLog.NET API to your project references. In the Main method of the console, add the following code to open a trajectory log file. The using directives needed to enable this code are the Microsoft.Win32 (for access to OpenFileDialog) and the TrajectoryLog.NET and TrajectoryLog.NET.TrajectorySpecifications to call the API and instantiate variables, respectively. Note that the EnableDebug() method is first called in order to call back the trajectory reading to the console. At the end of the block of code, place a Console.ReadLine() to pause the code to review the output. Also note when using the OpenFileDialog, the STAThread attribute must be added above the Main method.

[STAThread]
static void Main(string[] args)
        {
            OpenFileDialog ofd = new OpenFileDialog();
            ofd.Filter = "Trajectory Log File (*.bin)|*.bin";
            TrajectoryAPI.EnableDebug();
            TrajectoryLogInfo localLog = null;
            if (ofd.ShowDialog() == true)
            {
                localLog = TrajectoryAPI.LoadLog(ofd.FileName);
            }
            Console.ReadLine();
        }

When running the code, a dialog should appear and request the opening of a trajectory log file. These outputs are coming directly from the LoadLog() method as it reads through the binary file and sorts the data into the appropriate collections. Select the file and notice the real time reading of the trajectory file.

Without seriously debugging the application, it is challenging to gain any information about the delivery from the streaming control point positions. One method that can help the user evaluate the trajectories in the file is the ToCSV() method.

Console.WriteLine("Do you want to write .csv? (y/n)");
            if (Console.ReadLine().Trim().Equals("y", 				StringComparison.OrdinalIgnoreCase))
            {                
				TrajectoryAPI.ToCSV(localLog);
            }

On the user agreement by pressing "y" in the console, the trajectory log will be written to a CSV file. This file can be opened in Microsoft Excel or any other software that delimits comma separated value files. This technique can assist in gathering readable data for plotting, analysis, or storage.

Finally, the TrajectoryLog.NET API can provide a simple PDF report of the page analysis. To accomplish this, write the following line to include the PublishPDF() method in the bottom of the Main method.

TrajectoryAPI.PublishPDF(localLog);

This report contains maximum deviations and RMS value discrepancies across all control points for the gantry, MU, and MLC expected vs actual. There are also 2 images of the expected fluence and actual fluence built from the MLC positions and the relative MU delivered through the openings of those MLC positions.

Please note that trajectory log files do contain patient identifying information in both the filename (filenames start with the patient ID) and within the metadata of the file as well. The files written with the PDF report and the CSV output do not contain this patient identifying information (unless that information is in the Field ID printed at the top of the report).

There are some limitations currently to the TrajectoryLog.NET API methods. For instance, the fluence images included in the PDF do not include the jaw positions. Therefore, where the jaws are closed and no fluences is expected, the report may still show fluence. Please note that trajectory log files do contain patient identifying information in both the filename (filenames start with the patient ID) and within the metadata of the file as well. The files written with the PDF report and the CSV output do not contain this patient identifying information (unless that information is in the Field ID printed at the top of the report).

Conclusion

TrajectoryLog.NET is a convenient API for the interpretation of Varian machine trajectory log files in the .NET Framework, helping with compatibility to ESAPI and portal dosimetry applications. In this blog post, we have explored methods of interpreting the TrajectoryLog.NET API and some of its methods.

In a future blog post, the BuildFluence() method will also be introduced with some practical examples of how fluences can be displayed within a WPF application and compared with another fluence either from trajectory information or planning information.