Documentation updates

docs/source/cbct_docs.rst

@@ -21,20 +21,20 @@ To run one of the CatPhan demos, create a script or start an interpreter and inp
 
 Results will be printed to the console and a figure showing the slices analyzed will pop up::
 
-     - CatPhan 504 QA Test -
-    HU Linearity ROIs: {'Poly': -45.0, 'PMP': -200.0, 'Acrylic': 115.0, 'Teflon': 997.0, 'Delrin': 340.0, 'Air': -998.0, 'LDPE': -102.0}
+    - CatPhan 504 QA Test -
+    HU Linearity ROIs: Air: -998.0, PMP: -200.0, LDPE: -102.0, Poly: -45.0, Acrylic: 115.0, Delrin: 340.0, Teflon: 997.0
     HU Passed?: True
-    Uniformity ROIs: {'Center': 14.0, 'Top': 6.0, 'Left': 10.0, 'Bottom': 5.0, 'Right': 0.0}
-    Uniformity index: -1.3806706114398422
-    Integral non-uniformity: 0.006951340615690168
-    Uniformity Passed?: True
-    MTF 50% (lp/mm): 0.95
-    Low contrast ROIs "seen": 3
-    Low contrast visibility: 3.4654015681608437
-    Geometric Line Average (mm): 49.93054775087732
+    Low contrast visibility: 3.46
+    Geometric Line Average (mm): 49.95
     Geometry Passed?: True
-    Slice Thickness (mm): 2.5007568359375
+    Measured Slice Thickness (mm): 2.499
     Slice Thickness Passed? True
+    Uniformity ROIs: Top: 6.0, Right: -1.0, Bottom: 5.0, Left: 10.0, Center: 14.0
+    Uniformity index: -1.479
+    Integral non-uniformity: 0.0075
+    Uniformity Passed?: True
+    MTF 50% (lp/mm): 0.56
+    Low contrast ROIs "seen": 3
 
 .. plot::
 
@@ -185,6 +185,41 @@ The value is in mm:
 
     ct = OffsetCatPhan504.from_zip(...)  # use like normal
 
+Customizing Modules
+^^^^^^^^^^^^^^^^^^^
+
+You can also customize modules themselves in v2.4+. Customization should always be done by subclassing an existing
+module and overloading the attributes. Then, pass in the new custom module into the parent CatPhan class. The easiest
+way to get started is copy the relevant attributes from the existing code.
+
+As an example, let's override the nominal HU values for CTP404.
+
+.. code-block:: python
+
+    from pylinac.ct import CatPhan504, CTP404CP504
+
+    # first, customize the module
+    class CustomCTP404(CTP404CP504):
+        roi_dist_mm = 58.7  # this is the default value; we repeat here because it's easy to copy from source
+        roi_radius_mm = 5  # ditto
+        roi_settings = {
+            'Air': {'value': -1000, 'angle': -93, 'distance': roi_dist_mm, 'radius': roi_radius_mm},  # changed 'angle' from -90
+            'PMP': {'value': -196, 'angle': -120, 'distance': roi_dist_mm, 'radius': roi_radius_mm},
+            ...  # add other ROIs as appropriate
+        }
+
+    # then, pass to the CatPhan model
+    class CustomCP504(CatPhan504):
+        modules = {
+            CustomCTP404: {'offset': 0}
+            ...  # add other modules here as appropriate
+        }
+
+    ct = CustomCP504(...)
+
+.. warning:: If you overload the ``roi_settings`` or ``modules`` attributes, you are responsible for filling it out completely.
+             I.e. when you overload it's not partial. In the above example if you want other CTP modules you **must** populate them.
+
 Algorithm
 ---------
 
@@ -202,8 +237,7 @@ Restrictions
 
     .. warning:: Analysis can fail or give unreliable results if any Restriction is violated.
 
-* The phantom used must be an unmodified CatPhan 504, 503, or 600.
-* All of the relevant modules must be within the scan extent; i.e. one can't scan only part of the phantom.
+* All of the modules defined in the ``modules`` attribute must be within the scan extent.
 
 
 Pre-Analysis
@@ -239,7 +273,11 @@ Analysis
 
 * **Determine HU linearity** -- The HU module (CTP404) contains several materials with different HU values. Using
   hardcoded angles (corrected for roll) and radius from the center of the phantom, circular ROIs are sampled which
