signal-grad-cam 1.0.1__py3-none-any.whl → 2.0.0__py3-none-any.whl

signal_grad_cam/cam_builder.py

@@ -8,7 +8,12 @@ import matplotlib.colors as m_colors
 import re
 import torch
 import tensorflow as tf
+import torch.nn.functional as F
+import imageio
 from typing import Callable, List, Tuple, Dict, Any, Optional
+from matplotlib.colors import Normalize
+from matplotlib.axes import Axes
+from mpl_toolkits.axes_grid1 import make_axes_locatable
 
 
 # Class
@@ -38,8 +43,8 @@ class CamBuilder:
             function may optionally take as a second input a list of objects required by the preprocessing method.
         :param class_names: (optional, default is None) A list of strings where each string represents the name of an
             output class.
-        :param time_axs: (optional, default is 1) An integer index indicating whether the input signal's time axis is
-            represented as the first or second dimension of the input array.
+        :param time_axs: (optional, default is 1) An integer index indicating for the position of the time
+            axis in the input signal or video/volume.
         :param input_transposed: (optional, default is False) A boolean indicating whether the input array is transposed
             during model inference, either by the model itself or by the preprocessing function.
         :param ignore_channel_dim: (optional, default is False) A boolean indicating whether to ignore the channel
@@ -89,7 +94,7 @@ class CamBuilder:
         for k, v in self.explainer_types.items():
             print(f" - Explainer identifier '{k}': {v}")
 
-        # Show available 1D or 2D convolutional layers
+        # Show available 1D, 2D, or 3D convolutional layers
         print()
         print("SEARCHING FOR NETWORK LAYERS:")
         self.__print_justify("Please verify that your network contains at least one 1D or 2D convolutional layer, "
@@ -115,6 +120,7 @@ class CamBuilder:
                 data_sampling_freq: float = None, dt: float = 10, channel_names: List[str | float] = None,
                 results_dir_path: str = None, aspect_factor: float = 100, data_shape_list: List[Tuple[int, int]] = None,
                 extra_preprocess_inputs_list: List[List[Any]] = None, extra_inputs_list: List[Any] = None,
+                video_fps_list: List[float] = None, show_single_video_frames: bool = False,
                 time_names: List[str | float] = None,
                 axes_names: Tuple[str | None, str | None] | List[str | None] = None, eps: float = 1e-6) \
             -> Tuple[Dict[str, List[np.ndarray]], Dict[str, np.ndarray],  Dict[str, Tuple[np.ndarray, np.ndarray]]]:
@@ -124,7 +130,8 @@ class CamBuilder:
         outputs, enabling a customized display of CAMs. Optional inputs are employed for a more detailed
         visualization of the results.
 
-        :param data_list: (mandatory) A list of np.ndarrays to be explained, representing either a signal or an image.
+        :param data_list: (mandatory) A list of np.ndarrays to be explained, representing either a signal, an image, or
+            a video/volume.
         :param data_labels: (mandatory) A list of integers representing the true labels of the data to be explained.
         :param target_classes: (mandatory) An integer or a list of integers representing the target classes for the
             explanation.
@@ -159,6 +166,10 @@ class CamBuilder:
             represents the additional input objects required by the preprocessing method for the i-th input.
         :param extra_inputs_list: (optional, default is None) A list of additional input objects required by the model's
             forward method.
+        :param video_fps_list: (optional, default is None) A list of floats, representing the frames-per-second of each
+            input video to be explained. For 3D CAMs only.
+        :param show_single_video_frames: (optional, default is False) A boolean flag indicating whether to store single
+            frames with the corresponding CAM. For 3D CAMs only.
         :param time_names: (optional, default is None) A list of strings representing tick names for the time axis.
         :param axes_names: (optional, default is None) A tuple of strings representing names for X and Y axes,
             respectively.
@@ -176,8 +187,7 @@ class CamBuilder:
         """
 
         # Check data names
-        if data_names is None:
-            data_names = ["item" + str(i) for i in range(len(data_list))]
+        data_names = self.__check_data_names(data_names, data_list)
 
         # Check input types
         target_classes, explainer_types, target_layers, contrastive_foil_classes = self.__check_input_types(
@@ -215,7 +225,9 @@ class CamBuilder:
                         self.__display_output(data_labels, target_class, explainer_type, target_layer, cam_list, output_probs,
                                               results_dir_path, data_names, data_sampling_freq, dt, aspect_factor,
                                               bar_ranges, channel_names, time_names=time_names, axes_names=axes_names,
-                                              contrastive_foil_class=contrastive_foil_class)
+                                              contrastive_foil_class=contrastive_foil_class,
+                                              video_fps_list=video_fps_list,
+                                              show_single_video_frames=show_single_video_frames)
 
         return cams_dict, predicted_probs_dict, bar_ranges_dict
 
@@ -228,7 +240,8 @@ class CamBuilder:
                                   grid_instructions: Tuple[int, int] = None,
                                   bar_ranges_dict: Dict[str, Tuple[np.ndarray, np.ndarray]] = None,
                                   results_dir_path: str = None, data_sampling_freq: float = None, dt: float = 10,
-                                  channel_names: List[str | float] = None, time_names: List[str | float] = None,
+                                  channel_names: List[str | float] = None, video_fps_list: List[float] = None,
+                                  show_single_video_frames: bool = False, time_names: List[str | float] = None,
                                   axes_names: Tuple[str | None, str | None] | List[str | None] = None,
                                   fig_size: Tuple[int, int] = None) -> None:
         """
@@ -236,7 +249,8 @@ class CamBuilder:
         and multichannel signals with numerous channels, such as frequency spectra.
 
 
