The Winston-Lutz module loads and processes EPID images that have acquired Winston-Lutz type images.


  • Couch shift instructions - After running a WL test, get immediate feedback on how to shift the couch. Couch values can also be passed in and the new couch values will be presented so you don’t have to do that pesky conversion. “Do I subtract that number or add it?”
  • Automatic field & BB positioning - When an image or directory is loaded, the field CAX and the BB are automatically found, along with the vector and scalar distance between them.
  • Isocenter size determination - Using backprojections of the EPID images, the 3D gantry isocenter size and position can be determined independent of the BB position. Additionally, the 2D planar isocenter size of the collimator and couch can also be determined.
  • Image plotting - WL images can be plotted separately or together, each of which shows the field CAX, BB and scalar distance from BB to CAX.
  • Axis deviation plots - Plot the variation of the gantry, collimator, couch, and EPID in each plane as well as RMS variation.
  • File name interpretation - Rename DICOM filenames to include axis information for linacs that don’t include such information in the DICOM tags. E.g. “myWL_gantry45_coll0_couch315.dcm”.

Running the Demo

To run the Winston-Lutz demo, create a script or start an interpreter session and input:

from pylinac import WinstonLutz

Results will be printed to the console and a figure showing the zoomed-in images will be generated:

Winston-Lutz Analysis
Number of images: 17
Maximum 2D CAX->BB distance: 1.23mm
Median 2D CAX->BB distance: 0.69mm
Shift to iso: facing gantry, move BB: RIGHT 0.36mm; OUT 0.36mm; DOWN 0.20mm
Gantry 3D isocenter diameter: 1.05mm (9/17 images considered)
Maximum Gantry RMS deviation (mm): 1.03mm
Maximum EPID RMS deviation (mm): 1.31mm
Gantry+Collimator 3D isocenter diameter: 1.11mm (13/17 images considered)
Collimator 2D isocenter diameter: 1.09mm (7/17 images considered)
Maximum Collimator RMS deviation (mm): 0.79
Couch 2D isocenter diameter: 2.32mm (7/17 images considered)
Maximum Couch RMS deviation (mm): 1.23

(Source code, png, hires.png, pdf)


Image Acquisition

The Winston-Lutz module will only load EPID images. The images can be from any EPID however, and any SID. To ensure the most accurate results, a few simple tips should be followed. Note that these are not unique to pylinac; most Winston-Lutz analyses require these steps:

  • The BB should be fully within the field of view.
  • The MLC field should be symmetric.
  • The BB should be <2cm from the isocenter.

Coordinate Space


In pylinac 2.3, the coordinates changed to be compliant with IEC 61217. Compared to previous versions, the Y and Z axis have been swapped. The new Z axis has also flipped which way is positive.

When interpreting results from a Winston-Lutz test, it’s important to know the coordinates, origin, etc. Pylinac uses IEC 61217 coordinate space. Colloquial descriptions are as if standing at the foot of the couch looking at the gantry.

  • X-axis - Lateral, or left-right, with right being positive.
  • Y-axis - Superior-Inferior, or in-out, with sup/in being positive.
  • Z-axis - Anterior-Posterior, or up-down, with up/anterior being positive.

Typical Use

Analyzing a Winston-Lutz test is simple. First, let’s import the class:

from pylinac import WinstonLutz

From here, you can load a directory:

my_directory = 'path/to/wl_images'
wl = WinstonLutz(my_directory)

You can also load a ZIP archive with the images in it:

wl = WinstonLutz.from_zip('path/to/')

Now, analyze it:


And that’s it! You can now view images, print the results, or publish a PDF report:

# plot all the images
# plot an individual image
# save a figure of the image plots
# print to PDF

If you want to shift the BB based on the results and perform the test again there is a method for that:

# LEFT: 0.1mm, DOWN: 0.22mm, ...

You can also pass in your couch coordinates and the new values will be generated:

print(wl.bb_shift_instructions(couch_vrt=0.41, couch_lng=96.23, couch_lat=0.12))
New couch coordinates (mm): VRT: 0.32; LNG: 96.11; LAT: 0.11

Accessing data

Changed in version 3.0.

Using the WL module in your own scripts? While the analysis results can be printed out, if you intend on using them elsewhere (e.g. in an API), they can be accessed the easiest by using the results_data() method which returns a WinstonLutzResult instance.


While the pylinac tooling may change under the hood, this object should remain largely the same and/or expand. Thus, using this is more stable than accessing attrs directly.

Continuing from above:

data = wl.results_data()
# and more