-  correspond to the HU material regions. The mean pixel value of the ROI is the stated HU value.
+  correspond to the HU material regions. The mean pixel value of the ROI is the stated HU value. Nominal HU values
+  are taken as the mean of the range given in the manual(s):
+
+  .. image:: images/catphan_densities.png
+
 * **Determine HU uniformity** -- HU uniformity (CTP486) is calculated in a similar manner to HU linearity, but
   within the CTP486 module/slice.
 * **Calculate Geometry/Scaling** -- The HU module (CTP404), besides HU materials, also contains several "nodes" which
@@ -290,6 +328,9 @@ Most problems in this module revolve around getting the data loaded.
 API Documentation
 -----------------
 
+CatPhan classes
+^^^^^^^^^^^^^^^
+
 The CatPhan classes uses several other classes. There are several Slices of Interest (SOI), most of which contain Regions of Interest (ROI).
 
 .. autoclass:: pylinac.ct.CatPhan504
@@ -309,9 +350,21 @@ Module classes (CTP404, etc)
 
 .. autoclass:: pylinac.ct.CatPhanModule
 
-.. autoclass:: pylinac.ct.CTP404
+.. autoclass:: pylinac.ct.CTP404CP503
+
+.. autoclass:: pylinac.ct.CTP404CP504
+
+.. autoclass:: pylinac.ct.CTP404CP600
 
-.. autoclass:: pylinac.ct.CTP528
+.. autoclass:: pylinac.ct.CTP404CP604
+
+.. autoclass:: pylinac.ct.CTP528CP503
+
+.. autoclass:: pylinac.ct.CTP528CP504
+
+.. autoclass:: pylinac.ct.CTP528CP600
+
+.. autoclass:: pylinac.ct.CTP528CP604
 
 .. autoclass:: pylinac.ct.CTP515
 
@@ -321,12 +374,8 @@ Module classes (CTP404, etc)
 ROI Objects
 ^^^^^^^^^^^
 
-.. autoclass:: pylinac.ct.ROIManagerMixin
-
 .. autoclass:: pylinac.ct.HUDiskROI
 
-.. autoclass:: pylinac.ct.RectangleROI
-
 .. autoclass:: pylinac.ct.ThicknessROI
 
 .. autoclass:: pylinac.ct.GeometricLine
@@ -335,3 +384,5 @@ Helper Functions
 ^^^^^^^^^^^^^^^^
 
 .. autofunction:: combine_surrounding_slices
+
+.. autofunction:: get_regions

docs/source/changelog.rst

@@ -6,6 +6,22 @@ Changelog
 v 2.4.0
 -------
 
+General
+^^^^^^^
+
+* The GUI function was removed from the pylinac init file. This was causing issues when deploying to Heroku as calls to tkinter
+  caused failures. The GUI should be called from the submodule now:
+
+  .. code-block:: python
+
+    # old
+    import pylinac
+    pylinac.gui()
+
+    # new
+    from pylinac.py_gui import gui
+    gui()
+
 CT Module
 ^^^^^^^^^
 
@@ -19,6 +35,11 @@ A new tutorial section has been added to the documentation showing examples of t
 * CTP modules had an inconsistent naming scheme for rois. E.g. CTP404 had ``hu_rois`` and ``bg_hu_rois`` while CTP515 had
   ``inner_bg_rois`` and ``rois``. This has been standardized (mostly) into ``rois`` for all modules and, where applicable, ``background_rois``.
   Some modules still have **more** relevant attrs, e.g. ``thickness_rois`` for CTP404, but they all have have ``rois``.
+* Due to the above refactor, you may notice small differences in the contrast constant value and thus the ROIs "seen".
+* HU differences are now signed. Previously the absolute value of the difference was taken.
+* HU nominal values have been adjusted to be the mean of the range listed in the CatPhan manuals. The changes
+  are as follows: Air: N/A (this is because most systems have a lower limit of -1000), PMP: -200 -> -196, LDPE: -100 -> -104,
+  Poly: -35 -> -47, Acrylic 120 -> 115, Delrin: 340 -> 365, Teflon: 990 -> 1000, Bone (20%): 240 -> 237, Bone (50%): N/A.
 
 Flatness & Symmetry
 ^^^^^^^^^^^^^^^^^^^
@@ -27,7 +48,7 @@ The flatness & symmetry module has been updated to allow for profiles of a selec
 pixel profile. Thanks to `@alanphys <https://github.com/alanphys>`_ for the pull request.
 
 * Two new keyword parameters were added to analyze: ``vert_width`` and ``horiz_width``. You can read about their usage
-  in the documentation.
+  in the ``analyze`` documentation.
 * The ``plot()`` method was renamed to ``plot_analyzed_image`` to match the rest of the modules.