-        :param data_list: (mandatory) A list of np.ndarrays to be explained, representing either a signal or an image.
+        :param data_list: (mandatory) A list of np.ndarrays to be explained, representing either a signal, an image, or
+            a video/volume.
         :param data_labels: (mandatory) A list of integers representing the true labels of the data to be explained.
         :param predicted_probs_dict: (mandatory) A dictionary storing a np.ndarray. Each array represents the inferred
             class probabilities for each item in the input list.
@@ -258,7 +272,8 @@ class CamBuilder:
             comparative classes (foils) for the explanation in the context of Contrastive Explanations. If None, the
             explanation would follow the classical paradigm.
         :param grid_instructions: (optional, default is None) A tuple of integers defining the desired tabular layout
-            for figure subplots. The expected format is number of columns (width) x number of rows (height).
+            for figure subplots. The expected format is number of columns (width) x number of rows (height). Unused for
+            3D CAMs.
         :param bar_ranges_dict: A dictionary storing a tuple of np.ndarrays. Each tuple contains two np.ndarrays
             corresponding to the minimum and maximum importance scores per CAM for each item in the input data list,
             based on a given setting (defined by algorithm, target layer, and target class).
@@ -270,6 +285,10 @@ class CamBuilder:
             in the output display.
         :param channel_names: (optional, default is None) A list of strings where each string represents the name of a
             signal channel for tick settings.
+        :param video_fps_list: (optional, default is None) A list of floats, representing the frames-per-second of each
+            input video to be explained.
+        :param show_single_video_frames: (optional, default is False) A boolean flag indicating whether to store single
+            frames with the corresponding CAM. For 3D CAMs only.
         :param time_names: (optional, default is None) A list of strings representing tick names for the time axis.
         :param axes_names: (optional, default is None) A tuple of strings representing names for X and Y axes,
             respectively.
@@ -295,31 +314,47 @@ class CamBuilder:
             for target_layer in target_layers:
                 for target_class in target_classes:
                     for contrastive_foil_class in contrastive_foil_classes:
-                        plt.figure(figsize=fig_size)
-                        for i in range(n_items):
-                            cam, item, batch_idx, item_key = self.__get_data_for_plots(data_list, i, target_item_ids,
-                                                                                       cams_dict, explainer_type,
-                                                                                       target_layer, target_class,
-                                                                                       contrastive_foil_class)
-
-                            plt.subplot(w, h, i + 1)
-                            plt.imshow(item)
-                            aspect = "auto" if cam.shape[0] / cam.shape[1] < 0.1 else None
-
-                            norm = self.__get_norm(cam)
-                            map = plt.imshow(cam, cmap="inferno", aspect=aspect, norm=norm)
-                            self.__set_colorbar(bar_ranges_dict[item_key], i)
-                            map.set_alpha(0.3)
-
-                            self.__set_axes(cam, data_sampling_freq, dt, channel_names, time_names=time_names,
-                                            axes_names=axes_names)
-                            data_name = data_names[batch_idx] if data_names is not None else "item" + str(batch_idx)
-                            plt.title(self.__get_cam_title(data_name, target_class, data_labels, batch_idx, item_key,
-                                                           predicted_probs_dict, contrastive_foil_class))
-
-                        # Store or show CAM
-                        self.__display_plot(results_dir_path, explainer_type, target_layer, target_class,
-                                            contrastive_foil_class)
+                        if (self._is_2d_layer(self._get_layers_pool(extend_search=self.extend_search)[target_layers[0]])
+                                is not None):
+                            plt.figure(figsize=fig_size)
+                            for i in range(n_items):
+                                cam, item, batch_idx, item_key = self.__get_data_for_plots(data_list, i, target_item_ids,
+                                                                                           cams_dict, explainer_type,
+                                                                                           target_layer, target_class,
+                                                                                           contrastive_foil_class)
+
+                                plt.subplot(w, h, i + 1)
+                                plt.imshow(item)
+                                aspect = "auto" if cam.shape[0] / cam.shape[1] < 0.1 else None
+
+                                norm = self.__get_norm(cam)
+                                map = plt.imshow(cam, cmap="inferno", aspect=aspect, norm=norm)
+                                self.__set_colorbar(bar_ranges_dict[item_key], i)
+                                map.set_alpha(0.3)
+
+                                self.__set_axes(cam, data_sampling_freq, dt, channel_names, time_names=time_names,
+                                                axes_names=axes_names)
+                                data_name = data_names[batch_idx] if data_names is not None else "item" + str(batch_idx)
+                                plt.title(self.__get_cam_title(data_name, target_class, data_labels, batch_idx, item_key,
+                                                               predicted_probs_dict, contrastive_foil_class))
+
+                            # Store or show CAM
+                            self.__display_plot(results_dir_path, explainer_type, target_layer, target_class,
+                                                contrastive_foil_class)
+                        else:
+                            item_key = self.__get_item_key(explainer_type, target_layer, target_class,
+                                                           contrastive_foil_class)
+                            data_names = self.__check_data_names(data_names, data_list)
+
+                            self.__display_output(data_labels=data_labels, target_class=target_class,
+                                                  explainer_type=explainer_type, target_layer=target_layer,
+                                                  cam_list=cams_dict[item_key],
+                                                  predicted_probs=predicted_probs_dict[item_key],
+                                                  results_dir_path=results_dir_path, data_names=data_names,
+                                                  bar_ranges=bar_ranges_dict[item_key], axes_names=axes_names,
+                                                  contrastive_foil_class=contrastive_foil_class,
+                                                  video_fps_list=video_fps_list, video_list=data_list,
+                                                  show_single_video_frames=show_single_video_frames)
 
     def single_channel_output_display(self, data_list: List[np.ndarray], data_labels: List[int],
                                       predicted_probs_dict: Dict[str, np.ndarray],
@@ -330,7 +365,9 @@ class CamBuilder:
                                       grid_instructions: Tuple[int, int] = None,
                                       bar_ranges_dict: Dict[str, Tuple[np.ndarray, np.ndarray]] = None,
                                       results_dir_path: str = None, data_sampling_freq: float = None, dt: float = 10,
-                                      channel_names: List[str | float] = None, time_names: List[str | float] = None,
+                                      channel_names: List[str | float] = None, video_fps_list: List[float] = None,
+                                      video_channel_idx: int = -1, show_single_video_frames: bool = False,
+                                      time_names: List[str | float] = None,
                                       axes_names: Tuple[str | None, str | None] | List[str | None] = None,
                                       fig_size: Tuple[int, int] = None, line_width: float = 0.1,
                                       marker_width: float = 30) -> None:
@@ -339,7 +376,8 @@ class CamBuilder:
         visualization is useful for interpreting signal explanations with a limited number of channels. If many channels
         are present, it is recommended to select only a subset.
 
-        :param data_list: (mandatory) A list of np.ndarrays to be explained, representing either a signal or an image.
+        :param data_list: (mandatory) A list of np.ndarrays to be explained, representing either a signal, an image, or
+            a video/volume.
         :param data_labels: (mandatory) A list of integers representing the true labels of the data to be explained.
         :param predicted_probs_dict: (mandatory) A dictionary storing a np.ndarray. Each array represents the inferred
             class probabilities for each item in the input list.
@@ -375,6 +413,12 @@ class CamBuilder:
             in the output display.
         :param channel_names: (optional, default is None) A list of strings where each string represents the name of a
             signal channel for tick settings.
+        :param video_fps_list: (optional, default is None) A list of floats, representing the frames-per-second of each
+            input video to be explained.
+        :param video_channel_idx: (optional, default is -1) An integer representing the channel index in the input
+            videos/volumes.
+        :param show_single_video_frames: (optional, default is False) A boolean flag indicating whether to store single
+            frames with the corresponding CAM. For 3D CAMs only.
         :param time_names: (optional, default is None) A list of strings representing tick names for the time axis.
         :param axes_names: (optional, default is None) A tuple of strings representing names for X and Y axes,
             respectively.
@@ -410,43 +454,64 @@ class CamBuilder:
             for target_layer in target_layers:
                 for target_class in target_classes:
                     for contrastive_foil_class in contrastive_foil_classes:
-                        for i in range(n_items):
-                            plt.figure(figsize=fig_size)
-                            cam, item, batch_idx, item_key = self.__get_data_for_plots(data_list, i, target_item_ids,
-                                                                                       cams_dict, explainer_type,
-                                                                                       target_layer, target_class,
-                                                                                       contrastive_foil_class)
-
-                            # Cross-CAM normalization
-                            minimum = np.min(cam)
-                            maximum = np.max(cam)
-
-                            data_name = data_names[batch_idx] if data_names is not None else "item" + str(batch_idx)
-                            desired_channels = desired_channels if desired_channels is not None else range(cam.shape[1])
-                            for j in range(len(desired_channels)):
-                                channel = desired_channels[j]
-                                plt.subplot(w, h, j + 1)
-                                try:
-                                    cam_j = cam[channel, :]
-                                except IndexError:
-                                    cam_j = cam[0, :]
-                                item_j = item[:, channel] if item.shape[0] == len(cam_j) else item[channel, :]
-                                plt.plot(item_j, color="black", linewidth=line_width)
-                                plt.scatter(np.arange(len(item_j)), item_j, c=cam_j, cmap="inferno", marker=".",
-                                            s=marker_width, norm=None, vmin=minimum, vmax=maximum + 1e-10)
-                                self.__set_colorbar(bar_ranges_dict[item_key], i)
-
-                                if channel_names is None:
-                                    channel_names = ["Channel " + str(c) for c in desired_channels]
-                                self.__set_axes(cam, data_sampling_freq, dt, channel_names, time_names,
-                                                axes_names=axes_names, only_x=True)
-                                plt.title(channel_names[j])
-                            plt.suptitle(self.__get_cam_title(data_name, target_class, data_labels, batch_idx, item_key,
-                                                              predicted_probs_dict, contrastive_foil_class))
-
-                            # Store or show CAM
-                            self.__display_plot(results_dir_path, explainer_type, target_layer, target_class,
-                                                contrastive_foil_class, data_name, is_channel=True)
+                        if (self._is_2d_layer(self._get_layers_pool(extend_search=self.extend_search)[target_layers[0]])
+                                is not None):
+                            for i in range(n_items):
+                                plt.figure(figsize=fig_size)
+                                cam, item, batch_idx, item_key = self.__get_data_for_plots(data_list, i, target_item_ids,
+                                                                                           cams_dict, explainer_type,
+                                                                                           target_layer, target_class,
+                                                                                           contrastive_foil_class)
+
+                                # Cross-CAM normalization
+                                minimum = np.min(cam)
+                                maximum = np.max(cam)
+
+                                data_name = data_names[batch_idx] if data_names is not None else "item" + str(batch_idx)
+                                desired_channels = desired_channels if desired_channels is not None else range(cam.shape[1])
+                                for j in range(len(desired_channels)):
+                                    channel = desired_channels[j]
+                                    plt.subplot(w, h, j + 1)
+                                    try:
+                                        cam_j = cam[channel, :]
+                                    except IndexError:
+                                        cam_j = cam[0, :]
+                                    item_j = item[:, channel] if item.shape[0] == len(cam_j) else item[channel, :]
+                                    plt.plot(item_j, color="black", linewidth=line_width)
+                                    plt.scatter(np.arange(len(item_j)), item_j, c=cam_j, cmap="inferno", marker=".",
+                                                s=marker_width, norm=None, vmin=minimum, vmax=maximum + 1e-10)
+                                    self.__set_colorbar(bar_ranges_dict[item_key], i)
+
+                                    if channel_names is None:
+                                        channel_names = ["Channel " + str(c) for c in desired_channels]
+                                    self.__set_axes(cam, data_sampling_freq, dt, channel_names, time_names,
+                                                    axes_names=axes_names, only_x=True)
+                                    plt.title(channel_names[j])
+                                plt.suptitle(self.__get_cam_title(data_name, target_class, data_labels, batch_idx, item_key,
+                                                                  predicted_probs_dict, contrastive_foil_class))
+
+                                # Store or show CAM
+                                self.__display_plot(results_dir_path, explainer_type, target_layer, target_class,
+                                                    contrastive_foil_class, data_name, is_channel=True)
+                        else:
+                            item_key = self.__get_item_key(explainer_type, target_layer, target_class,
+                                                           contrastive_foil_class)
+                            data_names = self.__check_data_names(data_names, data_list)
+
+                            for channel in range(data_list[0].shape[video_channel_idx]):
+                                data_list_channel = [np.take(data, [channel], axis=video_channel_idx) for data in data_list]
+                                channel_name = channel_names[channel] if channel_names is not None else str(channel)
+
+                                self.__display_output(data_labels=data_labels, target_class=target_class,
+                                                      explainer_type=explainer_type, target_layer=target_layer,
+                                                      cam_list=cams_dict[item_key],
+                                                      predicted_probs=predicted_probs_dict[item_key],
+                                                      results_dir_path=results_dir_path, data_names=data_names,
+                                                      bar_ranges=bar_ranges_dict[item_key], axes_names=axes_names,
+                                                      contrastive_foil_class=contrastive_foil_class,
+                                                      video_fps_list=video_fps_list, video_list=data_list_channel,
+                                                      channel_name=channel_name,
+                                                      show_single_video_frames=show_single_video_frames)
 
     def _get_layers_pool(self, show: bool = False, extend_search: bool = False) \
             -> Dict[str, torch.nn.Module | tf.keras.layers.Layer | Any]:
