class PicketFence: """A class used for analyzing EPID images where radiation strips have been formed by the MLCs. The strips are assumed to be parallel to one another and normal to the image edge; i.e. a "left-right" or "up-down" orientation is assumed. Further work could follow up by accounting for any angle. Attributes ---------- pickets: :class:`~pylinac.picketfence.PicketHandler` image: :class:`~pylinac.core.image.Image` Examples -------- Run the demo:: >>> PicketFence().run_demo() Typical session: >>> img_path = r"C:/QA/June/PF.dcm" # the EPID image >>> mypf = PicketFence(img_path) >>> mypf.analyze(tolerance=0.5, action_tolerance=0.3) >>> print(mypf.return_results()) >>> mypf.plot_analyzed_image() """ def __init__(self, filename=None, filter=None): """ Parameters ---------- filename : str, None Name of the file as a string. If None, image must be loaded later. filter : int, None The filter size to apply to the image upon load. """ if filename is not None: self.load_image(filename, filter) @classmethod def from_url(cls, url, filter=None): """Instantiate from a URL. .. versionadded:: 0.7.1 """ obj = cls() obj.load_url(url, filter=filter) return obj def load_url(self, url, filter=None): """Load from a URL. .. versionadded:: 0.7.1 """ try: import requests except ImportError: raise ImportError("Requests is not installed; cannot get the log from a URL") response = requests.get(url) if response.status_code != 200: raise ConnectionError("Could not connect to the URL") stream = BytesIO(response.content) self.load_image(stream, filter=filter) @property def passed(self): """Boolean specifying if all MLC positions were within tolerance.""" return self.pickets.passed @property def percent_passing(self): """Return the percentage of MLC positions under tolerance.""" num = 0 num_pass = 0 for picket in self.pickets: num += len(picket.error_array) num_pass += sum(picket.error_array < self.settings.tolerance) pct_pass = 100 * num_pass / num return pct_pass @property def max_error(self): """Return the maximum error found.""" return max(picket.max_error for picket in self.pickets) @property def max_error_picket(self): """Return the picket number where the maximum error occured.""" return np.argmax([picket.max_error for picket in self.pickets]) @property def max_error_leaf(self): """Return the leaf that had the maximum error.""" picket = self.pickets[self.max_error_picket] return np.argmax(picket.error_array) @property @lru_cache() def abs_median_error(self): """Return the median error found.""" return np.median(np.hstack([picket.error_array for picket in self.pickets])) @property def num_pickets(self): """Return the number of pickets determined.""" return len(self.pickets) @classmethod def from_demo_image(cls, filter=None): """Construct a PicketFence instance using the demo image. .. versionadded:: 0.6 """ obj = cls() obj.load_demo_image(filter=filter) return obj def load_demo_image(self, filter=None): """Load the demo image that is included with pylinac.""" im_open_path = osp.join(osp.dirname(__file__), 'demo_files', 'picket_fence', 'EPID-PF-LR.dcm') self.load_image(im_open_path, filter=filter) def load_image(self, file_path, filter=None): """Load the image Parameters ---------- file_path : str Path to the image file. filter : int, None If None (default), no filtering will be done to the image. If an int, will perform median filtering over image of size *filter*. """ self.image = Image(file_path) if isinstance(filter, int): self.image.median_filter(size=filter) self._check_for_noise() self.image.check_inversion() @classmethod def from_image_UI(cls, filter=None): """Construct a PicketFence instance and load an image using a dialog box. .. versionadded:: 0.6 """ obj = cls() obj.load_image_UI(filter=filter) return obj def load_image_UI(self, filter=None): """Load the image using a UI dialog box.""" path = get_filepath_UI() self.load_image(path, filter=filter) def _check_for_noise(self): """Check if the image has extreme noise (dead pixel, etc) by comparing min/max to 1/99 percentiles and smoothing if need be.""" while self._has_noise(): self.image.median_filter() def _has_noise(self): """Helper method to determine if there is spurious signal in the image.""" min = self.image.array.min() max = self.image.array.max() near_min, near_max = np.percentile(self.image.array, [0.5, 99.5]) max_is_extreme = max > near_max * 2 min_is_extreme = (min < near_min) and (abs(near_min - min) > 0.2 * near_max) return max_is_extreme or min_is_extreme def _adjust_for_sag(self, sag): """Roll the image to adjust for EPID sag.""" sag_pixels = int(round(sag * self.settings.dpmm)) direction = 'y' if self.orientation == orientations['UD'] else 'x' self.image.roll(direction, sag_pixels) def run_demo(self, tolerance=0.5): """Run the Picket Fence demo using the demo image. See analyze() for parameter info.""" self.load_demo_image() self.analyze(tolerance) print(self.return_results()) self.plot_analyzed_image() def analyze(self, tolerance=0.5, action_tolerance=None, hdmlc=False, num_pickets=None, sag_adjustment=0): """Analyze the picket fence image. Parameters ---------- tolerance : int, float The tolerance of difference in mm between an MLC pair position and the picket fit line. action_tolerance : int, float, None If None (default), no action tolerance is set or compared to. If an int or float, the MLC pair measurement is also compared to this tolerance. Must be lower than tolerance. This value is usually meant to indicate that a physicist should take an "action" to reduce the error, but should not stop treatment. hdmlc : bool If False (default), a standard (5/10mm leaves) Millennium MLC model is assumed. If True, an HD (2.5/5mm leaves) Millennium is assumed. num_pickets : int, None .. versionadded:: 0.8 The number of pickets in the image. A helper parameter to limit the total number of pickets, only needed if analysis is catching things that aren't pickets. sag_adjustment : float, int .. versionadded:: 0.8 The amount of shift in mm to apply to the image to correct for EPID sag. For Up-Down picket images, positive moves the image down, negative up. For Left-Right picket images, positive moves the image left, negative right. """ if action_tolerance is not None and tolerance < action_tolerance: raise ValueError("Tolerance cannot be lower than the action tolerance") """Pre-analysis""" self.settings = Settings(self.orientation, tolerance, action_tolerance, hdmlc, self.image.dpmm) self._adjust_for_sag(sag_adjustment) """Analysis""" self.pickets = PicketHandler(self.image, self.settings, num_pickets) def plot_analyzed_image(self, guard_rails=True, mlc_peaks=True, overlay=True, show=True): """Plot the analyzed image. Parameters ---------- guard_rails : bool Do/don't plot the picket "guard rails". mlc_peaks : bool Do/don't plot the MLC positions. overlay : bool Do/don't plot the alpha overlay of the leaf status. """ # plot the image plt.clf() ax = plt.imshow(self.image.array, cmap=plt.cm.Greys) # plot guard rails and mlc peaks as desired for p_num, picket in enumerate(self.pickets): if guard_rails: picket.add_guards_to_axes(ax.axes) if mlc_peaks: for idx, mlc_meas in enumerate(picket.mlc_meas): mlc_meas.add_to_axes(ax.axes, width=1.5) # plot the overlay if desired. if overlay: o = Overlay(self.image, self.settings, self.pickets) o.add_to_axes(ax) plt.xlim([0, self.image.shape[1]]) plt.ylim([0, self.image.shape[0]]) plt.axis('off') if show: plt.show() def save_analyzed_image(self, filename, guard_rails=True, mlc_peaks=True, overlay=True, **kwargs): """Save the analyzed figure to a file.""" self.plot_analyzed_image(guard_rails, mlc_peaks, overlay, show=False) plt.savefig(filename, **kwargs) def return_results(self): """Return results of analysis. Use with print().""" pass_pct = self.percent_passing string = "Picket Fence Results: \n{:2.1f}% " \ "Passed\nMedian Error: {:2.3f}mm \n" \ "Max Error: {:2.3f}mm on Picket: {}, Leaf: {}".format(pass_pct, self.abs_median_error, self.max_error, self.max_error_picket, self.max_error_leaf) return string @property def orientation(self): """The orientation of the image, either Up-Down or Left-Right.""" # replace any dead pixels with median value temp_image = self.image.array.copy() temp_image[temp_image < np.median(temp_image)] = np.median(temp_image) # find "range" of 80 to 90th percentiles row_sum = np.sum(temp_image, 0) col_sum = np.sum(temp_image, 1) row80, row90 = np.percentile(row_sum, [80, 90]) col80, col90 = np.percentile(col_sum, [80, 90]) row_range = row90 - row80 col_range = col90 - col80 # The true picket side will have a greater difference in # percentiles than will the non-picket size. if row_range < col_range: orientation = orientations['LR'] else: orientation = orientations['UD'] return orientation
class PicketFence: """A class used for analyzing EPID images where radiation strips have been formed by the MLCs. The strips are assumed to be parallel to one another and normal to the image edge; i.e. a "left-right" or "up-down" orientation is assumed. Further work could follow up by accounting for any angle. Attributes ---------- pickets: :class:`~pylinac.picketfence.PicketHandler` image: :class:`~pylinac.core.image.Image` Examples -------- Run the demo:: >>> PicketFence().run_demo() Typical session: >>> img_path = r"C:/QA/June/PF.dcm" # the EPID image >>> mypf = PicketFence(img_path) >>> mypf.analyze(tolerance=0.5, action_tolerance=0.3) >>> print(mypf.return_results()) >>> mypf.plot_analyzed_image() """ def __init__(self, filename=None, filter=None): """ Parameters ---------- filename : str, None Name of the file as a string. If None, image must be loaded later. filter : int, None The median filter size to apply to the image upon load. """ if filename is not None: self.load_image(filename, filter) @classmethod def from_url(cls, url, filter=None): """Instantiate from a URL. .. versionadded:: 0.7.1 """ obj = cls() obj.load_url(url, filter=filter) return obj def load_url(self, url, filter=None): """Load from a URL. .. versionadded:: 0.7.1 """ response = get_url(url) stream = BytesIO(response.content) self.load_image(stream, filter=filter) @property def passed(self): """Boolean specifying if all MLC positions were within tolerance.""" return self.pickets.passed @property def percent_passing(self): """Return the percentage of MLC positions under tolerance.""" num = 0 num_pass = 0 for picket in self.pickets: num += len(picket.error_array) num_pass += sum(picket.error_array < self.settings.tolerance) pct_pass = 100 * num_pass / num return pct_pass @property def max_error(self): """Return the maximum error found.""" return max(picket.max_error for picket in self.pickets) @property def max_error_picket(self): """Return the picket number where the maximum error occured.""" return np.argmax([picket.max_error for picket in self.pickets]) @property def max_error_leaf(self): """Return the leaf that had the maximum error.""" picket = self.pickets[self.max_error_picket] return np.argmax(picket.error_array) @property @lru_cache() def abs_median_error(self): """Return the median error found.""" return np.median(np.hstack([picket.error_array for picket in self.pickets])) @property def num_pickets(self): """Return the number of pickets determined.""" return len(self.pickets) @classmethod def from_demo_image(cls, filter=None): """Construct a PicketFence instance using the demo image. .. versionadded:: 0.6 """ obj = cls() obj.load_demo_image(filter=filter) return obj def load_demo_image(self, filter=None): """Load the demo image that is included with pylinac.""" im_open_path = osp.join(osp.dirname(__file__), 'demo_files', 'picket_fence', 'EPID-PF-LR.dcm') self.load_image(im_open_path, filter=filter) def load_image(self, file_path, filter=None): """Load the image Parameters ---------- file_path : str Path to the image file. filter : int, None If None (default), no filtering will be done to the image. If an int, will perform median filtering over image of size *filter*. """ self.image = Image(file_path) if isinstance(filter, int): self.image.median_filter(size=filter) self._check_for_noise() self.image.check_inversion() @classmethod def from_image_UI(cls, filter=None): """Construct a PicketFence instance and load an image using a dialog box. .. versionadded:: 0.6 """ obj = cls() obj.load_image_UI(filter=filter) return obj def load_image_UI(self, filter=None): """Load the image using a UI dialog box.""" path = get_filepath_UI() self.load_image(path, filter=filter) @classmethod def from_multiple_images(cls, path_list): """Load and superimpose multiple images and instantiate a Starshot object. .. versionadded:: 0.9 Parameters ---------- path_list : iterable An iterable of path locations to the files to be loaded/combined. """ obj = cls() obj.load_multiple_images(path_list) return obj def load_multiple_images(self, path_list): """Load and superimpose multiple images. .. versionadded:: 0.9 Parameters ---------- path_list : iterable An iterable of path locations to the files to be loaded/combined. """ self.image = Image.from_multiples(path_list, method='mean') self._check_for_noise() self.image.check_inversion() def _check_for_noise(self): """Check if the image has extreme noise (dead pixel, etc) by comparing min/max to 1/99 percentiles and smoothing if need be.""" while self._has_noise(): self.image.median_filter() def _has_noise(self): """Helper method to determine if there is spurious signal in the image.""" min = self.image.array.min() max = self.image.array.max() near_min, near_max = np.percentile(self.image.array, [0.5, 99.5]) max_is_extreme = max > near_max * 2 min_is_extreme = (min < near_min) and (abs(near_min - min) > 0.2 * near_max) return max_is_extreme or min_is_extreme def _adjust_for_sag(self, sag): """Roll the image to adjust for EPID sag.""" sag_pixels = int(round(sag * self.settings.dpmm)) direction = 'y' if self.orientation == orientations['UD'] else 'x' self.image.roll(direction, sag_pixels) def run_demo(self, tolerance=0.5, action_tolerance=0.25, interactive=False): """Run the Picket Fence demo using the demo image. See analyze() for parameter info.""" self.load_demo_image() self.analyze(tolerance, action_tolerance=action_tolerance) print(self.return_results()) self.plot_analyzed_image(interactive=interactive, leaf_error_subplot=True) def analyze(self, tolerance=0.5, action_tolerance=None, hdmlc=False, num_pickets=None, sag_adjustment=0): """Analyze the picket fence image. Parameters ---------- tolerance : int, float The tolerance of difference in mm between an MLC pair position and the picket fit line. action_tolerance : int, float, None If None (default), no action tolerance is set or compared to. If an int or float, the MLC pair measurement is also compared to this tolerance. Must be lower than tolerance. This value is usually meant to indicate that a physicist should take an "action" to reduce the error, but should not stop treatment. hdmlc : bool If False (default), a standard (5/10mm leaves) Millennium MLC model is assumed. If True, an HD (2.5/5mm leaves) Millennium is assumed. num_pickets : int, None .. versionadded:: 0.8 The number of pickets in the image. A helper parameter to limit the total number of pickets, only needed if analysis is catching more pickets than there really are. sag_adjustment : float, int .. versionadded:: 0.8 The amount of shift in mm to apply to the image to correct for EPID sag. For Up-Down picket images, positive moves the image down, negative up. For Left-Right picket images, positive moves the image left, negative right. """ if action_tolerance is not None and tolerance < action_tolerance: raise ValueError("Tolerance cannot be lower than the action tolerance") """Pre-analysis""" self.settings = Settings(self.orientation, tolerance, action_tolerance, hdmlc, self.image) self._adjust_for_sag(sag_adjustment) """Analysis""" self.pickets = PicketHandler(self.image, self.settings, num_pickets) def plot_analyzed_image(self, guard_rails=True, mlc_peaks=True, overlay=True, leaf_error_subplot=True, interactive=False, show=True): """Plot the analyzed image. Parameters ---------- guard_rails : bool Do/don't plot the picket "guard rails" around the ideal picket mlc_peaks : bool Do/don't plot the MLC positions. overlay : bool Do/don't plot the alpha overlay of the leaf status. leaf_error_subplot : bool .. versionadded:: 1.0 If True, plots a linked leaf error subplot adjacent to the PF image plotting the average and standard deviation of leaf error. interactive : bool .. versionadded:: 1.0 .. note:: mpld3 must be installed to use this feature. If False (default), plots a matplotlib figure. If True, plots a MPLD3 local server image, which adds some tooltips. """ # plot the image fig, ax = plt.subplots(figsize=self.settings.figure_size) ax.imshow(self.image.array, cmap=plt.cm.Greys) # generate a leaf error subplot if desired if leaf_error_subplot: self._add_leaf_error_subplot(ax, fig, interactive) # plot guard rails and mlc peaks as desired for p_num, picket in enumerate(self.pickets): if guard_rails: picket.add_guards_to_axes(ax.axes) if mlc_peaks: for idx, mlc_meas in enumerate(picket.mlc_meas): mlc_meas.add_to_axes(ax.axes, width=1.5) # plot the overlay if desired. if overlay: o = Overlay(self.image, self.settings, self.pickets) o.add_to_axes(ax) # tighten up the plot view ax.set_xlim([0, self.image.shape[1]]) ax.set_ylim([0, self.image.shape[0]]) ax.axis('off') if show: if interactive: mpld3 = import_mpld3() mpld3.show() else: plt.show() def _add_leaf_error_subplot(self, ax, fig, interactive): """Add a bar subplot showing the leaf error.""" tol_line_height = [self.settings.tolerance, self.settings.tolerance] tol_line_width = [0, max(self.image.shape)] # make the new axis divider = make_axes_locatable(ax) if self.settings.orientation == orientations['UD']: axtop = divider.append_axes('right', 2, pad=1, sharey=ax) else: axtop = divider.append_axes('bottom', 2, pad=1, sharex=ax) # get leaf positions, errors, standard deviation, and leaf numbers pos, vals, err, leaf_nums = self.pickets.error_hist() # plot the leaf errors as a bar plot if self.settings.orientation == orientations['UD']: axtop.barh(pos, vals, xerr=err, height=self.pickets[0].sample_width * 2, alpha=0.4, align='center') # plot the tolerance line(s) # TODO: replace .plot() calls with .axhline when mpld3 fixes funtionality axtop.plot(tol_line_height, tol_line_width, 'r-', linewidth=3) if self.settings.action_tolerance is not None: axtop.plot(tol_line_height, tol_line_width, 'y-', linewidth=3) # reset xlims to comfortably include the max error or tolerance value axtop.set_xlim([0, max(max(vals), self.settings.tolerance) + 0.1]) else: axtop.bar(pos, vals, yerr=err, width=self.pickets[0].sample_width * 2, alpha=0.4, align='center') axtop.plot(tol_line_width, tol_line_height, 'r-', linewidth=3) if self.settings.action_tolerance is not None: axtop.plot(tol_line_width, tol_line_height, 'y-', linewidth=3) axtop.set_ylim([0, max(max(vals), self.settings.tolerance) + 0.1]) # add formatting to axis axtop.grid('on') axtop.set_title("Average Error (mm)") # add tooltips if interactive if interactive: labels = [['Leaf pair {}/{}, Avg Error: {:3.3f}mm, Stdev: {:3.3f}mm'.format(leaf_num[0], leaf_num[1], err, std)] for leaf_num, err, std in zip(leaf_nums, vals, err)] mpld3 = import_mpld3() for num, patch in enumerate(axtop.axes.patches): ttip = mpld3.plugins.PointLabelTooltip(patch, labels[num], location='top left') mpld3.plugins.connect(fig, ttip) def save_analyzed_image(self, filename, guard_rails=True, mlc_peaks=True, overlay=True, leaf_error_subplot=False, interactive=False, **kwargs): """Save the analyzed figure to a file. See :meth:`~pylinac.picketfence.PicketFence.plot_analyzed_image()` for further parameter info. interactive : bool If False (default), saves the figure as a .png image. If True, saves an html file, which can be opened in a browser, etc. .. note:: mpld3 must be installed to use this feature. """ self.plot_analyzed_image(guard_rails, mlc_peaks, overlay, leaf_error_subplot=leaf_error_subplot, interactive=interactive, show=False) if interactive: mpld3 = import_mpld3() mpld3.save_html(plt.gcf(), filename) else: plt.savefig(filename, **kwargs) if isinstance(filename, str): print("Picket fence image saved to: {}".format(osp.abspath(filename))) def return_results(self): """Return results of analysis. Use with print().""" pass_pct = self.percent_passing string = "Picket Fence Results: \n{:2.1f}% " \ "Passed\nMedian Error: {:2.3f}mm \n" \ "Max Error: {:2.3f}mm on Picket: {}, Leaf: {}".format(pass_pct, self.abs_median_error, self.max_error, self.max_error_picket, self.max_error_leaf) return string @property def orientation(self): """The orientation of the image, either Up-Down or Left-Right.""" # replace any dead pixels with median value temp_image = self.image.array.copy() temp_image[temp_image < np.median(temp_image)] = np.median(temp_image) # find "range" of 80 to 90th percentiles row_sum = np.sum(temp_image, 0) col_sum = np.sum(temp_image, 1) row80, row90 = np.percentile(row_sum, [80, 90]) col80, col90 = np.percentile(col_sum, [80, 90]) row_range = row90 - row80 col_range = col90 - col80 # The true picket side will have a greater difference in # percentiles than will the non-picket size. if row_range < col_range: orientation = orientations['LR'] else: orientation = orientations['UD'] return orientation