Feature/seg eigen cam (#580)

* new branch

* Add SegEigenCAM implementation and update README for new method

* Add SegEigenCAM to test suite for all CAM models

* Trigger CI

Author: Rafaelca70x

README.md

@@ -49,6 +49,7 @@ The aim is also to serve as a benchmark of algorithms and metrics for research o
 | FEM                 | A gradient free method that binarizes activations by an activation > mean + k * std rule.                                   |
 | ShapleyCAM          | Weight the activations using the gradient and Hessian-vector product.|
 | FinerCAM                |  Improves fine-grained classification by comparing similar classes, suppressing shared features and highlighting discriminative details.    |
+| SegEigenCAM         | Like EigenCAM but with gradient weighting (absolute gradients ⊙ activations) before SVD and sign correction to fix SVD sign ambiguity; designed for semantic segmentation |
 ## Visual Examples
 
 | What makes the network think the image label is 'pug, pug-dog' | What makes the network think the image label is 'tabby, tabby cat' | Combining Grad-CAM with Guided Backpropagation for the 'pug, pug-dog' class |
@@ -291,7 +292,7 @@ To use with a specific device, like cpu, cuda, cuda:0, mps or hpu:
 
 You can choose between:
 
-`GradCAM` , `HiResCAM`, `ScoreCAM`, `GradCAMPlusPlus`, `AblationCAM`, `XGradCAM` , `LayerCAM`, `FullGrad`, `EigenCAM`, `ShapleyCAM`, and `FinerCAM`.
+`GradCAM` , `HiResCAM`, `ScoreCAM`, `GradCAMPlusPlus`, `AblationCAM`, `XGradCAM` , `LayerCAM`, `FullGrad`, `EigenCAM`, `ShapleyCAM`, `FinerCAM` and `SegEigenCAM`.
 
 Some methods like ScoreCAM and AblationCAM require a large number of forward passes,
 and have a batched implementation.
@@ -374,3 +375,8 @@ Huaiguang Cai`
 https://arxiv.org/pdf/2501.11309 <br>
 `Finer-CAM : Spotting the Difference Reveals Finer Details for Visual Explanation`    
 `Ziheng Zhang*, Jianyang Gu*, Arpita Chowdhury, Zheda Mai, David Carlyn,Tanya Berger-Wolf, Yu Su, Wei-Lun Chao`
+
+
+https://doi.org/10.3390/app15137562 <br>
+`Seg-Eigen-CAM: Eigen-Value-Based Visual Explanations for Semantic Segmentation Models
+Ching-Ting Chung, Josh Jia-Ching Ying`

cam.py

@@ -8,7 +8,7 @@
     GradCAM, FEM, HiResCAM, ScoreCAM, GradCAMPlusPlus,
     AblationCAM, XGradCAM, EigenCAM, EigenGradCAM,
     LayerCAM, FullGrad, GradCAMElementWise, KPCA_CAM, ShapleyCAM,
-    FinerCAM
+    FinerCAM, SegEigenCAM
 )
 from pytorch_grad_cam import GuidedBackpropReLUModel
 from pytorch_grad_cam.utils.image import (
@@ -39,7 +39,7 @@ def get_args():
                             'scorecam', 'xgradcam', 'ablationcam',
                             'eigencam', 'eigengradcam', 'layercam',
                             'fullgrad', 'gradcamelementwise', 'kpcacam', 'shapleycam',
-                            'finercam'
+                            'finercam', 'segeigencam'
                         ],
                         help='CAM method')
 
@@ -79,7 +79,8 @@ def get_args():
         "gradcamelementwise": GradCAMElementWise,
         'kpcacam': KPCA_CAM,
         'shapleycam': ShapleyCAM,
-        'finercam': FinerCAM
+        'finercam': FinerCAM,
+        'segeigencam': SegEigenCAM,
     }
 
     if args.device=='hpu':

pytorch_grad_cam/__init__.py

@@ -16,6 +16,7 @@
 from pytorch_grad_cam.random_cam import RandomCAM
 from pytorch_grad_cam.fullgrad_cam import FullGrad
 from pytorch_grad_cam.guided_backprop import GuidedBackpropReLUModel
+from pytorch_grad_cam.seg_eigen_cam import SegEigenCAM
 from pytorch_grad_cam.activations_and_gradients import ActivationsAndGradients
 from pytorch_grad_cam.feature_factorization.deep_feature_factorization import DeepFeatureFactorization, run_dff_on_image
 import pytorch_grad_cam.utils.model_targets

pytorch_grad_cam/seg_eigen_cam.py

@@ -0,0 +1,62 @@
+import numpy as np
+from pytorch_grad_cam.base_cam import BaseCAM
+from pytorch_grad_cam.utils.svd_on_activations import get_2d_projection_with_sign_correction
+
+# Based on this paper:
+# https://doi.org/10.3390/app15137562
+# Chung, C.-T.; Ying, J.J.-C.
+# Seg-Eigen-CAM: Eigen-Value-Based Visual Explanations for Semantic Segmentation Models.
+# Applied Sciences, 2025, 15(13), 7562.
+
+
+class SegEigenCAM(BaseCAM):
+    """
+    Seg-Eigen-CAM: Eigen-Value-Based Visual Explanations for Semantic
+    Segmentation Models.
+
+    Extends Eigen-CAM with two contributions tailored for segmentation:
+
+    1. **Gradient Weighting** (Section 3.2.1): Element-wise product between
+       absolute gradients and activations (Eq. 10), providing local pixel-wise
+       spatial information instead of a global average.
+
+    2. **Sign Correction** (Section 3.2.2): Dynamically corrects the sign
+       ambiguity from SVD by comparing |max| vs |min| of the projection
+       (Eq. 13), ensuring salient regions are always positive.
+
+    Reference:
+        Chung, C.-T.; Ying, J.J.-C. Seg-Eigen-CAM: Eigen-Value-Based Visual
+        Explanations for Semantic Segmentation Models. Appl. Sci. 2025,
+        15(13), 7562. https://doi.org/10.3390/app15137562
+
+    Args:
+        model: The neural network model to explain.
+        target_layers: List of convolutional layers to extract activations from.
+        reshape_transform: Optional callable for non-standard activation shapes.
+    """
+
+    def __init__(self, model, target_layers, reshape_transform=None):
+        super(SegEigenCAM, self).__init__(
+            model,
+            target_layers,
+            reshape_transform,
+            uses_gradients=True,
+        )
+
+    def get_cam_image(
+        self,
+        input_tensor,
+        target_layer,
+        target_category,
+        activations,
+        grads,
+        eigen_smooth,
+    ):
+        # Step 1 — Gradient Weighting (Eq. 10):
+        # |grads| ⊙ activations captures pixel-wise spatial importance,
+        # using absolute values to include both positive and negative gradient
+        # contributions (unlike Grad-CAM which discards negative gradients).
+        weighted_activations = np.abs(grads) * activations
+
+        # Steps 2 & 3 — SVD + Sign Correction (Eq. 11-13)
+        return get_2d_projection_with_sign_correction(weighted_activations)

pytorch_grad_cam/utils/svd_on_activations.py

@@ -20,16 +20,59 @@ def get_2d_projection(activation_batch):
     return np.float32(projections)
 
 
-
 def get_2d_projection_kernel(activation_batch, kernel='sigmoid', gamma=None):
     activation_batch[np.isnan(activation_batch)] = 0
     projections = []
     for activations in activation_batch:
-        reshaped_activations = activations.reshape(activations.shape[0], -1).transpose()
-        reshaped_activations = reshaped_activations - reshaped_activations.mean(axis=0)
+        reshaped_activations = activations.reshape(
+            activations.shape[0], -1).transpose()
+        reshaped_activations = reshaped_activations - \
+            reshaped_activations.mean(axis=0)
         # Apply Kernel PCA
         kpca = KernelPCA(n_components=1, kernel=kernel, gamma=gamma)
         projection = kpca.fit_transform(reshaped_activations)
         projection = projection.reshape(activations.shape[1:])
         projections.append(projection)
     return np.float32(projections)
+
+
+def get_2d_projection_with_sign_correction(activation_batch: np.ndarray) -> np.ndarray:
+    """
+    Perform SVD on a batch of activation maps, project onto the first
+    principal component, and apply sign correction.
+
+    Sign correction addresses the inherent sign ambiguity of SVD:
+    decomposing A = U Σ Vᵀ is equivalent to (-U) Σ (-Vᵀ), so the sign
+    of the resulting projection is arbitrary. The correction ensures that
+    class-discriminative information aligns with the positive direction by
+    flipping the map when |min| > |max| (Eq. 13 in the paper).
+
+    Reference:
+        Chung, C.-T.; Ying, J.J.-C. Seg-Eigen-CAM. Appl. Sci. 2025,
+        15(13), 7562. https://doi.org/10.3390/app15137562
+
+    Args:
+        activation_batch: Array of shape (B, C, H, W).
+
+    Returns:
+        np.ndarray of shape (B, H, W) with dtype float32.
+    """
+    activation_batch[np.isnan(activation_batch)] = 0
+    projections = []
+
+    for activations in activation_batch:
+        reshaped = activations.reshape(activations.shape[0], -1).transpose()
+        reshaped = reshaped - reshaped.mean(axis=0)
+
+        _, _, VT = np.linalg.svd(reshaped, full_matrices=True)
+
+        projection = reshaped @ VT[0, :]
+        projection = projection.reshape(activations.shape[1:])
+
+        # Sign correction (Eq. 13): ensure salient regions are positive
+        if abs(projection.min()) > abs(projection.max()):
+            projection = -projection
+
+        projections.append(projection)
+
+    return np.float32(projections)

tests/test_run_all_models.py

@@ -11,7 +11,8 @@
     EigenGradCAM, \
     LayerCAM, \
     FullGrad, \
-    KPCA_CAM
+    KPCA_CAM, \
+    SegEigenCAM
 from pytorch_grad_cam.utils.image import show_cam_on_image, \
     preprocess_image
 from pytorch_grad_cam.utils.model_targets import ClassifierOutputTarget
@@ -52,7 +53,8 @@ def numpy_image():
                           EigenGradCAM,
                           LayerCAM,
                           FullGrad,
-                          KPCA_CAM])
+                          KPCA_CAM,
+                          SegEigenCAM])
 
 def test_all_cam_models_can_run(numpy_image, batch_size, width, height,
                                 cnn_model, target_layer_names, cam_method,