@@ -495,7 +560,8 @@ class CamBuilder:
         Retrieves raw CAMs from an input data list based on the specified settings (defined by algorithm, target layer,
         and target class). Additionally, it returns the class probabilities predicted by the model.
 
-        :param data_list: (mandatory) A list of np.ndarrays to be explained, representing either a signal or an image.
+        :param data_list: (mandatory) A list of np.ndarrays to be explained, representing either a signal, an image, or
+            a video/volume.
         :param target_class: (mandatory) An integer representing the target class for the explanation.
         :param target_layer: (mandatory) A string representing the target layer for the explanation. This string should
             identify either PyTorch named modules, TensorFlow/Keras layers, or it should be a class dictionary key,
@@ -522,11 +588,12 @@ class CamBuilder:
                              "'CamBuilder': you will need to instantiate either a 'TorchCamBuilder' or a 'TfCamBuilder'"
                              " instance to use it.")
 
-    def _get_gradcam_map(self, is_2d_layer: bool, batch_idx: int) -> torch.Tensor | tf.Tensor:
+    def _get_gradcam_map(self, is_2d_layer: bool, is_3d_layer: bool, batch_idx: int) -> torch.Tensor | tf.Tensor:
         """
         Compute the CAM using the vanilla Gradient-weighted Class Activation Mapping (Grad-CAM) algorithm.
 
         :param is_2d_layer: (mandatory) A boolean indicating whether the target layers 2D-convolutional layer.
+        :param is_3d_layer: (mandatory) A boolean indicating whether the target layers 3D-convolutional layer.
         :param batch_idx: (mandatory) The index corresponding to the i-th selected item within the original input data
             list.
 
@@ -538,11 +605,12 @@ class CamBuilder:
                              "will need to instantiate either a 'TorchCamBuilder' or a 'TfCamBuilder' instance to use "
                              "it.")
 
-    def _get_hirescam_map(self, is_2d_layer: bool, batch_idx: int) -> np.ndarray:
+    def _get_hirescam_map(self, is_2d_layer: bool, is_3d_layer: bool, batch_idx: int) -> np.ndarray:
         """
         Compute the CAM using the High-Resolution Class Activation Mapping (HiResCAM) algorithm.
 
         :param is_2d_layer: (mandatory) A boolean indicating whether the target layers 2D-convolutional layer.
+        :param is_3d_layer: (mandatory) A boolean indicating whether the target layers 3D-convolutional layer.
         :param batch_idx: (mandatory) The index corresponding to the i-th selected item within the original input data
             list.
 
@@ -564,7 +632,8 @@ class CamBuilder:
         layer, and target class), along with class probabilities predicted by the model. Additionally, it adjusts the
         output CAMs in both shape and value range (0-255), and returns the original importance score range.
 
-        :param data_list: (mandatory) A list of np.ndarrays to be explained, representing either a signal or an image.
+        :param data_list: (mandatory) A list of np.ndarrays to be explained, representing either a signal, an image, or
+            a video/volume.
         :param target_class: (mandatory) An integer representing the target classe for the explanation.
         :param target_layer: (mandatory) A string representing the target layer for the explanation. This string should
             identify either PyTorch named modules, TensorFlow/Keras layers, or it should be a class dictionary key,
