Merged in refactor/disk_locator_for_wl (pull request #303)

Part 1 of N: rework the disk locator to match WL. Use locator in WL standard version. Approved-by: Randy Taylor
jrkerns · Nov 29, 2023 · e2e228c · e2e228c
2 parents 5b04000 + ced510a
commit e2e228c
Show file tree

Hide file tree

Showing 19 changed files with 1,113 additions and 614 deletions.
diff --git a/bitbucket-pipelines.yml b/bitbucket-pipelines.yml
@@ -209,8 +209,18 @@ definitions:
         script:
           - source venv/bin/activate
           - pytest tests_basic/test_winstonlutz.py --cov-report term --junitxml=./test-reports/pytest_results.xml
-        caches:
-          - testfiles
+        condition:
+          changesets:
+            includePaths:
+              - "pylinac/core/**"
+              - "tests_basic/test_winstonlutz.py"
+              - "pylinac/winston_lutz.py"
+    - step: &winston-lutz-mtmf-tests
+        name: Run Winston-Lutz Multi-Target Multi-Field Tests
+        size: 2x
+        script:
+          - source venv/bin/activate
+          - pytest tests_basic/test_winstonlutz_mtmf.py --cov-report term --junitxml=./test-reports/pytest_results.xml
         condition:
           changesets:
             includePaths:
@@ -290,6 +300,7 @@ pipelines:
           - step: *calibration-tests
           - step: *vmat-tests
           - step: *winston-lutz-tests
+          - step: *winston-lutz-mtmf-tests
           - step: *core-module-tests
 
   branches:
@@ -312,6 +323,7 @@ pipelines:
           - step: *calibration-tests
           - step: *vmat-tests
           - step: *winston-lutz-tests
+          - step: *winston-lutz-mtmf-tests
           - step: *core-module-tests
       - step: *push-to-github
       - step: *update-dev-kraken
diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst
@@ -13,6 +13,47 @@ CT
   or limited resources on the machine running the process. This does come at a ~25-80% speed penalty depending on the
   size of the dataset. Larger datasets will have a larger penalty.
 
+Winston-Lutz
+^^^^^^^^^^^^
+
+* The ``results()`` method of the ``WinstonLutz`` class will now also report the mean distance from the BB to the CAX in mm.
+* The Winston-Lutz algorithm now uses the new :class:`~pylinac.core.metrics.SizedDiskLocator` internal class (see below). This was introduced in pylinac 3.16.
+  The algorithm is very similar to the existing WL algorithm.
+* A new parameter has been added to ``analyze()``: ``bb_tolerance_mm``. This gives an acceptable window for finding a BB.
+  E.g. if the BB size is 2mm, the tolerance can be set to 1mm. Alternatively, if the BB is very large, the
+  tolerance can be widened. This was done since very small and very large BBs were sometimes tripping up
+  because of the hardcoded 2mm tolerance. The default tolerance is still 2mm.
+
+  .. important::
+
+    If you use WL with very small BBs (<3mm), we recommend you set the tolerance to 1mm.
+
+* The BB boundary is now plotted. See the "Metrics" section.
+* Detection conditions for the WL algorithm can now be set via the ``detection_conditions`` parameter for ``WinstonLutz2D``
+  and set as a class attribute for ``WinstonLutz``.
+
+  .. important::
+
+      As always, pylinac uses the **weighted** centroid of the detected pixels. If the boundary
+      seems to include an extraneous pixel, it should minimally affect the BB location.
+
+
+Metrics
+^^^^^^^
+
+* The documentation for metrics has been updated considerably. See :ref:`image-metrics`.
+* The detection algorithm for disk/field metrics has been written out; see :ref:`image_metric_algorithm`.
+* The ``DiskLocator`` class was renamed to ``SizedDiskLocator``.
+* The ``DiskRegion`` class was renamed to ``SizedDiskRegion``.
+* The ``GlobalDiskLocator`` class was renamed to ``GlobalSizedDiskLocator``.
+* The ``SizedDiskLocator`` class now plots the detected boundary of the disk/BB. Because the WL algorithm
+  now uses this class, the WL plots now also include the detected BB boundary.
+* A new metric class has been added: ``GlobalFieldLocator``. This class will find a number of open fields
+  within an image without having to know the field size beforehand. See :ref:`global_sized_field_locator` for more.
+* Previously, metrics would allow the image to be modified. The metric would copy the image temporarily. However,
+  a memory bug would cause large numbers of images to use inordinate amounts of memory.
+  Now, images cannot be permanently modified. A hash check will be run before and after the calculation to ensure
+  the image array has not been modified and will raise an error if it has.
 
 v 3.17.0
 --------

diff --git a/docs/source/images/global_disk_locator.png b/docs/source/images/global_disk_locator.png
diff --git a/docs/source/images/metric_algo_0.02_binary.png b/docs/source/images/metric_algo_0.02_binary.png
diff --git a/docs/source/images/metric_algo_cropped.png b/docs/source/images/metric_algo_cropped.png
diff --git a/docs/source/images/metric_algo_final.png b/docs/source/images/metric_algo_final.png
diff --git a/docs/source/images/metric_algo_final_binary.png b/docs/source/images/metric_algo_final_binary.png
diff --git a/docs/source/images/metric_algo_inverted.png b/docs/source/images/metric_algo_inverted.png
diff --git a/docs/source/images/metric_algo_original.png b/docs/source/images/metric_algo_original.png
diff --git a/docs/source/images/metric_algo_profile_inversion.png b/docs/source/images/metric_algo_profile_inversion.png
diff --git a/docs/source/images/metric_algo_profile_normalized.png b/docs/source/images/metric_algo_profile_normalized.png
diff --git a/docs/source/images/multiple_field_sizes.png b/docs/source/images/multiple_field_sizes.png
diff --git a/docs/source/topics/image_metrics.rst b/docs/source/topics/image_metrics.rst
diff --git a/pylinac/core/image.py b/pylinac/core/image.py
@@ -863,8 +863,6 @@ def compute(self, metrics: list[MetricBase] | MetricBase) -> Any | dict[str, Any
         if isinstance(metrics, MetricBase):
             metrics = [metrics]
         for metric in metrics:
-            # we copy the image so any manipulations
-            # do not affect the original
             metric.inject_image(self)
             self.metrics.append(metric)
             value = metric.context_calculate()