# return as a dict
data_dict = wl.results_data(as_dict=True)

Accessing individual images

Each image can be plotted and otherwise accessed easily:

wl = WinstonLutz(...)
# access first image
wl.images[0]  # these are subclasses of the pylinac.core.image.DicomImage class, with a few special props
# plot 3rd image
wl.images[0].plot()  # the plot method is special to the WL module and shows the BB, EPID, and Field CAX.
# get 2D x/y vector of an image
wl.images[4].cax2bb_vector  # this is a Vector with a .x and .y attribute. Note that x and y are in respect to the image, not the fixed room coordinates.

Analyzing a single image

You may optionally analyze a single image if that is your preference. Obviously, no 3D computations are performed.


This is the same class used under the hood for the WinstonLutz images, so any attribute you currently use with something like wl.images[2].cax2bb_vector will work for the below with a direct call: wl2d.cax2bb_vector.

from pylinac import WinstonLutz2D

wl2d = WinstonLutz2D("my/path/...")
wl2d.analyze(bb_size_mm=4)  # same as WinstonLutz class

This class does not have all the methods that WinstonLutz has for mostly obvious reasons and lower likelihood of being used directly.

Using File Names

If your linac EPID images do not include axis information (such as Elekta) you can specify it in the file name. Any and all of the three axes can be defined. If one is not defined and is not in the DICOM tags, it will default to 0. The syntax to define the axes: “<*>gantry0<*>coll0<*>couch0<*>”. There can be any text before, after, or in between each axis definition. However, the axes numerical value must immediately follow the axis name. Axis names are also fixed. The following examples are valid:

  • MyWL-gantry0-coll90-couch315.dcm
  • gantry90_stuff_coll45-couch0.dcm
  • abc-couch45-gantry315-coll0.dcm
  • 01-gantry0-abcd-coll30couch10abc.dcm
  • abc-gantry30.dcm
  • coll45abc.dcm

The following are invalid:

  • mywl-gantry=0-coll=90-couch=315.dcm
  • gan45_collimator30-table270.dcm

Using the filenames within the code is done by passing the use_filenames=True flag to the init method:

my_directory = 'path/to/wl_images'
wl = WinstonLutz(my_directory, use_filenames=True)


If using filenames any relevant axes must be defined, otherwise they will default to zero. For example, if the acquisition was at gantry=45, coll=15, couch=0 then the filename must include both the gantry and collimator in the name (<…gantry45…coll15….dcm>). For this example, the couch need not be defined since it is 0.

Changing BB detection size

To change the size of BB pylinac is expecting you can pass the size to the analyze method:

import pylinac

wl = WinstonLutz(...)

Image types & output definitions

The following terms are used in pylinac’s WL module and are worth defining.

Image axis definitions/Image types Images are classified into 1 of 6 image types, depending on the position of the axes. The image type is then used for determining whether to use the image for the given calculation. Image types allow the module to isolate the analysis to a given axis if needed. E.g. for gantry iso size, as opposed to overall iso size, only the gantry should be moving so that no other variables influence it’s calculation.

  • Reference: This is when all axes are at value 0 (gantry=coll=couch=0).
  • Gantry: This is when all axes but gantry are at value 0, e.g. gantry=45, coll=0, couch=0.
  • Collimator: This is when all axes but collimator are at value 0.
  • Couch: This is when all axes but the couch are at value 0.
  • GB Combo: This is when either the gantry or collimator are non-zero but the couch is 0.
  • GBP Combo: This is where the couch is kicked and the gantry and/or collimator are rotated.

Analysis definitions Given the above terms, the following calculations are performed.

  • Maximum 2D CAX->BB distance (scalar, mm): Analyzes all images individually for the maximum 2D distance from rad field center to the BB.
  • Median 2D CAX->BB distance (scalar, mm): Same as above but the median.
  • Shift of BB to isocenter (vector, mm): The instructions of how to move the BB/couch in order to place the BB at the determined isocenter.
  • Gantry 3D isocenter diameter (scalar, mm): Analyzes only the gantry axis images (see above image types). Applies backprojection of the CAX in 3D and then minimizes a sphere that touches all the 3D backprojection lines.
  • Gantry+Collimator 3D isocenter diameter (scalar, mm): Same as above but also considers Collimator and GB Combo images.
  • [Couch, Collimator] 2D isocenter diameter (scalar, mm): Analyzes only the collimator or couch images to determine the size of the isocenter according to the axis in question. The maximum distance between any of the points is the isocenter size. The couch and collimator are treated separately for obvious reasons. If no images are given that rotate about the axis in question (e.g. cardinal gantry angles only) the isocenter size will default to 0.
  • [Maximum, All][Gantry, Collimator, Couch, GB Combo, GBP Combo, EPID] RMS deviation (array of scalars, mm): Analyzes the images for the axis in question to determine the overall RMS inclusive of all 3 coordinate axes (vert, long, lat). I.e. this is the overall displacement as a function of the axis in question. For EPID, the displacement is calculated as the distance from image center to BB for all images with couch=0. If no images are given that rotate about the axis in question (e.g. cardinal gantry angles only) the isocenter size will default to 0.


