NiftiGifCreator
=========================================================

.. py:class:: petpal.visualizations.image_visualization.NiftiGifCreator(path_to_image: str, view: str, output_directory: str, output_filename_prefix: str = '', fig_title: str = 'Patlak-$K_i$ Parametric Image', cbar_label: str = '$K_i$ (Infusion Rate)')

   This class is designed to create a GIF from a NIfTI image by iterating through its slices based on a specified view
   ('coronal', 'sagittal', or 'axial' (or 'transverse'). The GIF is then written to the specified output directory
   with a filename prefix specified by the user.

   .. important::

       Makes a GIF of the image in the space defined by the nifty file.

   :ivar path_to_image: Path to the NIfTI image file.
   :vartype path_to_image: str
   :ivar view: Specifies on which plane the NIfTI image is sliced.
   :vartype view: str
   :ivar output_directory: Directory where the GIF should be written.
   :vartype output_directory: str
   :ivar prefix: Filename prefix for the GIF.
   :vartype prefix: str
   :ivar fig: Matplotlib figure object for the GIF.
   :vartype fig: matplotlib.figure.Figure
   :ivar ax: Matplotlib axes object for the GIF.
   :vartype ax: matplotlib.axes.Axes
   :ivar im_kw: Dictionary of arguments passed to Axes.imshow for the GIF.
   :vartype im_kw: dict
   :ivar image: 3D numpy array representing the NIfTI image.
   :vartype image: numpy.ndarray
   :ivar vmax: Maximum value for the plot's color limit.
   :vartype vmax: float
   :ivar ani_image: An animated image rendered in the figure.
   :vartype ani_image: matplotlib.image.AxesImage
   :ivar cbar: Colorbar associated with ani_image.

   :vartype cbar: matplotlib.colorbar

   .. rubric:: Example

   An example of how to initialize and use the NiftiGifCreator class:

   .. code-block:: python

       import petpal.image_visualization as pet_vis

       gif_creator = pet_vis.NiftiGifCreator(path_to_image="./input.nii.gz",
                                             view="axial",
                                             output_directory="./output",
                                             output_filename_prefix="test")
       gif_creator.make_gif()
       gif_creator.write_gif()

   Initialize the :class:`NiftiGifCreator`. Assigns instance variables and sets up figure for animation.

   :param path_to_image: absolute path to the image file.
   :type path_to_image: str
   :param view: desired view for the gif. Can be 'coronal', 'sagittal', 'axial'.
   :type view: str
   :param output_directory: absolute path to the directory where gif is to be stored.
   :type output_directory: str
   :param output_filename_prefix: a string to be prepended to the filename of the gif.
   :type output_filename_prefix: str, optional
   :param fig_title: Title of the figure where the images will be plotted.
   :type fig_title: str, optional
   :param cbar_label: Label for the colorbar of the figure.
   :type cbar_label: str, optional

   :raises ValueError: If `view` is not 'coronal', 'sagittal' or 'axial'


   .. py:method:: _validate_view()

      Validate the value of ``view``. It must be one of ['coronal', 'sagittal', 'axial', 'x', 'y', 'z'].

      :raises ValueError: If ``view`` is not 'coronal', 'sagittal', 'axial', 'x', 'y', 'z'



   .. py:method:: make_first_frame()

      Makes the first frame of the animation by plotting an image on ``ax`` according to ``view``.

      :returns: *im (matplotlib.image.AxesImage)* -- Image plotted in the first frame.

      Side Effects:
          Modifies ``ani_image`` by creating the first frame of the GIF



   .. py:method:: set_figure_title_and_labels(title: str, cbar_label: str)

      Sets the title of the figure and labels of the color bar.

      :param title: Title to be set for the figure.
      :type title: str
      :param cbar_label: Label to be set for the color bar.
      :type cbar_label: str

      Side Effects:
          - Modifies ``cbar`` with a new colorbar
          - Changes the title of ``fig``
          - Modifies the x and y axes of ``ani_image``




   .. py:method:: update_frame(i)

      Update function for matplotlib.animation.FuncAnimation. Updates the plotted image on the current axes.

      :param i: Index of the current frame
      :type i: int

      :returns: Tuple containing ``im`` (matplotlib.image.AxesImage), which is updated to the i-th frame according to
                ``view``.

      Side Effects:
          Modifies ``ani_image`` by updating its frame data




   .. py:method:: make_gif(frames: Iterable = None)

      Makes the GIF using FuncAnimation from matplotlib.animation module.

      :param frames: Iterable of frame indices to be included in the GIF. If not provided, all
                     frames will be used.
      :type frames: Iterable, optional

      Side Effects:
          Modifies ``ani`` by creating a new :class:`matplotlib.animation.FuncAnimation` object



   .. py:method:: write_gif(fps: int = 15)

      Writes the GIF to the output directory with filename ``{prefix}_view-{view}.gif``.

      Side Effects:
          - Creates a GIF file at the path specified by ``output_directory`` and ``prefix``
          - Closes the ``fig`` matplotlib figure