# Flatness/Symmetry module documentation¶

## Overview¶

The Flatness & Symmetry module (flatsym) allows a physicist to check their linac’s beam profile against well-known flatness/symmetry calculation standards, reporting absolute values. Film or EPID images can be loaded in and analyzed.

## Running the Demo¶

To run the demo of the flatsym module, import the main class from it and run the demo method:

from pylinac.flatsym import BeamImage

my_img = BeamImage()
my_img.run_demo()


Which will result in the following plot:

## Typical Use¶

In most instances, a physicist is interested in quickly calculating the flatness, symmetry, or both of the image in question. The flatsym module allows you to do this easily, using any of multiple definitions of flatness or symmetry.

To get started, import the BeamImage class from the flatsym module:

from pylinac.flatsym import BeamImage


# from a file
my_file = r"C:/my/QA/folder/img.dcm"
my_img = BeamImage(my_file)

# or using a UI
my_img = BeamImage.open_UI()


You can calculate the flatness or symmetry directly, e.g.:

my_img.flatness()
[1.91, 2.6]  # or whatever the values are. Returns: [crossplane, inplane]
my_img.symmetry()
[3.08, 2.3]


Any physicist worth their salt will want to check that the right profile has been taken however. This is easily done with similar methods:

my_img.plot_flatness()


Default behavior is to analyze both planes at the calculated center of the field, but other options exist:

• Individual planes can be analyzed instead of both.
• The position of the profile can be directly passed.
• Multiple Analysis Definitions exist.

plot_flatsym() parameters for more details.

## Analysis Definitions¶

Warning

The following definitions are for photons only.

There are multiple definitions for both flatness and symmetry. Your machine vendor uses certain equations, or your clinic may use a specific definition. Pylinac has a number of built-in definitions which you can use.

Symmetry:

• – Name, Vendors that use it – Equation
• Point Difference, Varian$$100 * max(|L_{pt} - R_{pt}|)/ D_{CAX}$$ over 80%FW, where $$L_{pt}$$ and $$R_{pt}$$ are equidistant from the CAX.
• Point Difference Quotient (IEC), Elekta$$100 * max(|L_{pt}/R_{pt}|, |R_{pt}/L_{pt}|)$$ over 80%FW if 10<FW<30cm [1].

Flatness:

• – Name, Vendors that use it – Equation
• Variation over mean (80%), Varian$$100 * |D_{max} - D_{min}| / (D_{max} + D_{min})$$ within 80%FW.
• Dmax/Dmin (IEC), Elekta$$100 * D_{max}/D_{min}$$ within 80%FW for 10<FW<30cm [1].

Note

Siemens and other definitions (e.g. Area, Area/2) will be added if the community asks for it.

 [1] (1, 2) The region calculated over actually varies by the following: for 5

## Algorithm¶

There is little of a true “algorithm” in flatsym other than automatic field determination. Thus, this section is more terminology and notekeeping.

Allowances

• The image can be any size.
• The image can be digitized film or EPID (most image formats and DICOM).
• The image can be either inversion (Radiation is dark or light).

Restrictions

• The module is only meant for photon analysis at the moment (there are sometimes different equations for electrons for the same definition name).
• The image should be near perpendicular/normal to the image edge; this actually won’t cause the module to fail, but may invalidate the results’ accuracy. Accounting for angle may come in a future version if the community asks for it.

Analysis

• Determine the profile position - If the profile position determination is left to the automatic analysis, the row and column image sums are analyzed for the center of the FWHM. These then determine the location, either crossplane, inplane, or both. If the values are explicitly passed in, these values are used directly (or converted from a fraction).
• Extract profiles - With the positions known, profile(s) are extracted and analyzed according to the method specified (see Analysis Definitions). For symmetry calculations that operate around the CAX, the CAX must first be determined, which is the center of the FWHM of the profile.

## API Documentation¶

class pylinac.flatsym.BeamImage(filepath=None)[source]

Class for analyzing flatness & symmetry of a 2D beam image (perpendicular to the beam).

Parameters: filepath (None, str) – If None, image must be loaded later. If a str, path to the image file.
load_demo_image()[source]

run_demo(plane='both', position='auto', method='varian')[source]

Run the BeamImage flatness & symmetry demo.

plot_flatsym() for plane, position, and method parameter info.

plot_flatsym(plane='both', position='auto', method='varian')[source]

Plot both the flatness and symmetry.

Parameters: plane (str) – The plane of interest, either ‘crossplane’, ‘inplane’, or ‘both’. Shortcut descriptions are also allowed, e.g. ‘x’ == ‘cross’ == ‘crossplane’ and ‘i’ == ‘in’ == ‘inplane’. position (str, 2-element sequence) – If the position is a str, ‘auto’, the position will be determined automatically, at the center of the FWHM. If the position is a tuple/list/array it must be 2 elements long, specifying the location desired in (y, x) to take the flatness/symmetry over. The elements may be either integers, specifying the actual pixel values, or floats <1.0, specifying the image fraction (e.g. 0.4 will result in the pixel at 40% distance along an axis). Combinations of int/float is also allowed. See Examples section for more. method (str) – The method of analysis. There are multiple methods, specified by their “real” name as well as the vendor that utilizes the given method. For example, Varian uses the variation of the mean in the 80% field width for flatness. The method could be specified by using ‘varian’, or by ‘VoM80’. Another example is Elekta, who use the Point Difference Quotient-IEC definition for symmetry. Thus, one could use ‘elekta’ or ‘pdq-IEC’. Method names are case insensitive. For flatness, ‘Varian’, ‘VoM80’, ‘Siemens’ all perform the same calculation. ‘Elekta’ and ‘IEC’ both perform the same calculation. For symmetry, ‘Varian’, ‘Point Difference’ both perform the same calculation. ‘Elekta’ and ‘PDQ-IEC’ both perform the same calculation. See Analysis Definitions for equations.

Examples

>>> bi = BeamImage()


Defaults:

>>> bi.plot_flatsym()


Specify a single plane and different method:

>>> bi.plot_flatsym(plane='x', method='elekta')


Specify a custom position:

>>> bi.plot_flatsym(position=(300, 0.6))  # int/float combos allowed

symmetry(plane='both', position='auto', method='varian')[source]

Determine and return the symmetry of the image.

plot_flatsym() for plane, position, and method parameter info.

plot_symmetry(plane='both', position='auto', method='varian', plot_mirror=True, show=True, ax=None)[source]

Plot the profile, highlighting symmetry.

Parameters: show_mirror (bool) – If True (default), shows the “mirrored” profile, making visual comparison easier. ax (None, matplotlib.Axes, list containing matplotlib.Axes) – If None, the plot will be created on a new figure/axes, otherwise it will be plotted to the passed axes. show (bool) – If True (default), the plot will be drawn/shown at the end of the method call. Not showing the plot is useful when plotting multiple flat/sym plots.

plot_flatsym() for plane, position, and method parameter info.

flatness(plane='crossplane', position='auto', method='varian')[source]

Determine the flatness of the image.

plot_flatsym() for plane, position, and method parameter info.
plot_flatness(plane='both', position='auto', method='varian', ax=None, show=True)[source]
plot_flatsym() for plane, position, and method parameter info.