The Winston-Lutz algorithm is based on the works of Winkler et al, Du et al, and Low et al. Winkler found that the collimator and couch iso could be found using a minimum optimization of the field CAX points. They also found that the gantry isocenter could by found by “backprojecting” the field CAX as a line in 3D coordinate space, with the BB being the reference point. This method is used to find the gantry isocenter size.

Low determined the geometric transformations to apply to 2D planar images to calculate the shift to apply to the BB. This method is used to determine the shift instructions. Specifically, equations 6 and 9.


If doing research, it is very important to note that Low implicitly used the “Varian” coordinate system. This is an old coordinate system and any new Varian linac actually uses IEC 61217. However, because the gantry and couch definitions are different, the matrix definitions are technically incorrect when using IEC 61217. Pylinac assumes the images are in IEC 61217 scale and will internally convert it to varian scale to be able to use Low’s equations. The gantry is also reversed in Varian scale, but this can be compensated by simply reversing the sign of the Z axis.

The algorithm works like such:


  • The images can be acquired with any EPID (aS500, aS1000, aS1200) at any SID.
  • The BB does not need to be near the real isocenter to determine isocenter sizes, but does affect the 2D image analysis.



Analysis can fail or give unreliable results if any Restriction is violated.

  • The BB must be fully within the field of view.
  • The BB must be within 2.0cm of the real isocenter.
  • The images must be acquired with the EPID.
  • The linac scale should be IEC 61217.


  • Find the field CAX – The spread in pixel values (max - min) is divided by 2, and any pixels above the threshold is associated with the open field. The pixels are converted to black & white and the center of mass of the pixels is assumed to be the field CAX.
  • Find the BB – The image is converted to binary based on pixel values both above the 50% threshold as above, and below the upper threshold. The upper threshold is an iterative value, starting at the image maximum value, that is lowered slightly when the BB is not found. If the binary image has a reasonably circular ROI, the BB is considered found and the pixel-weighted center of mass of the BB is considered the BB location.


Strictly speaking, the following aren’t required analyses, but are explained for fullness and clarity.

  • Backproject the CAX for gantry images – Based on the vector of the BB to the field CAX and the gantry angle, a 3D line projection of the CAX is constructed. The BB is considered at the origin. Only images where the couch was at 0 are used for CAX projection lines.
  • Determine gantry isocenter size - Using the backprojection lines, an optimization function is run to minimize the maximum distance to any line. The optimized distance is the isocenter radius.
  • Determine collimator isocenter size - The maximum distance between any two field CAX locations is calculated for all collimator images.
  • Determine couch isocenter size - Instead of using the BB as the non-moving reference point, which is now moving with the couch, the Reference image (gantry = collimator = couch = 0) CAX location is the reference. The maximum distance between any two BB points is calculated and taken as the isocenter size.


Collimator iso size is always in the plane normal to the gantry, while couch iso size is always in the x-z plane.

API Documentation

class pylinac.winston_lutz.WinstonLutz(directory: str, use_filenames: bool = False)[source]

Bases: object

Class for performing a Winston-Lutz test of the radiation isocenter.

  • directory (str) – Path to the directory of the Winston-Lutz EPID images.
  • use_filenames (bool) – Whether to try to use the file name to determine axis values. Useful for Elekta machines that do not include that info in the DICOM data.
images = None
classmethod from_demo_images()[source]

Instantiate using the demo images.

classmethod from_zip(zfile: Union[str, BinaryIO], use_filenames: bool = False)[source]

Instantiate from a zip file rather than a directory.

  • zfile – Path to the archive file.
  • use_filenames (bool) – Whether to interpret axis angles using the filenames. Set to true for Elekta machines where the gantry/coll/couch data is not in the DICOM metadata.
classmethod from_url(url: str, use_filenames: bool = False)[source]

Instantiate from a URL.

  • url (str) – URL that points to a zip archive of the DICOM images.
  • use_filenames (bool) – Whether to interpret axis angles using the filenames. Set to true for Elekta machines where the gantry/coll/couch data is not in the DICOM metadata.
