A robust, research-based implementation of Grad-CAM (Gradient-weighted Class Activation Mapping) with a production-ready REST API for visual explanations of ResNet18 predictions.
Grad-CAM is a technique for explaining what a convolutional neural network "looks at" when making a prediction. Given an image and a classification decision, Grad-CAM produces a visual heatmap highlighting which regions of the image were important for that specific prediction.
The method works by computing gradients—how the network's output changes relative to features in the final convolutional layer. These gradients serve as importance weights, allowing us to identify which learned features were decisive in the model's decision.
Modern deep learning models are often criticized as "black boxes." While they achieve high accuracy, we rarely understand why they make a particular decision. This opacity is problematic in high-stakes domains like medical diagnosis or autonomous driving.
Grad-CAM provides visual explanations that are:
- Interpretable: Human-understandable heatmaps showing which image regions matter
- Model-agnostic: Works with any CNN architecture without modifications
- Efficient: Requires only a single backward pass with minimal overhead
- Class-specific: Different classes produce different explanations for the same image
This transparency builds trust, enables debugging of model failures, and validates that the network learned meaningful patterns rather than spurious correlations.
Grad-CAM operates conceptually in three steps:
- Compute importance weights for each feature map by averaging gradients across spatial dimensions
- Combine feature maps with their importance weights, retaining only positive contributions
- Overlay the result on the original image as a heatmap
The outcome is a visual explanation showing which image regions contributed to the prediction.
Consider classifying a cat image with 95% confidence. Grad-CAM highlights the cat's face, whiskers, and ears—exactly the features a human would use. If the same image were misclassified as a dog, the heatmap would highlight different regions, revealing which features fooled the model.
This visual verification is crucial: it confirms the network learned meaningful patterns and didn't develop spurious correlations.
For detailed mathematical treatment: See docs/GRADCAM_THEORY.md
Production REST API (FastAPI) with ResNet18 inference, Grad-CAM visualization, and 53 comprehensive tests (100% pass rate).
Stack: FastAPI + PyTorch + Pydantic
Core: backend/app/ (main, api, inference, schemas) + backend/tests/ (53 tests)
Grad-CAM: gradcam/ (core logic, hooks, visualization)
API: GET /api/health · POST /api/predict · POST /api/predict/upload · GET /api/models · GET /api/colormaps
Tests: 53 comprehensive (100% pass rate). Run: pytest backend/tests/ -v
Details: backend/tests/README.md
Install: pip install -r requirements.txt
Run: uvicorn backend.app.main:app --host 0.0.0.0 --port 8000
Access: Swagger UI at http://localhost:8000/docs
Frontend: Streamlit UI at http://localhost:8501
streamlit run app.py
See requirements.txt for dependencies.
Configure via .env (see .env.example).
- Theory:
docs/GRADCAM_THEORY.md- Mathematical foundations - API: Auto-generated at
/docs(Swagger) and/redoc
✅ Production-ready REST API with 53 comprehensive tests and full documentation
Atharva Dharmadhikari
M.Sc Information and Communication Technology
Friedrich-Alexander-Universität Erlangen-Nürnberg (FAU)
📧 atharva.ad@outlook.com