.. _quart: ===== Quart ===== .. versionadded:: 3.2 Overview -------- The Quart module provides routines for automatically analyzing DICOM images of the Quart DVT phantom typically used with the Halcyon linac system. It can load a folder or zip file of images, correcting for translational and rotational offsets. .. versionadded:: 3.2 .. warning:: These algorithms have only a limited amount of testing data and results should be scrutinized. Further, the algorithm is more likely to change in the future when a more robust test suite is built up. If you'd like to submit data, enter it `here `_. Typical Use ----------- The Quart phantom analysis follows a similar pattern of load/analyze/output as the rest of the library. Unlike the CatPhan analysis, customization is not a goal, as the phantoms and analyses are much more well-defined. I.e. there's less of a use case for custom phantoms in this scenario. To use the Quart analysis, import the class: .. code-block:: python from pylinac import QuartDVT from pylinac.quart import QuartDVT # equivalent import And then load, analyze, and view the results: * **Load images** -- Loading can be done with a directory or zip file: .. code-block:: python quart_folder = r"C:/CT/Quart/Sept 2021" quart = QuartDVT(quart_folder) or load from zip: .. code-block:: python quart_folder = ( r"C:/CT/Quart/Sept 2021.zip" # this contains all the DICOM files of the scan ) quart = QuartDVT.from_zip(quart_folder) * **Analyze** -- Analyze the dataset: .. code-block:: python quart.analyze() * **View the results** -- Reviewing the results can be done in text or dict format as well as images: .. code-block:: python # print text to the console print(quart.results()) # view analyzed image summary quart.plot_analyzed_image() # view images independently quart.plot_images() # save the images quart.save_images() # finally, save a PDF quart.publish_pdf("myquart.pdf") Hypersight ---------- .. versionadded:: 3.17 The Hypersight variant of the Quart phantom includes a water ROI in the HU module. The Quart analysis automatically detects whether the water vial is present and filled, and reports the additional ROI analysis results for the water bubble. .. warning:: .. versionchanged:: 3.37 In earlier versions, the Hypersight variant had its own class. Starting with v3.37, there is now a unified Quart Phantom class that automatically detects the water vial. This class is now deprecated but remains in the event the automatic water vial detection of the ``QuartDVT`` class is incorrect. It will be removed in a future release. Advanced Use ------------ Adjusting ROI locations ^^^^^^^^^^^^^^^^^^^^^^^ To adjust ROI locations, see the sister section for CT analysis: :ref:`adjusting-roi-locations`. Using ``results_data`` ^^^^^^^^^^^^^^^^^^^^^^ Using the Quart module in your own scripts? While the analysis results can be printed out, if you intend on using them elsewhere (e.g. in an API), they can be accessed the easiest by using the :meth:`~pylinac.quart.QuartDVT.results_data` method which returns a :class:`~pylinac.quart.QuartDVTResult` instance. Continuing from above: .. code-block:: python data = quart.results_data() data.hu_module.roi_radius_mm # and more # return as a dict data_dict = quart.results_data(as_dict=True) data_dict["hu_module"]["roi_radius_mm"] ... Analysis Parameters ------------------- .. tab-set:: :sync-group: usage .. tab-item:: pylinac :sync: pylinac See :meth:`pylinac.quart.QuartDVT.analyze` for details. .. tab-item:: RadMachine :sync: radmachine * **HU Tolerance**: The tolerance in HU for the phantom materials. * **Scaling tolerance**: The tolerance in mm for the scaling of the phantom. * **Slice thickness tolerance**: The tolerance in mm for the slice thickness. * **CNR Ratio**: The required minimum ratio for the contrast-to-noise to be considered passing. * **X adjustment**: A fine-tuning adjustment to the detected x-coordinate of the phantom center. This will move the detected phantom position by this amount in the x-direction in mm. Positive values move the phantom to the right. * **Y adjustment**: A fine-tuning adjustment to the detected y-coordinate of the phantom center. This will move the detected phantom position by this amount in the y-direction in mm. Positive values move the phantom down. * **Angle adjustment**: A fine-tuning adjustment to the detected angle of the phantom. This will rotate the phantom by this amount in degrees. Positive values rotate the phantom clockwise. * **ROI size factor**: A fine-tuning adjustment to the ROI sizes of the phantom. This will scale the ROIs by this amount. Positive values increase the ROI sizes. In contrast to the scaling adjustment, this adjustment effectively makes the ROIs bigger or smaller, but does not adjust their position. * **Scaling factor**: A fine-tuning adjustment to the detected magnification of the phantom. This will zoom the ROIs and phantom outline (if applicable) by this amount. In contrast to the roi size adjustment, the scaling adjustment effectively moves the phantom and ROIs closer or further from the phantom center. I.e. this zooms the outline and ROI positions, but not ROI size. * **Origin slice**: The slice number that corresponds to the HU linearity slice. This is a fallback mechanism in case the automatic detection fails. Algorithm --------- The Quart algorithm is nearly the same as the :ref:`CBCT Algorithm `. The image loading and localization use the same type of logic. .. _quart-high-res: High-Resolution ^^^^^^^^^^^^^^^ For high-resolution resolvability, the Quart manual does describe an equation for calculating the MTF using the line-spread function (LSF) of the phantom edge. For simplicity, we use the Varian Halcyon IPA document, which outlines a similar logic with specific measurements of the -700 -> -200 HU distance using a vertical and horizontal profile. Within pylinac, to reduce the number of input parameters and also match commissioning values, these are the values used. The result is the distance in mm from these two HU values. .. note:: The images in pylinac are "grounded", meaning -1000 -> 0. So the actual algorithm search values are +300 HU (-700 + 1000) and +800 HU (-200 + 1000). CNR/SNR ^^^^^^^ While normally the :ref:`contrast ` algorithm is chosen by the user, for the Quart phantom it is hardcoded based on the equations in the manual. Specifically, contrast to noise is defined as: .. math:: CNR = \frac{|HU_{Poly} - HU_{Acrylic}|}{\sigma_{Acrylic}} where :math:`HU_{Poly}` and :math:`HU_{Acrylic}` are the median pixel values of the Polystyrene and Acrylic ROIs respectively, and :math:`\sigma_{Acrylic}` is the standard deviation of the Acrylic (background) ROI pixel values. Polystyrene was given as a possible recommendation in the Quart user manual. Acrylic is the base material of the phantom, i.e. background. .. note:: The numerator is an absolute value. The signal to noise is defined as: .. math:: \frac{Polystyrene + 1000}{\sigma_{Polystyrene}} where :math:`\sigma` is the standard deviation of the Polystyrene ROI pixel values. The poly ROI was chosen by us to match the selection for the CNR equation. Interpreting Results -------------------- The outcome from analyzing the phantom available in RadMachine or from ``results_data`` is: * ``phantom_model``: The model of the phantom, e.g. "Quart DVT". * ``phantom_roll_deg``: The roll of the phantom in degrees. * ``origin_slice``: The slice number of the origin image. * ``num_images``: The number of images given in the dataset. * ``hu_module``: A dictionary of the HU module results with the following items: * ``offset``: The offset of the module slice in mm from the origin slice. * ``measured_slice_thickness_mm``: The measured slice thickness in mm. * ``signal_to_noise``: The signal to noise ratio. * ``contrast_to_noise``: The contrast to noise ratio. * ``roi_settings``: A dictionary of the ROI settings. The keys are the HU material such as ``Acrylic`` with the following items: * ``value``: The mean value of the ROI in HU. * ``angle``: The angle of the ROI in degrees. * ``distance``: The distance of the ROI from the center of the phantom in mm. * ``radius``: The radius of the ROI in mm. * ``distance_pixels``: The distance of the ROI from the center of the phantom in pixels. * ``radius_pixels``: The radius of the ROI in pixels. * ``angle_corrected``: The angle of the ROI corrected for phantom roll in degrees. * ``rois``: A dictionary of ROI results where the key is the name of the material. Each material has the following items: * ``name``: The name of the material. * ``value``: The mean value of the ROI in HU. * ``stdev``: The standard deviation of the ROI in HU. * ``difference``: The difference in HU from the Acrylic ROI. * ``nominal_value``: The nominal value of the material in HU. * ``passed``: A boolean indicating if the material HU was within tolerance. * ``uniformity_module``: A dictionary of the uniformity module results with the following items: * ``offset``: The offset of the module slice in mm from the origin slice. * ``passed``: A boolean indicating if the module passed. * ``rois``: A dictionary of ROI results where the key is the name of the material. Each material has the following items: * ``name``: The name of the material. * ``value``: The mean value of the ROI in HU. * ``stdev``: The standard deviation of the ROI in HU. * ``difference``: The difference in HU from the Acrylic ROI. * ``nominal_value``: The nominal value of the material in HU. * ``passed``: A boolean indicating if the material HU was within tolerance. * ``roi_settings``: A dictionary of the ROI settings. The keys are the HU material such as ``Acrylic`` with the following items: * ``value``: The mean value of the ROI in HU. * ``angle``: The angle of the ROI in degrees. * ``distance``: The distance of the ROI from the center of the phantom in mm. * ``radius``: The radius of the ROI in mm. * ``distance_pixels``: The distance of the ROI from the center of the phantom in pixels. * ``radius_pixels``: The radius of the ROI in pixels. * ``angle_corrected``: The angle of the ROI corrected for phantom roll in degrees. * ``geometric_module``: A dictionary containing the following items: * ``offset``: The offset of the module slice in mm from the origin slice. * ``distances``: A dictionary of the phantom size itself in horizontal and vertical dimensions in mm. The keys are ``horizontal mm`` and ``vertical mm``. * ``high_contrast_distances``: A dictionary of the high contrast distances in mm. See: :ref:`quart-high-res`. The key is the region of the line and the value is the distance in mm. * ``mean_high_contrast_distance``: The mean of the high contrast distances in mm. API Documentation ------------------ .. autoclass:: pylinac.quart.QuartDVT :inherited-members: :members: .. autoclass:: pylinac.quart.HypersightQuartDVT :inherited-members: :members: .. autoclass:: pylinac.quart.QuartHUModule :inherited-members: :members: .. autoclass:: pylinac.quart.QuartUniformityModule :inherited-members: :members: .. autoclass:: pylinac.quart.QuartGeometryModule :inherited-members: :members: .. autopydantic_model:: pylinac.quart.QuartDVTResult .. autopydantic_model:: pylinac.quart.QuartHUModuleOutput .. autopydantic_model:: pylinac.quart.QuartUniformityModuleOutput .. autopydantic_model:: pylinac.quart.QuartGeometryModuleOutput