static run_demo()[source]

Run the Winston-Lutz demo, which loads the demo files, prints results, and plots a summary image.

analyze(bb_size_mm: float = 5)[source]

Analyze the WL images.

Parameters:bb_size_mm – The expected size of the BB in mm. The actual size of the BB can be +/-2mm from the passed value.

The diameter of the 3D gantry isocenter size in mm. Only images where the collimator and couch were at 0 are used to determine this value.


The diameter of the 3D gantry isocenter size in mm including collimator and gantry/coll combo images. Images where the couch!=0 are excluded.


The 2D collimator isocenter size (diameter) in mm. The iso size is in the plane normal to the gantry.


The diameter of the 2D couch isocenter size in mm. Only images where the gantry and collimator were at zero are used to determine this value.


The shift necessary to place the BB at the radiation isocenter. The values are in the coordinates defined in the documentation.

The shift is based on the paper by Low et al. See online documentation for more.

bb_shift_instructions(couch_vrt: Optional[float] = None, couch_lng: Optional[float] = None, couch_lat: Optional[float] = None) → str[source]

Returns a string describing how to shift the BB to the radiation isocenter looking from the foot of the couch. Optionally, the current couch values can be passed in to get the new couch values. If passing the current couch position all values must be passed.

  • couch_vrt (float) – The current couch vertical position in cm.
  • couch_lng (float) – The current couch longitudinal position in cm.
  • couch_lat (float) – The current couch lateral position in cm.
axis_rms_deviation(axis: pylinac.winston_lutz.Axis = <Axis.GANTRY: 'Gantry'>, value: str = 'all') → Union[Iterable[T_co], float][source]

The RMS deviations of a given axis/axes.

  • axis (('Gantry', 'Collimator', 'Couch', 'Epid', 'GB Combo', 'GBP Combo'}) – The axis desired.
  • value ({'all', 'range'}) – Whether to return all the RMS values from all images for that axis, or only return the maximum range of values, i.e. the ‘sag’.
cax2bb_distance(metric: str = 'max') → float[source]

The distance in mm between the CAX and BB for all images according to the given metric.

Parameters:metric ({'max', 'median'}) – The metric of distance to use.
cax2epid_distance(metric: str = 'max') → float[source]

The distance in mm between the CAX and EPID center pixel for all images according to the given metric.

Parameters:metric ({'max', 'median'}) – The metric of distance to use.
plot_axis_images(axis: pylinac.winston_lutz.Axis = <Axis.GANTRY: 'Gantry'>, show: bool = True, ax: Optional[matplotlib.axes._axes.Axes] = None)[source]

Plot all CAX/BB/EPID positions for the images of a given axis.

For example, axis=’Couch’ plots a reference image, and all the BB points of the other images where the couch was moving.

  • axis ({'Gantry', 'Collimator', 'Couch', 'GB Combo', 'GBP Combo'}) – The images/markers from which accelerator axis to plot.
  • show (bool) – Whether to actually show the images.
  • ax (None, matplotlib.Axes) – The axis to plot to. If None, creates a new plot.
plot_images(axis: pylinac.winston_lutz.Axis = <Axis.GANTRY: 'Gantry'>, show: bool = True)[source]

Plot a grid of all the images acquired.

Four columns are plotted with the titles showing which axis that column represents.

  • axis ({'Gantry', 'Collimator', 'Couch', 'GB Combo', 'GBP Combo', 'All'}) –
  • show (bool) – Whether to show the image.
save_images(filename: Union[str, BinaryIO], axis: pylinac.winston_lutz.Axis = <Axis.GANTRY: 'Gantry'>, **kwargs)[source]

Save the figure of plot_images() to file. Keyword arguments are passed to matplotlib.pyplot.savefig().

  • filename (str) – The name of the file to save to.
  • axis – The axis to save.
plot_summary(show: bool = True)[source]

Plot a summary figure showing the gantry sag and wobble plots of the three axes.

save_summary(filename: Union[str, BinaryIO], **kwargs)[source]

Save the summary image.

results(as_list: bool = False) → str[source]

Return the analysis results summary.

Parameters:as_list (bool) – Whether to return as a list of strings vs single string. Pretty much for internal usage.
results_data(as_dict=False) → Union[pylinac.winston_lutz.WinstonLutzResult, dict][source]

Present the results data and metadata as a dataclass or dict. The default return type is a dataclass.

publish_pdf(filename: str, notes: Union[str, List[str], None] = None, open_file: bool = False, metadata: Optional[dict] = None)[source]

