TorchCAM：类别激活探索器

一种在 PyTorch (深度学习框架) 中利用卷积层特定类别激活的简便方法。

来源：图片来自 woopets（激活图由预训练的 Resnet-18 创建）

快速入门

配置您的 CAM

TorchCAM 利用 PyTorch 钩子机制 无缝检索生成类别激活图 (Class Activation Map, CAM) 所需的所有信息，无需用户额外操作。每个 CAM 对象都充当您模型的包装器。

您可以在 文档 中找到支持的所有 CAM 方法的完整列表，然后按如下方式使用：

from torchvision.models import get_model, get_model_weights
from torchcam.methods import LayerCAM

# Define your model
model = get_model("resnet18", weights=get_model_weights("resnet18").DEFAULT).eval()
# Set your CAM extractor
cam_extractor = LayerCAM(model)

请注意，默认情况下，检索 CAM 的层设置为最后一个非降采样卷积层。如果您希望调查特定的层，请在构造函数中使用 target_layer 参数。

获取类别激活图

一旦设置了 CAM 提取器，您只需要像往常一样使用模型对数据进行推理即可。如果需要任何额外信息，提取器会自动为您获取。

from torchvision.io import decode_image
from torchvision.models import get_model, get_model_weights
from torchcam.methods import LayerCAM

# Get a model and an image
weights = get_model_weights("resnet18").DEFAULT
model = get_model("resnet18", weights=weights).eval()
preprocess = weights.transforms()
img = decode_image("path/to/your/image.jpg")

input_tensor = preprocess(img)

with LayerCAM(model) as cam_extractor:
  out = model(input_tensor.unsqueeze(0))
  # Retrieve the CAM by passing the class index and the model output
  activation_map = cam_extractor(out.squeeze(0).argmax().item(), out)

如果您想可视化热力图，只需将 CAM 转换为 NumPy 数组：

import matplotlib.pyplot as plt
# Visualize the raw CAM
plt.imshow(activation_map[0].squeeze(0).numpy()); plt.axis('off'); plt.tight_layout(); plt.show()

或者如果您希望将其叠加在输入图像上：

import matplotlib.pyplot as plt
from torchvision.transforms.v2.functional import to_pil_image
from torchcam.utils import overlay_mask

# Resize the CAM and overlay it
result = overlay_mask(to_pil_image(img), to_pil_image(activation_map[0].squeeze(0), mode='F'), alpha=0.5)
plt.imshow(result); plt.axis('off'); plt.tight_layout(); plt.show()

安装

需要 Python 3.11（或更高版本）以及 uv/pip 来安装 TorchCAM。

稳定版本

您可以使用 pypi 安装该包的最后一个稳定版本，如下所示：

pip install torchcam

最新版本

另外，如果您希望使用尚未发布到正式版本中的项目最新功能，可以从源代码安装该包：

pip install torchcam @ git+https://github.com/frgfm/torch-cam.git

CAM Zoo

本项目由仓库所有者开发和维护，但其实现基于以下研究论文：

• Learning Deep Features for Discriminative Localization：原始的 CAM（类激活映射）论文
• Grad-CAM：GradCAM 论文，将 CAM 推广至没有全局平均池化的模型。
• Grad-CAM++：GradCAM++ 的改进版，用于更准确地计算像素级对激活的贡献。
• Smooth Grad-CAM++：将 SmoothGrad 机制与 GradCAM 结合。
• Score-CAM：类激活的分数加权，以获得更好的可解释性。
• SS-CAM：将 SmoothGrad 机制与 Score-CAM 结合。
• IS-CAM：基于积分的 Score-CAM 变体。
• XGrad-CAM：在敏感性和守恒性方面改进的 Grad-CAM 版本。
• Layer-CAM：利用梯度对激活的像素级贡献的 Grad-CAM 替代方案。

来源：YouTube 视频（激活图由 Layer-CAM 使用预训练的 ResNet-18 创建）

其他

文档

完整包文档可在 此处 获取，包含详细规格说明。

演示应用