@@ -645,28 +714,59 @@ class CamBuilder:
                 layer, and target class).
         """
 
-        cams, bar_ranges = self.__normalize_cams(cams, is_2d_layer)
+        is_3d_layer = is_2d_layer is None
+        cams, bar_ranges = self.__normalize_cams(cams, is_2d_layer, is_3d_layer)
 
         cam_list = []
         for i in range(len(data_shape_list)):
             cam = cams[i]
-            if is_2d_layer:
+            if is_2d_layer is not None and is_2d_layer:
                 dim_reshape = (data_shape_list[i][1], data_shape_list[i][0])
                 if self.input_transposed:
                     dim_reshape = dim_reshape[::-1]
+            elif is_3d_layer:
+                if len(data_shape_list[i]) >= 4:
+                    w_idx = 2
+                    h_idx = 3
+                else:
+                    w_idx = 1
+                    h_idx = 2
+                if not self.input_transposed:
+                    dim_reshape = (data_shape_list[i][0], data_shape_list[i][w_idx], data_shape_list[i][h_idx])
+                else:
+                    dim_reshape = (data_shape_list[i][0], data_shape_list[i][h_idx], data_shape_list[i][w_idx])
             else:
                 dim_reshape = (1, data_shape_list[i][self.time_axs])
                 if self.time_axs:
                     cam = np.transpose(cam)
-            if self.padding_dim is not None:
-                original_dim = dim_reshape[1]
-                dim_reshape = (dim_reshape[0], self.padding_dim)
-            cam = cv2.resize(cam, dim_reshape)
+            if not is_3d_layer:
+                if self.padding_dim is not None:
+                    if is_2d_layer is not None and is_2d_layer:
+                        original_dim = (dim_reshape[1], dim_reshape[0])
+                        dim_reshape = (self.padding_dim, self.padding_dim)
+                    else:
+                        original_dim = dim_reshape[1]
+                        dim_reshape = (dim_reshape[0], self.padding_dim)
+                cam = cv2.resize(cam, dim_reshape)
+            else:
+                if self.padding_dim is not None:
+                    original_dim = dim_reshape
+                    dim_reshape = (self.padding_dim, self.padding_dim, self.padding_dim)
+                cam = F.interpolate(torch.tensor(cam, dtype=torch.float32).unsqueeze(0).unsqueeze(0), size=dim_reshape,
+                                    mode="trilinear", align_corners=False)[0, 0].numpy()
 
-            if is_2d_layer and self.input_transposed:
+            if is_2d_layer is not None and is_2d_layer and self.input_transposed:
                 cam = np.transpose(cam)
+            elif is_3d_layer and self.input_transposed:
+                cam = np.transpose(cam, (0, 2, 1))
+
             if self.padding_dim is not None:
-                cam = cam[:original_dim, :]
+                if is_2d_layer is not None and is_2d_layer:
+                    cam = cam[:original_dim[0], :original_dim[1]]
+                elif is_3d_layer:
+                    cam = cam[:original_dim[0], :original_dim[1], :original_dim[2]]
+                else:
+                    cam = cam[:original_dim, :]
             cam_list.append(cam)
 
         return cam_list, bar_ranges
@@ -676,7 +776,9 @@ class CamBuilder:
                          data_names: List[str], data_sampling_freq: float = None, dt: float = 10,
                          aspect_factor: float = 100, bar_ranges: Tuple[np.ndarray, np.ndarray] = None,
                          channel_names: List[str | float] = None, time_names: List[str | float] = None,
-                         axes_names: Tuple[str | None, str | None] = None, contrastive_foil_class: int = None) -> None:
+                         axes_names: Tuple[str | None, str | None] = None, contrastive_foil_class: int = None,
+                         video_fps_list: List[float] = None, video_list: List[np.ndarray] = None,
+                         show_single_video_frames: bool = False, channel_name: str = None) -> None:
         """
         Create plots displaying the obtained CAMs, set their axes, and show them as multiple figures or as ".png" files.
 
@@ -713,54 +815,80 @@ class CamBuilder:
         :param contrastive_foil_class: (optional, default is None) An integer representing the comparative class (foil)
             for the explanation in the context of Contrastive Explanations. If None, the explanation would follow the
             classical paradigm.