Publish (print) a PDF containing the analysis, images, and quantitative results.

  • filename ((str, file-like object}) – The file to write the results to.
  • notes (str, list of strings) – Text; if str, prints single line. If list of strings, each list item is printed on its own line.
  • open_file (bool) – Whether to open the file using the default program after creation.
  • metadata (dict) – Extra data to be passed and shown in the PDF. The key and value will be shown with a colon. E.g. passing {‘Author’: ‘James’, ‘Unit’: ‘TrueBeam’} would result in text in the PDF like: ————– Author: James Unit: TrueBeam ————–
class pylinac.winston_lutz.WinstonLutzResult(num_gantry_images: int, num_gantry_coll_images: int, num_coll_images: int, num_couch_images: int, num_total_images: int, max_2d_cax_to_bb_mm: float, median_2d_cax_to_bb_mm: float, max_2d_cax_to_epid_mm: float, median_2d_cax_to_epid_mm: float, gantry_3d_iso_diameter_mm: float, max_gantry_rms_deviation_mm: float, max_epid_rms_deviation_mm: float, gantry_coll_3d_iso_diameter_mm: float, coll_2d_iso_diameter_mm: float, max_coll_rms_deviation_mm: float, couch_2d_iso_diameter_mm: float, max_couch_rms_deviation_mm: float)[source]

Bases: pylinac.core.utilities.ResultBase

This class should not be called directly. It is returned by the results_data() method. It is a dataclass under the hood and thus comes with all the dunder magic.

Use the following attributes as normal class attributes.

num_gantry_images = None
num_gantry_coll_images = None
num_coll_images = None
num_couch_images = None
num_total_images = None
max_2d_cax_to_bb_mm = None
median_2d_cax_to_bb_mm = None
max_2d_cax_to_epid_mm = None
median_2d_cax_to_epid_mm = None
gantry_3d_iso_diameter_mm = None
max_gantry_rms_deviation_mm = None
max_epid_rms_deviation_mm = None
gantry_coll_3d_iso_diameter_mm = None
coll_2d_iso_diameter_mm = None
max_coll_rms_deviation_mm = None
couch_2d_iso_diameter_mm = None
max_couch_rms_deviation_mm = None
class pylinac.winston_lutz.ImageManager(directory: str, use_filenames: bool)[source]

Bases: list

Manages the images of a Winston-Lutz test.

  • directory (str) – The path to the images.
  • use_filenames (bool) – Whether to try to use the file name to determine axis values. Useful for Elekta machines that do not include that info in the DICOM data.
class pylinac.winston_lutz.WinstonLutz2D(file: str, use_filenames: bool = False)[source]

Bases: pylinac.core.image.LinacDicomImage

Holds individual Winston-Lutz EPID images, image properties, and automatically finds the field CAX and BB.

  • file (str) – Path to the image file.
  • use_filenames (bool) – Whether to try to use the file name to determine axis values. Useful for Elekta machines that do not include that info in the DICOM data.
analyze(bb_size_mm: float = 5) → None[source]

Analyze the image.


Center of the EPID panel


The projection of the field CAX through space around the area of the BB. Used for determining gantry isocenter size.

Returns:The virtual line in space made by the beam CAX.
Return type:Line

The couch angle converted from IEC 61217 scale to “Varian” scale. Note that any new Varian machine uses 61217.


The vector in mm from the CAX to the BB.


The scalar distance in mm from the CAX to the BB.


The vector in mm from the CAX to the EPID center pixel


The scalar distance in mm from the CAX to the EPID center pixel

plot(ax: Optional[matplotlib.axes._axes.Axes] = None, show: bool = True, clear_fig: bool = False)[source]

Plot the image, zoomed-in on the radiation field, along with the detected BB location and field CAX location.

  • ax (None, matplotlib Axes instance) – The axis to plot to. If None, will create a new figure.
  • show (bool) – Whether to actually show the image.
  • clear_fig (bool) – Whether to clear the figure first before drawing.
save_plot(filename: str, **kwargs)[source]

Save the image plot to file.


The axis that is varying.

There are five types of images:

  • Reference : All axes are at 0.
  • Gantry: All axes but gantry at 0.
  • Collimator : All axes but collimator at 0.
  • Couch : All axes but couch at 0.
  • Combo : More than one axis is not at 0.
results_data(as_dict=False) → Union[pylinac.winston_lutz.WinstonLutz2DResult, dict][source]

Present the results data and metadata as a dataclass or dict. The default return type is a dataclass.