Pylinac PicketFence mlc_pos and picket_pos

[carlosdiazavino]

Hello.

I'm a medical physicist trainee and also a python newbie. I'm trying to understand pylinac PicketFence to apply it at work, but I'm having trouble understanding what are mlc_pos and picket_pos in def error(self), inside MLCValue class. I assume picket_pos is the position where the picket should be, and mlc_pos is the position where the MLC leaves actually are; am I right?
Moreover, I don't get where are those values coming from...

Thank you in advance!

[calculusbook]

I think, you are 100% right. The leaf positional error is calculated as a difference between mlc_pos and picket_pos in Line 1244

(mlc_pos - picket_pos) / self._image.dpmm

self._image.dpmm is just a scale factor to convert pixels to mm.

As to where the picket_pos and mlc_pos are coming from, it is a bit more complicated. Each picket has an attribute self._fit which is a linear equation (y=ax+b) that approximates the picket as a geometrical line on the imaging plane. You can think of it as the central axis of the picket.
On the other hand, each mlc leaf has an attribute self.marker_lines which are essentially two short, parallel lines outlining the tips of a leaf pair. Something like this: ------| |------ The distance between those marker_lines is the gap between the two leafs in pair.

Now, mlc_pos is apparently the x or y coordinate of the middle point of marker_line. The middle point is assumed to be the the very tip of the leaf. The choice between x and y depends on the orientation of the pickets: up/down or left/right. See lines 1231 thru 1236.

picket_pos is the projection of the other coordinate (y or x) onto the geometrical line, see above, (y=ax+b) that approximates the picket line.

[seandomal]

I have some similar confusion here. How does this software identify where all the mlc positions are, especially if you don't pass the number of mlc's as an argument. I'm looking for a higher level explanation here.

[calculusbook]

What you pass as an argument is the type of MLC (Truebeam, Millennium, Agility, etc) which defines the leaf geometry and leaves' midline positions in the in-plane direction. The script detects the interleaf peaks in the PF image and aligns them with the given MLC geometry.
That is my understanding.

[jrkerns]

As @calculusbook said, the MLC positions are based on the type of MLC configuration that is passed. Here are the pre-built MLC models: https://pylinac.readthedocs.io/en/latest/picketfence.html#pylinac.picketfence.MLC. Here is how to create a custom configuration: https://pylinac.readthedocs.io/en/latest/picketfence.html#customizing-mlcs. The configuration is where the number of leaves and offsets are defined.

The configuration creates the offsets in the x and y direction from the center of the image. For each offset, a small window is sampled that contains the MLC kiss. E.g. if you run

from pylinac import PicketFence

pf = PicketFence.from_demo_image()
pf.analyze(sag_adjustment=3)
pf.plot_analyzed_image()

you'll note that the MLC marks no longer overlap. The MLC positions are not dynamically determined from the image.

[seandomal]

@jrkerns just to clarify, after all the mlc positions are determined based of the center of the image, do you just take a single 1D profile through the mlc pair ----- ] [ ---- at each of these locations to get the center of the fwhm? The major peaks that correspond to each picket, are these single points in the image and you are fitting a 1D polynomial to each single point and that's what is considered an "ideal picket"? In the case that you are analyzing each mlc independently, how do you programmatically define the window that searches for each mlc kiss, once this window is defined how do you find the "actual" location of the mlc kiss? In the documentation it mentions the concept of "nominal gap" could you elaborate why this parameter needed and how it is used in the algorithm? I know this is alot of questions here, I apologize in advance, just want to really make sure I have a fundamentally sound understanding of the algorithm before trying to use it in clinic.