# utkuozbulak/pytorch-cnn-visualizations architecture

> Architecture diagram of the GitHub repository utkuozbulak/pytorch-cnn-visualizations, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/utkuozbulak/pytorch-cnn-visualizations
- Repository: https://github.com/utkuozbulak/pytorch-cnn-visualizations

## Overview

##### Project Type and Purpose
- This is an open-source Python toolkit for Convolutional Neural Network (CNN) visualizations, implemented in PyTorch.
- It provides standalone scripts (one per visualization technique) that load a pretrained model (AlexNet or VGG), compute attribution or filter visualizations, and save results.

##### High-Level Architecture Overview
- The system follows a lightweight “script + shared library” pattern:
- Technique Modules (src/*.py) – each script is an entry point implementing one algorithm (gradcam.py, guided_backprop.py, etc.).
- Shared Utilities (src/misc_functions.py) – image I/O, preprocessing (ImageNet normalization), postprocessing (heatmap blending), file-saving.
- Model Loader – wraps torchvision’s model zoo to fetch pretrained AlexNet/VGG, exposes model.features and model.classifier.
- Data I/O – input_images/ contains sample inputs; results/ is the sink for generated visualizations.
- External Dependencies – PyTorch, torchvision, PIL, numpy, matplotlib.

##### Main Components and Their Relationships
[User]
└─ invokes one of the Technique Scripts
└─ imports Shared Utilities
└─ calls Model Loader to fetch pretrained network
└─ preprocesses input image via misc_functions
└─ runs forward pass → attaches hooks or gradient operations specific to the technique
└─ computes visualization maps (gradients, activations, optimized inputs)
└─ postprocesses maps into images/heatmaps via misc_functions
└─ writes output to the appropriate subfolder in results/

##### Architectural Patterns and Design Principles
- Pipeline Pattern: each script defines a fixed sequence—Load Model → Preprocess → Compute Attribution/Visualization → Postprocess → Save.
- Plugin-Style Extensibility: adding a new technique = new script + reuse misc_functions for I/O and model interfacing.
- Separation of Concerns:
- Scripts handle algorithm logic and parameter parsing.
- misc_functions centralizes data preparation and file operations.
- Model loading is abstracted to isolate dependency on model.features/classifier conventions.

##### Detailed Elements to Capture
- That each technique script:
- Loads an input image → normalizes → forwards through model → applies technique-specific backward or optimization routines → post-processes map → saves result.
- Preprocessing routines (normalize, to_tensor)
- Postprocessing routines (heatmap generation, blending, file saving).
- Model zoo dependency:
- torchvision.models API
- Pretrained weights (AlexNet, VGG)
- Input_images/ and results/ directories as external storage.

##### Final Advice
- Be thorough: capture each logical stage in the visualization pipeline.
- Keep it modular: group similar scripts under a “Techniques” component.
- Extensibility: indicate how to plug in new methods via the shared utils and loader interface.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Actors
    User(("User")):::actor

    %% Technique Scripts Module
    subgraph "Technique Scripts"
        TS["Techniques (N scripts)"]:::code
    end

    %% Shared Utilities
    SU["misc_functions.py"]:::code

    %% Model Loader
    ML["Model Loader\n(wrapper over torchvision.models)"]:::code

    %% External Libraries
    Torch(("torchvision.models API")):::extLib
    PyTorch(("PyTorch")):::extLib
    PIL(("PIL")):::extLib
    NumPy(("NumPy")):::extLib
    Matplotlib(("Matplotlib")):::extLib

    %% File System I/O
    Input[/"input_images/"/]:::fs
    subgraph "Results Directory"
        OutMain[/"results/"/]:::fs
        GV[/"gradient_visualizations/"/]:::fs
        HSV[/"hierarchical_gradient_visualization/"/]:::fs
        II[/"inverted_images/"/]:::fs
        LV[/"layer_visualizations/"/]:::fs
    end

    %% Connections
    User -->|"invokes"| TS
    TS -->|"imports"| SU
    TS -->|"calls"| ML
    SU -->|"reads"| Input
    SU -->|"writes"| OutMain
    ML -->|"fetches"| Torch
    Torch -->|"provides pretrained weights"| ML
    ML -->|"depends on"| PyTorch
    SU -->|"uses"| PIL
    SU -->|"uses"| NumPy
    SU -->|"uses"| Matplotlib

    %% Click Events
    click TS "https://github.com/utkuozbulak/pytorch-cnn-visualizations/tree/master/src/"
    click SU "https://github.com/utkuozbulak/pytorch-cnn-visualizations/blob/master/src/misc_functions.py"
    click Input "https://github.com/utkuozbulak/pytorch-cnn-visualizations/tree/master/input_images/"
    click OutMain "https://github.com/utkuozbulak/pytorch-cnn-visualizations/tree/master/results/"
    click GV "https://github.com/utkuozbulak/pytorch-cnn-visualizations/tree/master/results/gradient_visualizations"
    click HSV "https://github.com/utkuozbulak/pytorch-cnn-visualizations/tree/master/results/hierarchical_gradient_visualization"
    click II "https://github.com/utkuozbulak/pytorch-cnn-visualizations/tree/master/results/inverted_images"
    click LV "https://github.com/utkuozbulak/pytorch-cnn-visualizations/tree/master/results/layer_visualizations"

    %% Styles
    classDef code fill:#ADD8E6,stroke:#000,color:#000
    classDef extLib fill:#90EE90,stroke:#000,color:#000
    classDef fs fill:#FFFFE0,stroke:#000,color:#000
    classDef actor fill:#F0F0F0,stroke:#000,color:#000
```
