PetPvc
================================================

.. py:class:: petpal.preproc.partial_volume_corrections.PetPvc

   Handles operations for PET partial volume correction using a Docker container.

   This class manages the setup and execution of processes using the PETPVC package,
   accessible via `PETPVC on GitHub <https://github.com/UCL/PETPVC>`_ and a Docker image
   hosted on `DockerHub <https://hub.docker.com/r/benthomas1984/petpvc>`_. It manages
   image retrieval, input/output setup, and command execution.

   :ivar client: A Docker client connected to the local system.
   :vartype client: docker.DockerClient
   :ivar image_name: The Docker image name to use for PETPVC processes.

   :vartype image_name: str

   .. rubric:: Examples

   Initialize the PETPVC handler and run a correction process:

   .. code-block:: python

       from petpvc_module import PetPvc
       petpvc_handler = PetPvc()
       petpvc_handler.run_petpvc(
           pet_4d_filepath="/path/to/input/pet_image.nii",
           output_filepath="/path/to/output/corrected_pet_image.nii",
           pvc_method="RBV",
           psf_dimensions=(6.0, 6.0, 6.0),
           mask_filepath="/path/to/input/brain_mask.nii",
           verbose=True)

   Initializes the PetPvc instance and ensures the required Docker image is available.


   .. py:method:: run_petpvc(pet_4d_filepath: str, output_filepath: str, pvc_method: str, psf_dimensions: Union[Tuple[float, float, float], float], mask_filepath: str = None, verbose: bool = False, debug: bool = False) -> None

      Executes the PETPVC correction process within a Docker container.

      :param pet_4d_filepath: The file path to the input 4D PET image.
      :type pet_4d_filepath: str
      :param output_filepath: The file path where the output image should be saved.
      :type output_filepath: str
      :param pvc_method: The partial volume correction method to apply.
      :type pvc_method: str
      :param psf_dimensions: The full-width half-max (FWHM) in mm along x, y, z axes.
      :type psf_dimensions: Union[Tuple[float, float, float], float]
      :param mask_filepath: The file path to the mask image. Defaults to None.
      :type mask_filepath: str, optional
      :param verbose: If True, prints the output from the Docker container. Defaults to False.
      :type verbose: bool, optional
      :param debug: If True, adds the --debug flag to the command for detailed logs. Defaults to False.
      :type debug: bool, optional

      Prints:
          Outputs from the Docker container if verbose is True.

      :raises docker.errors.ImageNotFound: If the Docker image is not available.
      :raises docker.errors.APIError: If the Docker client encounters an API error.



   .. py:method:: _pull_image_if_not_exists() -> None

      Checks if the Docker image is locally available and pulls it if not.