ImageIO
=============================

.. py:class:: petpal.utils.image_io.ImageIO(verbose: bool = True)

   :class:`ImageIO` to handle reading and writing imaging data and metadata.

   Provides several tools designed for reading and writing data within the Python environment.

   Key methods include:
       - :meth:`save_nii`: Saves a loaded NIfTI file to a file path.
       - :meth:`extract_image_from_nii_as_numpy`: Extracts imaging data from a NIfTI file as a numpy array.
       - :meth:`extract_header_from_nii`: Extracts header information from a NIfTI file as a dictionary.
       - :meth:`extract_np_to_nibabel`: Wraps imaging information in numpy into an Nibabel image.

   :ivar verbose: Set to `True` to output processing information.

   :vartype verbose: bool

   Initializes :class:`ImageIO` and sets verbose.

   :param verbose: Set to True to print debugging info to shell. Defaults to True.
   :type verbose: bool


   .. py:method:: save_nii(image: nibabel.nifti1.Nifti1Image, out_file: str)

      Wrapper to save nifti to file.

      :param image: Nibabel-type image to write to file.
      :type image: nibabel.nifti1.Nifti1Image
      :param out_file: File path to which image will be written.
      :type out_file: str



   .. py:method:: extract_image_from_nii_as_numpy(image: nibabel.nifti1.Nifti1Image) -> numpy.ndarray

      Convenient wrapper to extract data from a .nii or .nii.gz file as a numpy array.

      :param image: Nibabel-type image to write to file.
      :type image: nibabel.nifti1.Nifti1Image

      :returns: The data contained in the .nii or .nii.gz file as a numpy array.



   .. py:method:: extract_header_from_nii(image: nibabel.nifti1.Nifti1Image) -> nibabel.filebasedimages.FileBasedHeader

      Convenient wrapper to extract header information from a .nii or .nii.gz
      file as a nibabel file-based header.

      :param image: Nibabel-type image to write to file.
      :type image: nibabel.nifti1.Nifti1Image

      :returns: *image_header (FileBasedHeader)* -- The nifti header.



   .. py:method:: extract_np_to_nibabel(image_array: numpy.ndarray, header: nibabel.filebasedimages.FileBasedHeader, affine: numpy.ndarray) -> nibabel.nifti1.Nifti1Image

      Wrapper to convert an image array into nibabel object.

      :param image_array: Array containing image data.
      :type image_array: np.ndarray
      :param header: Header information to include.
      :type header: FileBasedHeader
      :param affine: Affine information we need to keep when rewriting image.
      :type affine: np.ndarray

      :returns: *image_nibabel (nibabel.nifti1.Nifti1Image)* -- Image stored in nifti-like nibabel format.



   .. py:method:: affine_parse(image_affine: numpy.ndarray) -> tuple
      :staticmethod:


      Parse the components of an image affine to return origin, spacing, direction.

      :param image_affine: A 4x4 affine matrix defining spacing, origin,
                           and direction of an image.
      :type image_affine: np.ndarray



   .. py:method:: extract_np_to_ants(image_array: numpy.ndarray, affine: numpy.ndarray) -> ants.ANTsImage

      Wrapper to convert an image array into ants object.
      Note header info is lost as ANTs does not carry this metadata.

      :param image_array: Array containing image data.
      :type image_array: np.ndarray
      :param affine: Affine information we need to keep when rewriting image.
      :type affine: np.ndarray

      :returns: *image_ants (ants.ANTsImage)* -- Image stored in nifti-like nibabel format.