提供了一个最小化演示应用供您体验支持的 CAM 方法！欢迎查看 上的实时演示。

如果您更喜欢自己运行演示，需要额外的依赖项 (Streamlit) 才能运行该应用：

pip install -e ".[demo]"

然后您可以通过运行以下命令在默认浏览器中轻松运行您的应用：

streamlit run demo/app.py

可视化脚本

提供了一个示例脚本，供您对同一图像上多种 CAM 方法生成的热力图进行基准测试：

python scripts/cam_example.py --arch resnet18 --class-idx 232 --rows 2

所有脚本参数均可使用 python scripts/cam_example.py --help 进行检查

性能基准测试

CAM 方法的目的是提供可解释性，它们通过指出对模型输出影响最大的因素来实现这一点。理想情况下，CAM 应该精确定位任何影响输出分类分数的视觉线索。为此，我们使用两个指标：

• 置信度提升（越高越好）：如果我们使用 CAM 掩码后的输入进行前向传播（保留 CAM 值最高处的原始像素值，最低处置零），数据集中有多少次分类概率得到了提升。
• 平均下降（越低越好）：如果我们使用 CAM 掩码后的输入进行前向传播（保留 CAM 值最高处的原始像素值，最低处置零），分类概率下降了多少。

CAM 方法	架构	平均下降 (↓)	置信度提升 (↑)
GradCAM	resnet18	0.2686	0.2250
GradCAMpp	resnet18	0.5271	0.1962
SmoothGradCAMpp	resnet18	0.2088	0.2499
LayerCAM	resnet18	0.1712	0.2819
GradCAM	mobilenet_v3_large	0.2678	0.3483
GradCAMpp	mobilenet_v3_large	0.3182	0.2535
SmoothGradCAMpp	mobilenet_v3_large	0.2681	0.2678
LayerCAM	mobilenet_v3_large	0.2526	0.2882

此基准测试是在 imagenette 的验证集上进行的，它是 Imagenet 的一个子集，输入大小为 (224, 224)。

您可以在自己的硬件上为任何 CAM 方法运行此性能基准测试，如下所示：

python scripts/eval_perf.py ~/Downloads/imagenette LayerCAM --arch mobilenet_v3_large

所有脚本参数均可使用 python scripts/eval_perf.py --help 进行检查

延迟基准测试

你渴望获得漂亮的激活图 (activation maps)，但不知道它们在延迟方面是否符合你的需求？

在下表中，你将找到所有 CAM（类激活映射）方法的延迟开销基准测试（不包含前向传播）：

CAM 方法	架构	GPU 均值 (标准差)	CPU 均值 (标准差)
CAM	resnet18	0.11ms (0.02ms)	0.14ms (0.03ms)
GradCAM	resnet18	3.71ms (1.11ms)	40.66ms (1.82ms)
GradCAMpp	resnet18	5.21ms (1.22ms)	41.61ms (3.24ms)
SmoothGradCAMpp	resnet18	33.67ms (2.51ms)	239.27ms (7.85ms)
ScoreCAM	resnet18	304.74ms (11.54ms)	6796.89ms (415.14ms)
XGradCAM	resnet18	3.78ms (0.96ms)	40.63ms (2.03ms)
LayerCAM	resnet18	3.65ms (1.04ms)	40.91ms (1.79ms)
CAM	mobilenet_v3_large	N/A*	N/A*
GradCAM	mobilenet_v3_large	8.61ms (1.04ms)	26.64ms (3.46ms)
GradCAMpp	mobilenet_v3_large	8.83ms (1.29ms)	25.50ms (3.10ms)
SmoothGradCAMpp	mobilenet_v3_large	77.38ms (3.83ms)	156.25ms (4.89ms)
ScoreCAM	mobilenet_v3_large	35.19ms (2.11ms)	679.16ms (55.04ms)
XGradCAM	mobilenet_v3_large	8.41ms (0.98ms)	24.21ms (2.94ms)
LayerCAM	mobilenet_v3_large	8.02ms (0.95ms)	25.14ms (3.17ms)