+        :param video_fps_list: (optional, default is None) A list of floats, representing the frames-per-second of each
+            input video to be explained. For 3D CAMs only.
+        :param video_list: (optional, default is None) A list of np.ndarrays, where each array represents an input video
+            to be overlapped onto the corresponding CAM. For 3D CAMs only.
+        :param show_single_video_frames: (optional, default is False) A boolean flag indicating whether to store single
+            frames with the corresponding CAM. For 3D CAMs only.
+        :param channel_name: (optional, default is None) A string representing the name of the channel being explained.
         """
 
         if not os.path.exists(results_dir_path):
             os.makedirs(results_dir_path)
 
         is_2d_layer = self._is_2d_layer(self._get_layers_pool(extend_search=self.extend_search)[target_layer])
+        is_3d_layer = is_2d_layer is None
 
         n_cams = len(cam_list)
         for i in range(n_cams):
             map = cam_list[i]
             data_name = data_names[i]
+            if contrastive_foil_class is None:
+                title_str = ("CAM for class '" + self.class_names[target_class] + "' (confidence = " +
+                             str(np.round(predicted_probs[i] * 100, 2)) + "%) - true label " +
+                             self.class_names[data_labels[i]])
+            else:
+                title_str = ("Why '" + self.class_names[target_class] + "' (confidence = " +
+                             str(np.round(predicted_probs[i][0] * 100, 2)) + "%), rather than '" +
+                             self.class_names[contrastive_foil_class] + "'(confidence = " +
+                             str(np.round(predicted_probs[i][1] * 100, 2)) + "%)?")
 
             # Display CAM
-            plt.figure()
-            norm = self.__get_norm(map)
+            is_overlapped = False
+            if not is_3d_layer:
+                plt.figure()
+                norm = self.__get_norm(map)
 
-            if map.shape[1] == 1:
-                aspect = int(map.shape[0] / aspect_factor) if map.shape[0] > aspect_factor else 100
-                map = np.transpose(map)
-            else:
-                if is_2d_layer:
-                    aspect = "auto"
-                else:
-                    aspect = 1
-                if not self.time_axs:
+                if map.shape[1] == 1:
+                    aspect = int(map.shape[0] / aspect_factor) if map.shape[0] > aspect_factor else 100
                     map = np.transpose(map)
-            plt.matshow(map, cmap=plt.get_cmap("inferno"), norm=norm, aspect=aspect)
+                else:
+                    if is_2d_layer:
+                        aspect = "auto"
+                    else:
+                        aspect = 1
+                    if not self.time_axs:
+                        map = np.transpose(map)
+                plt.matshow(map, cmap=plt.get_cmap("inferno"), norm=norm, aspect=aspect)
 
-            # Add color bar
-            self.__set_colorbar(bar_ranges, i)
+                # Add color bar
+                self.__set_colorbar(bar_ranges, i)
 
-            # Set title
-            if contrastive_foil_class is None:
-                plt.title("CAM for class '" + self.class_names[target_class] + "' (confidence = " +
-                          str(np.round(predicted_probs[i] * 100, 2)) + "%) - true label " +
-                          self.class_names[data_labels[i]])
+                # Set title
+                plt.title(title_str)
+
+                frames = None
             else:
-                plt.title("Why '" + self.class_names[target_class] + "' (confidence = " +
-                          str(np.round(predicted_probs[i][0] * 100, 2)) + "%), rather than '" +
-                          self.class_names[contrastive_foil_class] + "'(confidence = " +
-                          str(np.round(predicted_probs[i][1] * 100, 2)) + "%)?")
+                if video_list is not None:
+                    video = video_list[i]
+                    if channel_name is None:
+                        is_overlapped = True
+                else:
+                    video = None
+                frames = self.__render_3d_frames(map, title_str, bar_ranges=bar_ranges, batch_idx=i, video=video)
 
             # Set axis
             self.__set_axes(map, data_sampling_freq, dt, channel_names, time_names=time_names, axes_names=axes_names)
 
             # Store or show CAM
+            if is_3d_layer:
+                fps = video_fps_list[i] if video_fps_list is not None else 10
+            else:
+                fps = None
             self.__display_plot(results_dir_path, explainer_type, target_layer, target_class, contrastive_foil_class,
-                                data_name)
+                                data_name, frames=frames, fps=fps, is_overlapped=is_overlapped,
+                                show_single_video_frames=show_single_video_frames, channel_name=channel_name)
 
     def __get_data_for_plots(self, data_list: List[np.ndarray], i: int, target_item_ids: List[int],
                              cams_dict: Dict[str, List[np.ndarray]], explainer_type: str, target_layer: str,
@@ -769,7 +897,8 @@ class CamBuilder:
         Prepares input data and CAMs to be plotted, identifying the string key to retrieve CAMs, probabilities and
         ranges from the corresponding dictionaries.
 
-        :param data_list: (mandatory) A list of np.ndarrays to be explained, representing either a signal or an image.
+        :param data_list: (mandatory) A list of np.ndarrays to be explained, representing either a signal, an image, or
+            a video/volume.
         :param i: (mandatory) An integer representing the index of an item among the selected ones.
         :param target_item_ids: (optional, default is None) A list of integers representing the target item indices
             among the items in the input data list.
@@ -795,9 +924,7 @@ class CamBuilder:
         """
         batch_idx = target_item_ids[i]
         item = data_list[batch_idx]
-        item_key = explainer_type + "_" + target_layer + "_class" + str(target_class)
-        if contrastive_foil_class is not None:
-            item_key += "_foil" + str(contrastive_foil_class)
+        item_key = self.__get_item_key(explainer_type, target_layer, target_class, contrastive_foil_class)
         cam = cams_dict[item_key][batch_idx]
 
         item_dims = item.shape
@@ -889,6 +1016,7 @@ class CamBuilder:
         :return:
             - title: A string representing the title of the CAM for a given item and target class.
         """
+
         if contrastive_foil_class is None:
             title = ("'" + item_name + "': CAM for class '" + self.class_names[target_class] + "' (confidence = " +
                      str(np.round(predicted_probs[item_key][batch_idx] * 100, 2)) + "%) - true class " +
@@ -903,7 +1031,9 @@ class CamBuilder:
         return title
 
     def __display_plot(self, results_dir_path: str, explainer_type: str, target_layer: str, target_class: int,
-                       contrastive_foil_class: int, item_name: str = None, is_channel: bool = False) -> None:
+                       contrastive_foil_class: int, item_name: str = None, is_channel: bool = False,
+                       frames: List[np.ndarray] = None, fps: float = None, is_overlapped: bool = False,
+                       show_single_video_frames: bool = False, channel_name: str = None) -> None:
         """
         Show one CAM plot as a figure or as a ".png" file.
 
@@ -921,6 +1051,15 @@ class CamBuilder:
         :param item_name: (optional, default is False) A string representing the name of an input item.
         :param is_channel: (optional, default is False) A boolean flag indicating whether the figure represents graphs
             of multiple input channels, to discriminate it from other display modalities.
