TorchCAM: class activation explorer¶

TorchCAM explains PyTorch models with spatial activation maps for images (classes, detected boxes, segmentation masks or VLM tokens) and signed input-token contributions for text decisions. The Streamlit explorer separates image classifiers, VLMs and decision models into lazily rendered tabs. The deployed demo is on HuggingFace Spaces 🤗

CAM visualization

Source: image from woopets (activation maps created with a pretrained Resnet-18)

This project is meant for:

⚡ exploration: assess which image regions or input tokens support a classification
🐛 debugging: compare predicted and expected classes, and save evidence that humans and AI agents can verify
👩‍🔬 research: quickly implement your own ideas for new CAM methods

Installation¶

Create and activate a virtual environment and then install TorchCAM:

pip install torchcam

Check out the installation guide for more options.

Having issues with gradients, hooks, or layer selection? See the troubleshooting guide.

Quick start¶

To explain one prediction and save the evidence, see Debug one prediction. For full control, use a CAM extractor directly. Get an image and a model:

from urllib.request import urlretrieve
from torchvision.io import decode_image
from torchvision.models import get_model, get_model_weights

# Get a model and an image
weights = get_model_weights("resnet18").DEFAULT
model = get_model("resnet18", weights=weights).eval()
preprocess = weights.transforms()
urlretrieve("https://github.com/pytorch/hub/raw/master/images/dog.jpg", "dog.jpg")
img = decode_image("dog.jpg")

input_tensor = preprocess(img)

Compute the class activation map:

from torchcam.methods import LayerCAM

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)

class_idx (the first argument) is the index in the model's output logits of the class to explain; argmax picks the top prediction, but any class index works. The call returns one activation map per target layer. See Advanced usage for batches, custom models and method selection.

TorchCAM extraction flow from model input and target-layer hooks to a class activation map.

Display it:

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

# Use the same spatial transforms as inference, before normalization.
model_image = center_crop(
    resize(img, preprocess.resize_size, interpolation=preprocess.interpolation, antialias=preprocess.antialias),
    preprocess.crop_size,
)
result = overlay_mask(to_pil_image(model_image), to_pil_image(activation_map[0].squeeze(0), mode='F'), alpha=0.5)
plt.imshow(result); plt.axis('off'); plt.tight_layout(); plt.show()

overlayed_heatmap

Text decisions¶

See Text decision models for input-token attribution, the API contract and Laya integration. Install the development version from source until the next release.

CAM zoo¶

Activation-based methods¶

CAM from "Learning Deep Features for Discriminative Localization"
Score-CAM from "Score-CAM: Score-Weighted Visual Explanations for Convolutional Neural Networks"
SS-CAM from "SS-CAM: Smoothed Score-CAM for Sharper Visual Feature Localization"
IS-CAM from "IS-CAM: Integrated Score-CAM for axiomatic-based explanations"

Gradient-based methods¶

Grad-CAM from "Grad-CAM: Visual Explanations from Deep Networks via Gradient-based Localization"
Grad-CAM++ from "Grad-CAM++: Improved Visual Explanations for Deep Convolutional Networks"
Smooth Grad-CAM++ from "Smooth Grad-CAM++: An Enhanced Inference Level Visualization Technique for Deep Convolutional Neural Network Models"
X-Grad-CAM from "Axiom-based Grad-CAM: Towards Accurate Visualization and Explanation of CNNs"
Layer-CAM from "LayerCAM: Exploring Hierarchical Class Activation Maps for Localization"
Finer-CAM from "Finer-CAM: Spotting the Difference Reveals Finer Details for Visual Explanation"
LeGrad from "LeGrad: An Explainability Method for Vision Transformers via Feature Formation Sensitivity"
RefineCAM from "How to Evaluate and Refine your CAM"

Next steps¶

Advanced usage — supported model and task boundaries, choosing the target layer, batched inputs, ViT/3D, and picking a method.
Troubleshooting — fixes for the requires grad error, NaN/blank maps, and hook issues.

Author¶

TorchCAM is created and maintained by François-Guillaume (F-G) Fernandez (@frgfm).