基础 CAM 方法无法与具有多个全连接层的架构配合使用*

此基准测试在笔记本电脑上进行了 100 次迭代，输入尺寸为 (224, 224)，以更好地反映普通用户可预期的性能。硬件配置包括用于 CPU 的 Intel(R) Core(TM) i7-10750H 和用于 GPU 的 NVIDIA GeForce RTX 2070 with Max-Q Design。

你可以按照以下方式在你的硬件上运行任何 CAM 方法的延迟基准测试：

python scripts/eval_latency.py SmoothGradCAMpp

可以使用 python scripts/eval_latency.py --help 检查所有脚本参数

示例笔记本

想要了解更多 TorchCAM 功能的说明吗？ 你可能想查看 Jupyter 笔记本，它们旨在为你提供更广泛的概览。

引用

如果你希望引用本项目，请随意使用此 BibTeX 引用：

@misc{torcham2020,
    title={TorchCAM: class activation explorer},
    author={François-Guillaume Fernandez},
    year={2020},
    month={March},
    publisher = {GitHub},
    howpublished = {\url{https://github.com/frgfm/torch-cam}}
}

贡献

想要扩展 CAM 的可能性范围吗？或者提交论文实现？任何形式的贡献都深表感谢！

你可以在 CONTRIBUTING 中找到简短指南，以帮助推动本项目发展！

许可证

根据 Apache 2.0 许可证分发。有关更多信息，请参阅 LICENSE。

TorchCAM 快速上手指南

TorchCAM 是一个轻量级工具，旨在简化 PyTorch 中卷积层特定类别激活的利用，帮助开发者快速生成类激活图（Class Activation Maps, CAM）以增强模型的可解释性。

1. 环境准备

• Python 版本：3.11 或更高
• 包管理器：pip 或 uv
• 前置依赖：确保已安装 PyTorch 和 torchvision（示例代码依赖这些库）

# 建议先安装基础深度学习框架
pip install torch torchvision

2. 安装步骤

通过 PyPI 安装最新稳定版：

pip install torchcam

如需使用尚未发布到正式版本的最新功能，可从源码安装：

pip install torchcam @ git+https://github.com/frgfm/torch-cam.git

3. 基本使用

配置 CAM 提取器

首先加载预训练模型并设置 CAM 提取器。默认情况下，CAM 将作用于最后一个非降采样卷积层。

from torchvision.models import get_model, get_model_weights
from torchcam.methods import LayerCAM

# 定义模型
model = get_model("resnet18", weights=get_model_weights("resnet18").DEFAULT).eval()
# 设置 CAM 提取器
cam_extractor = LayerCAM(model)

获取并可视化激活图

运行推理后，提取器会自动捕获所需信息。你可以通过指定类别索引获取激活图，并将其转换为 NumPy 数组进行可视化。

from torchvision.io import decode_image
from torchvision.models import get_model, get_model_weights
from torchcam.methods import LayerCAM

# 获取模型和图片
weights = get_model_weights("resnet18").DEFAULT
model = get_model("resnet18", weights=weights).eval()
preprocess = weights.transforms()
img = decode_image("path/to/your/image.jpg")

input_tensor = preprocess(img)

with LayerCAM(model) as cam_extractor:
  out = model(input_tensor.unsqueeze(0))
  # 通过传入类别索引和模型输出来获取 CAM
  activation_map = cam_extractor(out.squeeze(0).argmax().item(), out)

import matplotlib.pyplot as plt
# 可视化原始 CAM
plt.imshow(activation_map[0].squeeze(0).numpy()); plt.axis('off'); plt.tight_layout(); plt.show()

若希望将热力图叠加在原图上，可使用以下代码：

import matplotlib.pyplot as plt
from torchvision.transforms.v2.functional import to_pil_image
from torchcam.utils import overlay_mask

# 调整 CAM 大小并叠加
result = overlay_mask(to_pil_image(img), to_pil_image(activation_map[0].squeeze(0), mode='F'), alpha=0.5)
plt.imshow(result); plt.axis('off'); plt.tight_layout(); plt.show()