+        :param frames: (mandatory) A list of np.ndarrays representing frames to be saved as a GIF animation. This
+            parameter should be provided only for 3D (video/volume) explanations and it is set to None for 1D or 2D maps.
+        :param fps: (optional, default is None) An float, representing the frames-per-second of the input video to be
+            explained.
+        :param is_overlapped: (optional, default is False) A boolean flag indicating whether the CAM frames are
+            overlapped onto the original video frames. Only for 3D CAMs.
+        : param show_single_video_frames: (optional, default is False) A boolean flag indicating whether to store single
+            frames with the corresponding CAM. For 3D CAMs only.
+        :param channel_name: (optional, default is None) A string representing the name of the channel being explained.
         """
 
         if is_channel:
@@ -944,7 +1083,18 @@ class CamBuilder:
                         str(target_class))
             if contrastive_foil_class is not None:
                 filename += "_foil" + str(contrastive_foil_class)
-            filename += ".png"
+            if channel_name is not None:
+                filename += "_" + channel_name
+
+            single_frames_folder = None
+            if frames is None:
+                filename += ".png"
+            else:
+                if is_overlapped:
+                    filename += "_overlapped"
+                if show_single_video_frames:
+                    single_frames_folder = filename
+                filename += ".gif"
 
             # Communicate outcome
             descr_addon1 = "for item '" + item_name + "' " if item_name is not None else ""
@@ -954,32 +1104,53 @@ class CamBuilder:
                 tmp_txt += ", foil class " + self.class_names[contrastive_foil_class]
             self.__print_justify(tmp_txt + ") as '" + filename + "'...")
 
-            plt.savefig(os.path.join(filepath, filename), format="png", bbox_inches="tight", pad_inches=0,
-                        dpi=500)
+            out_path = os.path.join(filepath, filename)
+            if frames is None:
+                plt.savefig(out_path, format="png", bbox_inches="tight", pad_inches=0, dpi=500)
+            else:
+                imageio.mimsave(out_path, frames, fps=fps)
+                if show_single_video_frames:
+                    out_path = os.path.join(filepath, single_frames_folder)
+                    if single_frames_folder not in os.listdir(filepath):
+                        os.mkdir(out_path)
+                    for idx, frame in enumerate(frames):
+                        frame_filename = "frame_" + str(idx) + ".png"
+                        frame_path = os.path.join(out_path, frame_filename)
+                        imageio.imwrite(frame_path, frame)
             plt.close()
         else:
+            if frames is not None:
+                fig, ax = plt.subplots()
+                ax.axis("off")
+                im = ax.imshow(frames[0])
+                for f in frames:
+                    im.set_data(f)
+                    plt.pause(0.1)
             plt.show()
 
     @staticmethod
-    def _is_2d_layer(target_layer: torch.nn.Module | tf.keras.layers.Layer) -> bool:
+    def _is_2d_layer(target_layer: torch.nn.Module | tf.keras.layers.Layer) -> bool | None:
         """
         Evaluates whether the target layer is a 2D-convolutional layer.
 
         :param target_layer: (mandatory) A PyTorch module or a TensorFlow/Keras layer.
 
         :return:
-            - is_2d_layer: A boolean indicating whether the target layers 2D-convolutional layer.
+            - is_2d_layer: A boolean indicating whether the target layers 2D-convolutional layer. If the target layer is
+                a 3D-convolutional layer, the function returns a None.
         """
 
-        raise ValueError(str(target_layer) + " must be a 1D or 2D convolutional layer.")
+        raise ValueError(str(target_layer) + " must be a 1D, 2D, or 3D convolutional layer.")
 
     @staticmethod
-    def __normalize_cams(cams: np.ndarray, is_2d_layer: bool) -> Tuple[np.ndarray, Tuple[np.ndarray, np.ndarray]]:
+    def __normalize_cams(cams: np.ndarray, is_2d_layer: bool, is_3d_layer: bool) \
+            -> Tuple[np.ndarray, Tuple[np.ndarray, np.ndarray]]:
         """
         Adjusts the CAMs in value range (0-255), and returns the original importance score range.
 
         :param cams: (mandatory) A np.ndarray representing a batch of raw CAMs, one per item in the input data batch.
         :param is_2d_layer: (mandatory) A boolean indicating whether the target layers 2D-convolutional layer.
+        :param is_3d_layer: (mandatory) A boolean indicating whether the target layers 3D-convolutional layer.
 
         :return:
             - cams: A np.ndarray representing a batch of CAMs (normalised in the range 0-255), one per item in the input
@@ -989,8 +1160,10 @@ class CamBuilder:
             layer, and target class).
         """
 
-        if is_2d_layer:
+        if is_2d_layer is not None and is_2d_layer:
             axis = (1, 2)
+        elif is_3d_layer:
+            axis = (1, 2, 3)
         else:
             axis = 1
         maxima = np.max(cams, axis=axis, keepdims=True)
@@ -1028,20 +1201,33 @@ class CamBuilder:
         return time_steps, points
 
     @staticmethod
-    def __set_colorbar(bar_ranges: Tuple[np.ndarray, np.ndarray] = None, batch_idx: int = None) -> None:
+    def __set_colorbar(bar_ranges: Tuple[np.ndarray, np.ndarray] = None, batch_idx: int = None, norm: Normalize = None,
+                       ax: Axes = None) \
+            -> None:
         """
         Sets the colorbar describing a CAM, representing extreme colors as minimum and maximum importance score values.
 
         :param bar_ranges: (optional, default is None) A tuple containing two np.ndarrays, corresponding to the minimum
             and maximum importance scores per CAM for each item in the input data list, based on a given setting
             (defined by algorithm, target layer, and target class).
