🎨 Visual Image Comparer

A powerful pixel-by-pixel image comparison tool with advanced visual diff overlay

Live Demo • Features • Quick Start • API Config • Deployment

📖 Overview

Visual Image Comparer is a sophisticated web application that enables precise visual comparison between two images. Built with Next.js and powered by ResembleJS, it provides pixel-level analysis with an interactive diff overlay, similarity percentage calculations, and comprehensive configuration options for various comparison scenarios.

🎯 Perfect For

UI/UX Testing: Detect visual regressions in web/mobile interfaces
A/B Testing: Compare design variations side-by-side
Screenshot Comparison: Validate rendering across browsers/devices
Quality Assurance: Automated visual testing in CI/CD pipelines
Design Review: Highlight subtle differences between design iterations
Game Development: Compare textures, sprites, and rendered frames

✨ Features

🔍 Core Capabilities

Pixel-Perfect Analysis: Compare images down to individual pixel differences
Visual Diff Overlay: Interactive color-coded difference highlighting
Similarity Percentage: Precise mismatch calculation (0-100%)
Dual Input Methods: Upload files OR paste image URLs
Real-time Preview: See base, actual, and diff images side-by-side
Threshold Control: Set acceptable difference tolerance (0-100%)
Pass/Fail Status: Automatic comparison verdict based on threshold

⚙️ Advanced Configuration

Output Settings

Error Color Customization: RGB color picker for diff highlighting
Error Type: Choose between flat, movement, or flatDifferenceIntensity
Transparency: Adjust diff overlay opacity (0.0 - 1.0)
Large Image Threshold: Optimize performance for large images
Cross-Origin Support: Handle CORS-protected images

Comparison Options

Scale to Same Size: Auto-resize images before comparison
Ignore Anti-aliasing: Skip anti-aliasing pixel differences
Ignore Colors: Compare structure only (grayscale)
Ignore Alpha Channel: Exclude transparency from comparison
Early Return Threshold: Stop analysis when threshold exceeded (performance boost)

🎨 User Experience

Responsive Design: Works seamlessly on desktop, tablet, and mobile
Dark/Light Mode: (Coming soon)
Drag & Drop: Upload images effortlessly
Image Download: Export diff results as PNG
Reset Functionality: Clear all inputs and start fresh
Tooltips & Help: User-friendly explanations for all options
Loading States: Visual feedback during processing
Error Handling: Graceful fallbacks with helpful error messages

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                   Full Stack (Netlify)                      │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  Frontend - Next.js 15.5 + React 18 + TypeScript     │  │
│  │  ├── Client-side ResembleJS (Browser)                │  │
│  │  ├── Shadcn/ui Components                            │  │
│  │  ├── Tailwind CSS                                    │  │
│  │  └── Image Upload & URL Input                        │  │
│  └──────────────────────────────────────────────────────┘  │
│                          ↕ HTTPS                            │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  Serverless API Routes (Netlify Functions)           │  │
│  │  ├── /api/health - Health check endpoint            │  │
│  │  ├── /api/compare-images - Image comparison         │  │
│  │  ├── Sharp (image processing)                        │  │
│  │  ├── Pixelmatch (comparison algorithm)              │  │
│  │  └── CORS-enabled responses                          │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

🔧 Technology Stack

Layer	Technology	Purpose
Frontend	Next.js 15.5	React framework with App Router
UI Library	Shadcn/ui	Accessible component system
Styling	Tailwind CSS	Utility-first CSS framework
Image Analysis	ResembleJS 5.0	Client-side pixel comparison
API	Next.js Routes	Serverless API endpoints
Image Processing	Sharp	Server-side image manipulation
Comparison	Pixelmatch	Server-side pixel comparison
Type Safety	TypeScript 5.0	Static type checking
Deployment	Netlify	CDN + Serverless Functions

🚀 Quick Start

📚 New to the project? Check out DEPLOYMENT.md for production deployment guide!

Prerequisites

Node.js >= 18.0.0
npm >= 9.0.0 or yarn >= 1.22.0

Installation

# Clone the repository
git clone https://github.com/Arghajit47/visual-image-comparer.git
cd visual-image-comparer

# Install dependencies
npm install

# Create environment file
cp .env.example .env.local

# Start development server
npm run dev

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

Environment Variables

Create .env.local in the root directory:

# API Configuration
NEXT_PUBLIC_API_URL=http://localhost:3000

# CORS Configuration (optional)
ALLOWED_ORIGIN=*

# Node Environment
NODE_ENV=development

💻 Usage

1️⃣ Basic Comparison

// Upload two images or provide URLs
// Click "Compare Images"
// View results: similarity percentage + diff overlay

2️⃣ Advanced Configuration

// Expand "Advanced Options" accordion
// Customize error color (default: magenta RGB(255, 0, 255))
// Adjust transparency (default: 0.3)
// Set comparison threshold (default: 0%)

3️⃣ API Integration

🎛️ Full API Documentation: See API_CONFIG.md for all configuration options!

POST /api/compare-images
Content-Type: application/json

{
  "baseImageSource": "data:image/png;base64,...",
  "actualImageSource": "https://example.com/image.png",
  "threshold": 5,
  "options": {
    "pixelmatch": {
      "threshold": 0.1,
      "diffColor": [255, 0, 255]
    },
    "resize": {
      "enabled": true,
      "strategy": "fill"
    },
    "output": {
      "format": "png",
      "includeMetadata": true
    }
  }
}

Response:

{
  "differencePercentage": 2.45,
  "status": "Passed",
  "diffImageUrl": "data:image/png;base64,...",
  "metadata": {
    "baseImage": { "width": 1920, "height": 1080 },
    "comparison": { "totalPixels": 2073600, "diffPixels": 50803 }
  },
  "error": null
}

