An interactive, agency-grade web application designed to demystify deep learning for a 20-layer Convolutional Neural Network (CNN) trained on MNIST digit classification.
Built with Next.js 16, React 19, Tailwind CSS, HTML5 Canvas, SVG, and WebGL, this application executes 100% client-side forward pass inference and attribution math in pure TypeScript—visually rendering every filter kernel, feature map, batch normalization parameter, max pooling step, dense classification node, 3D latent vector embedding, and attribution heatmap in real time at 60 FPS.
Tip
You can launch and test the visualizer locally in less than 2 minutes using Node.js.
| Requirement | Supported Version | Notes |
|---|---|---|
| Node.js | v18.0.0 or higher |
Recommended LTS release |
| Package Manager | npm v9+, pnpm, or yarn |
Native npm included with Node |
-
Clone the repository:
git clone https://github.com/AmirHossein-84/Neural-Network-Visualizer.git cd Neural-Network-Visualizer/cnn-visualizer -
Install project dependencies:
npm install
-
Verify model manifest files: Ensure all 5 trained JSON manifests exist inside
cnn-visualizer/public/model/:- 📄
model_architecture.json - 📄
conv_weights.json - 📄
batchnorm_params.json - 📄
dense_weights.json - 📄
sample_predictions.json
- 📄
-
Start the local development server:
npm run dev
-
Open in browser: Navigate to http://localhost:3000.
- Overview
- Getting Started
- Key Features
- Visual Showcase
- Tech Stack
- System Architecture
- Project Structure
- License
Understanding the internal mechanisms of deep neural networks often feels like probing a black box. This visualizer exposes the inner workings of a trained 20-layer MNIST CNN model by enabling live digit drawing, real-time feature extraction inspection across 4 Conv2D layers, 1D/3D BatchNormalization tracking, 3D latent space embeddings, multi-mode explainability heatmaps, and interactive signal tracing through the Dense classification head.
Note
No backend or Python server is required during runtime. The model weights are loaded directly from static JSON manifests into a client-side TypeScript inference engine running on Web Worker background threads.
-
Interactive Canvas (
$280 \times 280$ ): Draw custom digits with natural, continuous brush strokes automatically downsampled live to$28 \times 28$ grayscale float matrices. - Sample Test Gallery: Load pre-packaged test images from the MNIST dataset complete with ground-truth labels and model output confidences.
-
Grad-CAM Pixel Sensitivity Heatmap: Calculates input pixel attribution gradients:
$$S(i, j) = \left|\frac{\partial y_{\text{pred}}}{\partial x_{i,j}}\right|$$ -
Occlusion Sensitivity Mapping: Slides a
$4 \times 4$ black mask across the grid to measure confidence drops: $$\text{Drop}{r,c} = P(y \mid x) - P(y \mid x{\text{masked } r,c})$$ - SmoothGrad Noise Reduction: Averages 15 saliency passes over noisy variations ($x + \mathcal{N}(0, \sigma^2)$) to eliminate visual noise artifacts.
-
Contrastive Explanations ("Why 7 and not 1?"): Computes differential saliency between target digit vs a rival digit:
$$\Delta S = \left|\frac{\partial y_{\text{target}}}{\partial x}\right| - \left|\frac{\partial y_{\text{rival}}}{\partial x}\right|$$ -
Receptive Field Inspector: Click any pixel in a feature map to highlight its exact
$3 \times 3$ spatial receptive field window. - Interactive 3x3 Filter Editor: Modify kernel weights live or apply presets (Sobel Horizontal/Vertical, Sharpen, Ridge Detect).
- 3D Latent Point Cloud: Interactive WebGL 3D projection of 1,000 MNIST test samples in 128D
dense_2feature space. White animated marker tracks your live hand-drawn digit position. - Architecture Battle: Side-by-side real-time probability comparison between the 20-Layer Deep CNN vs a 2-Layer Simple MLP.
- Interactive AI Game: Test your drawing skills against 3 difficulty levels (Easy, Medium, Hard) to trick the model into misclassifying ambiguous digit strokes.
- Score Tracking: Live score counters, high score persistence, and victory confetti animations when you successfully outsmart the neural network.
- 3-Column Locked Dock: Fixed bottom controller for step-by-step model execution tracing.
- Play Flow & Stepping: Automatically steps through all 20 layers every 1.2s or lets you step manually (
⏮ Prev/⏭ Next). - Auto-Tab Switching & Highlighting: Automatically switches between Conv Layers and Live Inference tabs, highlighting active layer cards in glowing cyan borders and scrolling them smoothly into view.
-
Interactive Node-Link Diagram: Visualizes the classification head sequence:
$$\text{Flatten (3136)} \longrightarrow \text{Dense 1 (256)} \longrightarrow \text{Dense 2 (128)} \longrightarrow \text{Output (10)}$$ - Hybrid Canvas + SVG Engine: GPU-accelerated 2D Canvas background line rendering with interactive SVG foreground nodes and viewport frustum culling.
-
Signal Pulse Particle Animation: Photon particles flowing along active weight paths (
Cyan = +Weight,Crimson = -Weight). -
Activation Threshold Slider: Filter out low-activation ReLU neurons (
$0.0 \dots 0.5$ ).
-
Full 10-Digit Report Export: Generates a downloadable
$680 \times 420\text{px}$ PNG snapshot card showing the drawn digit, top prediction confidence, and all 10 output probability bars (0-9) formatted cleanly in two columns.
graph TD
Client["Client Browser"] --> Next["Next.js 16 (App Router)"]
Next --> React["React 19 & Tailwind CSS v4"]
React --> CanvasEngine["HTML5 2D Canvas & WebGL"]
React --> Worker["Web Worker Thread"]
Worker --> Engine["Pure TS Inference & Attribution Engine"]
Engine --> Manifests["JSON Model Manifests (/public/model/)"]
| Layer | Technologies & Tools |
|---|---|
| Framework & UI | Next.js 16 (App Router), React 19, Tailwind CSS v4, Lucide Icons, Canvas Confetti |
| Language | TypeScript 5 |
| Graphics Engine | HTML5 2D Canvas, WebGL 3D Point Cloud, SVG Node-Link Diagram |
| Inference Engine | Pure TypeScript client-side forward pass (src/lib/inference.ts), Web Worker thread (src/workers/inference.worker.ts) |
| Model Training | Python 3, TensorFlow / Keras 2.x (train_mnist_model.py) |
The model is trained using Python (train_mnist_model.py) on Google Colab with GPU acceleration.
Important
The exact 20-layer Keras architecture sequence is:
Input(28, 28, 1)
➔ Conv2D(32, 3x3, relu, padding='same') ➔ BatchNorm ➔ Conv2D(32, 3x3, relu, padding='same') ➔ BatchNorm ➔ MaxPool2D(2,2) ➔ Dropout(0.25)
➔ Conv2D(64, 3x3, relu, padding='same') ➔ BatchNorm ➔ Conv2D(64, 3x3, relu, padding='same') ➔ BatchNorm ➔ MaxPool2D(2,2) ➔ Dropout(0.25)
➔ Flatten(3136)
➔ Dense(256, relu) ➔ BatchNorm ➔ Dropout(0.5)
➔ Dense(128, relu) ➔ BatchNorm ➔ Dropout(0.5)
➔ Dense(10, softmax)
The script exports 5 JSON manifests into cnn-visualizer/public/model/:
model_architecture.json: Layer manifest (types, names, output shapes, filter counts).conv_weights.json: Conv2D filter kernels[out_channels][3][3][in_channels]& biases.batchnorm_params.json: BatchNorm parameters (gamma,beta,moving_mean,moving_variance).dense_weights.json: Weight matrices[in_units][out_units]& bias vectors.sample_predictions.json: Pre-packaged MNIST test images with true labels & probabilities.cnn_mnist_model.keras: Native Keras model file.
Inference runs 100% client-side in TypeScript (src/lib/inference.ts) and Web Worker threads (src/workers/inference.worker.ts):
-
conv2dSame:$3 \times 3$ 2D Convolution with stride 1 and 'same' zero-padding + ReLU activation. -
batchNorm3D&batchNorm1D: Inference mode Batch Normalization transformation:$$y_i = \frac{x_i - \text{moving_mean}_i}{\sqrt{\text{moving_var}_i + \epsilon}} \cdot \gamma_i + \beta_i$$ -
maxPooling2D:$2 \times 2$ spatial Max Pooling with stride 2. -
flatten3D: Reshapes$[H, W, C]$ feature maps to 1D vector ($7 \times 7 \times 64 = 3136$ ). -
denseForward: Matrix vector multiplication$Y = \text{ReLU}(X \cdot W + B)$ . -
softmax: Exponential probability normalization for 10 output classes.
app/page.tsx (Main Viewport & Navigation Tabs)
├── DrawCanvas.tsx (280x280 Canvas + 28x28 Preview + Preset Digits)
├── SampleGallery.tsx (MNIST Test Set Carousel)
├── SaliencyOverlay.tsx (Grad-CAM, Occlusion, SmoothGrad & Contrastive Heatmaps)
├── OutputBars.tsx (Digit Probabilities & Winner Highlight)
├── ExportSnapshotButton.tsx (PNG 10-Digit Report Exporter)
├── ModelDebuggerBar.tsx (Persistent Playback Step Controller Dock)
├── ChallengeModeModal.tsx (Gamified AI Ambiguity Game)
├── LatentSpace3DModal.tsx (3D Latent Point Cloud & MLP Architecture Battle)
├── DenseLayerView.tsx (Hybrid Canvas/SVG Node-Link Classification Head)
│ └── NeuronDetailPanel.tsx (Dense Neuron Inspector)
├── ConvLayerView.tsx (Conv2D Layer Accordion)
│ ├── FilterGrid.tsx (3x3 Kernel Grid)
│ └── FeatureMapGrid.tsx (Channel Thumbnails + Receptive Field Inspector)
├── FilterEditorModal.tsx (Live 3x3 Kernel Editor)
├── BatchNormPanel.tsx (Mean/Variance Sparklines)
├── PoolingComparisonView.tsx (Before vs After 2x2 MaxPool)
└── DropoutCard.tsx (Inactive Rate Indicator)
Neural Network Visualizer/
├── cnn-visualizer/ # Next.js Web Application
│ ├── public/
│ │ └── model/ # Exported Trained Model JSON Manifests
│ │ ├── model_architecture.json
│ │ ├── conv_weights.json
│ │ ├── batchnorm_params.json
│ │ ├── dense_weights.json
│ │ ├── sample_predictions.json
│ │ └── cnn_mnist_model.keras
│ ├── src/
│ │ ├── app/ # App Router (page.tsx, layout.tsx)
│ │ ├── components/ # UI & Visualization Components
│ │ ├── lib/ # Inference Engine & Attribution Math
│ │ └── workers/ # Background Web Worker Thread
│ ├── package.json
│ └── tsconfig.json
├── train_mnist_model.py # Colab Python Training & JSON Exporter Script
├── cnn_mnist_model.keras # Trained Keras Model Artifact
├── conv_weights.json # Conv2D Weights Manifest
├── batchnorm_params.json # BatchNorm Parameters Manifest
├── dense_weights.json # Dense Head Weights Manifest
├── model_architecture.json # Architecture Manifest
├── sample_predictions.json # Test Samples Manifest
├── .gitignore
└── README.md
This project is licensed under the MIT License. Educational and personal use welcomed.