-        :param batch_idx: (mandatory) The index corresponding to the i-th selected item within the original input data
-            list.
+        :param batch_idx: (optional, default is None) The index corresponding to the i-th selected item within the
+            original input data list.
+        :param norm: (optional, default is None) A matplotlib.colors.Normalize object defining the normalization
+            used to map CAM importance scores to the colormap range. For 3D CAMs only.
+        :param ax: (optional, default is None) A matplotlib.axes.Axes object corresponding to the axes on which
+            the colorbar describing the CAM is rendered. For 3D CAMs only.
         """
 
         if bar_ranges is not None:
             bar_range = [bar_ranges[0][batch_idx], bar_ranges[1][batch_idx]]
-            cbar = plt.colorbar()
+            if norm is None:
+                cbar = plt.colorbar()
+            else:
+                sm = plt.cm.ScalarMappable(cmap="inferno", norm=norm)
+                sm.set_array([])
+                divider = make_axes_locatable(ax)
+                cax = divider.append_axes("right", size="4%", pad=0.05)
+                cbar = plt.colorbar(sm, cax=cax)
             minimum = float(bar_range[0])
             maximum = float(bar_range[1])
             min_str = str(minimum) if minimum == 0 else "{:.2e}".format(minimum)
@@ -1132,7 +1318,7 @@ class CamBuilder:
         return norm
 
     @staticmethod
-    def __print_justify(text: str, n_characters: int = 100) -> None:
+    def __print_justify(text: str, n_characters: int = 170) -> None:
         """
         Prints a message in a fully justified format within a specified line width.
 
@@ -1141,3 +1327,93 @@ class CamBuilder:
         """
         text = "\n".join(text[i:i + n_characters] for i in range(0, len(text), n_characters))
         print(text)
+
+    def __render_3d_frames(self, cam: np.ndarray, title_str: str, bar_ranges: Tuple[np.ndarray, np.ndarray],
+                           batch_idx: int, video: np.ndarray = None) -> List[np.ndarray]:
+        """
+        Renders a 3D CAM (e.g., temporal or volumetric activation map) into a sequence of RGB frames suitable for
+        visualization or GIF generation.
+
+        :param cam: (mandatory) A np.ndarray representing a CAM.
+        :param title_str: (mandatory) A string representing the title to be displayed on each frame.
+        :param bar_ranges: (optional, default is None) A tuple containing two np.ndarrays, corresponding to the minimum
+            and maximum importance scores per CAM for each item in the input data list, based on a given setting
+            (defined by algorithm, target layer, and target class).
+        :param batch_idx: (mandatory) The index corresponding to the i-th selected item within the original input data
+            list.
+        :param video: (mandatory) A np.ndarray to be explained, representing the input video/volume.
+
+        :return:
+            - frames: A list of np.ndarrays representing frames to be saved as a GIF animation. This parameter should be
+            provided only for 3D (video/volume) explanations and it is set to None for 1D or 2D
+                maps.
+        """
+        frames = []
+        norm = plt.Normalize(vmin=cam.min(), vmax=cam.max())
+        time_axs = 0 if self.time_axs is None else self.time_axs
+        for idx in range(cam.shape[time_axs]):
+            video_slice = np.take(video, idx, axis=time_axs) if video is not None else None
+            cam_slice = np.take(cam, idx, axis=time_axs)
+            cam_slice = (plt.get_cmap("inferno")(cam_slice / 255)[:, :, :3] * 255).astype(np.uint8)
+            fig, ax = plt.subplots(figsize=(10, 4), dpi=300)
+            ax.axis("off")
+            if video_slice is None:
+                output_slice = cam_slice
+            else:
+                if len(video_slice.shape) == 2:
+                    video_slice = video_slice[np.newaxis, :, :]
+                    video_slice = np.transpose(video_slice, (1, 2, 0))
+                output_slice = (0.6 * video_slice + 0.4 * cam_slice).astype(np.uint8)
+            ax.imshow(output_slice)
+            ax.set_title(title_str)
+
+            self.__set_colorbar(bar_ranges, batch_idx, norm=norm, ax=ax)
+            fig.canvas.draw()
+            w, h = fig.canvas.get_width_height()
+            buf = np.frombuffer(fig.canvas.tostring_argb(), dtype=np.uint8).reshape((h, w, 4))
+            frames.append(buf[:, :, 1:4])
+            plt.close(fig)
+        return frames
+
+    @staticmethod
+    def __get_item_key(explainer_type: str, target_layer: str, target_class: int,
+                       contrastive_foil_class: int) -> str:
+        """
+        Builds a string key to retrieve CAMs, probabilities and ranges from the corresponding dictionaries.
+
+        :param explainer_type: (mandatory) A string representing the desired algorithm for the explanation. This string
+            should identify one of the CAM algorithms allowed, as listed by the class constructor
+        :param target_layer: (mandatory) A string representing the target layer for the explanation. This string should
+            identify either PyTorch named modules, TensorFlow/Keras layers, or it should be a class dictionary key,
+            used to retrieve the layer from the class attributes.
+        :param target_class: (mandatory) An integer representing the target class for the explanation.
+        :param contrastive_foil_class: (mandatory) An integer representing the comparative classes (foils) for the
+            explanation in the context of Contrastive Explanations. If None, the explanation would follow the classical
+            paradigm.
+
+        :return:
+            - item_key: A string representing the considered setting (defined by algorithm, target layer, and target
+              class).
+        """
+
+        item_key = explainer_type + "_" + target_layer + "_class" + str(target_class)
+        if contrastive_foil_class is not None:
+            item_key += "_foil" + str(contrastive_foil_class)
+        return item_key
+
+    @staticmethod
+    def __check_data_names(data_names: List[str], data_list: List[np.ndarray] = None) -> List[str]:
+        """
+        Checks whether data names are provided for each item in the input data list. If not, default names are assigned.
+
+        :param data_names: (mandatory) A list of strings representing the names of the input items.
+        :param data_list: (optional, default is None) A list of np.ndarrays to be explained, representing either a
+            signal, an image, or a video/volume.
+
+        :return:
+            - data_names: A list of strings representing the names of the input items.
+        """
+
+        if data_names is None:
+            data_names = ["item" + str(i) for i in range(len(data_list))]
+        return data_names