README.md

metadata

title: Kernel Convolution Visualizer
emoji: 🔍
colorFrom: blue
colorTo: purple
sdk: docker
sdk_version: latest
app_file: Dockerfile
pinned: false

Interactive Kernel Convolution Visualizer

An educational web application that demonstrates how image convolution works in real-time. Upload any image, choose from predefined kernels or create your own, and watch the convolution process step-by-step with detailed mathematical visualization.

Features

Core Visualization

• Step-by-step convolution animation - Watch the kernel matrix move across the image pixel by pixel
• Real-time mathematical display - See element-wise multiplication and summation for each output pixel
• Current patch highlighting - Visual indication of the image region under the kernel
• Progressive output rendering - Output image builds up as computation completes

Kernel Library

• Blur Filters: Box Blur (3×3, 5×5), Gaussian Blur (3×3, 5×5)
• Sharpen Filters: Standard Sharpen, Strong Sharpen, Unsharp Mask
• Edge Detection: Sobel X/Y/Combined, Prewitt, Roberts Cross, Laplacian
• Emboss: Multiple directional emboss effects
• Special Effects: Motion Blur, Outline, Ridge Detection
• Custom Kernel Builder: Create your own kernels (3×3 to 9×9)

Interactive Controls

• Play, Pause, Step Forward, Stop, Reset
• Adjustable animation speed (0.1x - 10x)
• Zoom and pan for pixel-level inspection
• Step mode for manual frame-by-frame advancement

Comparison & Analysis

• Side-by-side original vs processed view
• Split-view slider with draggable divider
• Synchronized zoom/pan between views
• Multiple kernel comparison tabs

Educational Features

• Real-time convolution equation with current values
• Kernel purpose and effect descriptions
• Padding strategy visualization (Zero, Reflect, Replicate, Wrap)
• Channel-wise processing explanation (RGB)
• Mathematical formula display

Export & Sharing

• Save processed images (PNG)
• Download convolution computation logs
• Shareable application state

Tech Stack

• Framework: Next.js 14+ (App Router) with TypeScript
• State Management: Zustand
• Animation: Framer Motion + Custom Canvas Animation Loop
• Styling: Tailwind CSS
• Visualization: HTML5 Canvas API
• Icons: Lucide React
• UI Components: Radix UI primitives

Getting Started

Prerequisites

• Node.js 18+
• npm, yarn, pnpm, or bun

Installation

# Clone the repository
git clone <repository-url>
cd kernel-convolution-visualizer

# Install dependencies
npm install

# Start development server
npm run dev

Open http://localhost:3000 in your browser.

Available Scripts

npm run dev       # Start development server
npm run build     # Build for production
npm run start     # Start production server
npm run lint      # Run ESLint
npm run type-check # Run TypeScript type checking

Project Structure

src/
├── app/                    # Next.js App Router pages
├── components/
│   ├── canvas/            # Canvas-based visualization components
│   ├── controls/          # Playback, zoom, overlay controls
│   ├── kernel/            # Kernel selector, editor, library
│   ├── comparison/        # Split view, side-by-side comparison
│   ├── education/         # Math display, kernel info panels
│   └── ui/                # Reusable UI components
├── hooks/                 # Custom React hooks
├── lib/
│   ├── convolution/       # Core convolution algorithms
│   ├── kernels/           # Predefined kernel definitions
│   ├── image/             # Image loading, processing utilities
│   └── export/            # Export functionality
├── store/                 # Zustand state management
├── types/                 # TypeScript definitions
└── utils/                 # Helper functions

Usage Guide

1. Upload an Image: Drag & drop or click the upload area in the left sidebar
2. Select a Kernel: Choose from categories (Blur, Sharpen, Edge Detection, etc.) or create a custom kernel
3. Watch Convolution: Press Play to see the kernel move across the image
4. Inspect Details: Zoom in to see pixel values, multiplications, and summation
5. Compare Results: Click "Show Comparison" for side-by-side or split view
6. Experiment: Try different padding strategies, toggle overlays, adjust speed
7. Export: Download the processed image

Convolution Visualization Explained

The visualization shows the mathematical operation at each step:

For each output pixel (x, y) and channel c:
1. Extract input patch: P[i][j] = image[x+i][y+j][c] for i,j in kernel
2. Element-wise multiply: M[i][j] = P[i][j] × K[i][j]
3. Sum: S = Σ M[i][j]
4. Normalize: output = S / Σ K[i][j] (if normalized)

Padding Strategies

• Zero Padding: Fill outside with zeros (default)
• Reflect Padding: Mirror the image at boundaries
• Replicate Padding: Repeat edge pixels outward
• Wrap Padding: Tile the image (torus topology)

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting
5. Submit a pull request

License

MIT License - feel free to use for educational and commercial purposes.

Acknowledgments

• Inspired by convolution visualizations in computer vision education
• Kernel definitions from standard image processing literature
• Built with Next.js, React, and modern web technologies