diff --git a/docs/source/cbct_docs.rst b/docs/source/cbct_docs.rst index fcab507b..ba77afa1 100644 --- a/docs/source/cbct_docs.rst +++ b/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 diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst index 2f472541..c047ef8a 100644 --- a/docs/source/changelog.rst +++ b/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 `_ 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. diff --git a/docs/source/images/catphan_densities.png b/docs/source/images/catphan_densities.png new file mode 100644 index 00000000..a87d49fd Binary files /dev/null and b/docs/source/images/catphan_densities.png differ