🌐 Deployment

📖 Complete Guide: See DEPLOYMENT.md for detailed instructions!

Deploy to Netlify

Frontend + Serverless API in one deployment!

# 1. Push to GitHub
git push origin main

# 2. Connect to Netlify
# Dashboard → New site → Import from Git

# 3. Auto-configured via netlify.toml
# Build: npm run build
# Publish: .next
# Functions: Automatic (Next.js API routes)

# 4. Deploy! ✅

Features:

✅ Zero-config serverless functions
✅ Automatic HTTPS
✅ Preview deployments for PRs
✅ 100GB bandwidth/month (free)
✅ Support for all image formats (PNG, JPEG, WebP, GIF, SVG, AVIF, TIFF)

📂 Project Structure

visual-image-comparer/
├── src/
│   ├── app/
│   │   ├── api/
│   │   │   ├── compare-images/
│   │   │   │   └── route.ts          # Image comparison endpoint
│   │   │   └── health/
│   │   │       └── route.ts          # Health check endpoint
│   │   ├── globals.css               # Global styles
│   │   ├── layout.tsx                # Root layout
│   │   └── page.tsx                  # Home page
│   ├── components/
│   │   ├── ui/                       # Shadcn/ui components
│   │   ├── ImageComparer.tsx         # Main comparison component
│   │   └── ImageComparerLoader.tsx   # Client-side loader
│   ├── hooks/                        # Custom React hooks
│   └── lib/
│       └── utils.ts                  # Utility functions
├── .env.example                      # Environment template
├── .env.local                        # Local environment (git-ignored)
├── netlify.toml                      # Netlify config (serverless)
├── package.json                      # Dependencies
├── tsconfig.json                     # TypeScript config
├── API_CONFIG.md                     # 🎛️ API configuration guide
├── DEPLOYMENT.md                     # 🚀 Deployment instructions
└── README.md                         # You are here!

🔧 Configuration Options

📖 Full Documentation: See API_CONFIG.md for comprehensive configuration guide!

Quick Reference

Category	Options	Description
Pixelmatch	`threshold`, `diffColor`, `includeAA`	Comparison algorithm settings
Resize	`enabled`, `strategy`, `width`, `height`	Auto-resize configuration
Output	`format`, `includeMetadata`, `includeDiffBounds`	Response customization
Quality	`png`, `jpeg`, `webp`	Output image quality
Performance	`maxDimension`, `timeout`, `earlyExit`	Performance tuning

Example:

{
  "options": {
    "pixelmatch": { "threshold": 0.1, "diffColor": [255, 0, 255] },
    "resize": { "enabled": true, "strategy": "fill" },
    "output": { "format": "png", "includeMetadata": true }
  }
}

🧪 Testing

# Type checking
npm run typecheck

# Linting
npm run lint

# Test health endpoint
curl http://localhost:3000/api/health

🐛 Troubleshooting

CORS Errors

Issue: Access-Control-Allow-Origin blocked

Solution:

Set ALLOWED_ORIGIN environment variable in Netlify
Ensure https:// protocol is included
Remove trailing slashes from URLs
Check API routes return proper CORS headers

Large Image Performance

Issue: Slow comparison or browser freeze

Solution:

Enable "Scale to Same Size" option
Increase "Large Image Threshold" value
Set "Return Early Threshold" to stop at acceptable mismatch
Use server-side API for very large images

🤝 Contributing

Contributions are welcome! Please follow these steps:

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Commit changes: git commit -m 'Add amazing feature'
Push to branch: git push origin feature/amazing-feature
Open a Pull Request

📚 Documentation

README.md - You are here! Project overview and quick start
API_CONFIG.md - Complete API configuration reference
DEPLOYMENT.md - Production deployment guide

📄 License

This project is licensed under the MIT License - see LICENSE file for details.

🙏 Acknowledgments

ResembleJS - Powerful image analysis engine
Shadcn/ui - Beautiful component library
Next.js - React framework
Sharp - High-performance image processing
Pixelmatch - Fast pixel comparison
Netlify - Serverless deployment platform

📞 Support

🗺️ Roadmap

Made by Arghajit Singha

⭐ Star this repo if you find it helpful!

Name		Name	Last commit message	Last commit date
Latest commit History 50 Commits
.idx		.idx
.vscode		.vscode
docs		docs
src		src
.gitignore		.gitignore
.modified		.modified
API_CONFIG.md		API_CONFIG.md
DEPLOYMENT.md		DEPLOYMENT.md
README.md		README.md
api-requestbody-schema.json		api-requestbody-schema.json
components.json		components.json
netlify.toml		netlify.toml
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
tailwind.config.ts		tailwind.config.ts
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts
vitest.setup.ts		vitest.setup.ts

Arghajit47/Visual-image-comparer

Folders and files

Latest commit

History

Repository files navigation

🎨 Visual Image Comparer

A powerful pixel-by-pixel image comparison tool with advanced visual diff overlay

📖 Overview

🎯 Perfect For

✨ Features

🔍 Core Capabilities

⚙️ Advanced Configuration

Output Settings

Comparison Options

🎨 User Experience

🏗️ Architecture

🔧 Technology Stack

🚀 Quick Start

Prerequisites

Installation

Environment Variables

💻 Usage

1️⃣ Basic Comparison

2️⃣ Advanced Configuration

3️⃣ API Integration

🌐 Deployment

Deploy to Netlify

📂 Project Structure

🔧 Configuration Options

Quick Reference

🧪 Testing

🐛 Troubleshooting

CORS Errors

Large Image Performance

🤝 Contributing

📚 Documentation

📄 License

🙏 Acknowledgments

📞 Support

🗺️ Roadmap

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors 2

Uh oh!

Languages

Packages