README.md

---
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

```bash
# 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](http://localhost:3000) in your browser.

### Available Scripts

```bash
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