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