# Image Diff Tool

**Repository Path**: thmse/image-diff-tool

## Basic Information

- **Project Name**: Image Diff Tool
- **Description**: 一款基于浏览器的专业级图片对比工具，支持像素级精确对比与感知哈希对比，提供可视化差异掩码、统计报告与多种导出格式。
- **Primary Language**: JavaScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-14
- **Last Updated**: 2026-05-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Image Diff Tool

> 一款基于浏览器的专业级图片对比工具，支持像素级精确对比与感知哈希对比，提供可视化差异掩码、统计报告与多种导出格式。

[English](#english) | [中文](#中文)

---

<a name="中文"></a>
## 中文

### 功能特性

- **三种对比算法**
  - **像素精确对比** (`pixelmatch`) — 逐像素比对，适合 UI 截图、设计稿验收
  - **感知哈希对比** (分块 SSIM 简化版) — 忽略微小色差，关注结构差异
  - **双算法并行** — 同时运行两种算法，提供多维度参考

- **多种图片来源**
  - 本地上传（拖拽 / 点击选择）
  - 远程 URL 加载（支持跨域图片）
  - 支持 PNG、JPG、WebP、GIF 格式

- **可视化差异展示**
  - 差异掩码图：红色高亮标记差异区域
  - 差异叠加层：在原图上半透明显示差异
  - 并排对比：左右对照 + 差异标注
  - 实时统计：相似度、差异比例、差异像素数、耗时

- **丰富的导出选项**
  - 差异掩码图：PNG / JPG
  - 对比报告：Markdown / JSON
  - 并排合成图：带统计信息的对比长图

- **交互体验**
  - 一键交换左右图片
  - 独立清除单张图片
  - 可调节像素阈值与感知容差
  - 暗色主题 UI，专注视觉对比

### 在线体验

```bash
# 克隆仓库
git clone https://github.com/yourusername/image-diff-tool.git
cd image-diff-tool

# 安装依赖
npm install

# 启动开发服务器
npm run dev
```

打开浏览器访问 `http://localhost:5173`

### 技术栈

| 技术 | 说明 |
|------|------|
| [React](https://react.dev/) 18 | UI 框架 |
| [Vite](https://vitejs.dev/) 6 | 构建工具 |
| [TypeScript](https://www.typescriptlang.org/) 5.6 | 类型系统 |
| [Ant Design](https://ant.design/) 5 | UI 组件库 |
| [pixelmatch](https://github.com/mapbox/pixelmatch) | 像素级对比引擎 |
| [file-saver](https://github.com/eligrey/FileSaver.js/) | 文件导出 |

### 项目结构

```
image-diff-tool/
├── public/                 # 静态资源
├── src/
│   ├── components/
│   │   ├── common/
│   │   │   └── CanvasRenderer.tsx    # Canvas 渲染器
│   │   ├── Controls/
│   │   │   └── ControlsPanel.tsx     # 对比设置面板
│   │   ├── DiffViewer/
│   │   │   └── DiffViewer.tsx        # 差异结果展示
│   │   ├── ImageUploader/
│   │   │   └── ImageUploader.tsx     # 图片上传组件
│   │   └── Layout/
│   │       └── AppLayout.tsx         # 页面布局
│   ├── hooks/
│   │   └── useDiff.ts                # 对比逻辑 Hook
│   ├── types/
│   │   └── index.ts                  # TypeScript 类型定义
│   ├── utils/
│   │   ├── diffEngine.ts             # 核心对比引擎
│   │   ├── exportUtils.ts            # 导出功能
│   │   └── imageUtils.ts             # 图片处理工具
│   ├── App.tsx                       # 主应用组件
│   ├── main.tsx                      # 入口文件
│   └── vite-env.d.ts                 # Vite 类型声明
├── index.html
├── package.json
├── tsconfig.json
├── vite.config.ts
└── .gitignore
```

### 核心算法说明

#### 像素精确对比
基于 [pixelmatch](https://github.com/mapbox/pixelmatch) 实现，通过设定阈值 (`0~255`) 判断像素是否差异：
- 阈值越低，检测越严格
- 自动对齐不同尺寸图片（取较小尺寸）
- 忽略抗锯齿像素（`includeAA: false`）
- 差异标记为红色，半透明叠加

#### 感知哈希对比
自定义分块 SSIM 简化算法：
- 将图片划分为 8x8 区块
- 计算每个区块的灰度均值差异
- 容差可调（`0~1`），过滤微小色差
- 更适合肉眼感知层面的差异检测

### 开发指南

```bash
# 安装依赖
npm install

# 开发模式
npm run dev

# 构建生产版本
npm run build

# 预览生产构建
npm run preview

# 代码检查
npm run lint
```

### 浏览器兼容性

- Chrome / Edge ≥ 88
- Firefox ≥ 78
- Safari ≥ 14

> 依赖 `Canvas` 与 `ImageData` API，IE 不支持。

### 贡献

欢迎提交 Issue 和 Pull Request！请阅读 [CONTRIBUTING.md](./CONTRIBUTING.md) 了解详情。

### 许可证

[MIT](./LICENSE) © 2026 Image Diff Tool Contributors

---

<a name="english"></a>
## English

### Features

- **Three Comparison Algorithms**
  - **Pixel-level** (`pixelmatch`) — precise per-pixel comparison, ideal for UI screenshots
  - **Perceptual Hash** (block-based SSIM) — ignores minor color differences, focuses on structural changes
  - **Dual Algorithm** — run both simultaneously for multi-dimensional analysis

- **Multiple Image Sources**
  - Local upload (drag & drop / click)
  - Remote URL loading (CORS-enabled images)
  - Supports PNG, JPG, WebP, GIF

- **Visual Diff Display**
  - Diff mask: red-highlighted difference regions
  - Overlay mode: semi-transparent diff on original
  - Side-by-side: left-right comparison with diff annotation
  - Real-time stats: similarity, diff percentage, pixel count, elapsed time

- **Export Options**
  - Diff mask image: PNG / JPG
  - Comparison report: Markdown / JSON
  - Side-by-side composite: annotated comparison image

- **UX**
  - One-click swap left/right images
  - Clear individual images
  - Adjustable pixel threshold & perceptual tolerance
  - Dark theme UI for focused visual comparison

### Quick Start

```bash
git clone https://github.com/yourusername/image-diff-tool.git
cd image-diff-tool
npm install
npm run dev
```

Visit `http://localhost:5173`

### Tech Stack

| Tech | Purpose |
|------|---------|
| React 18 | UI framework |
| Vite 6 | Build tool |
| TypeScript 5.6 | Type system |
| Ant Design 5 | UI components |
| pixelmatch | Pixel-level diff engine |
| file-saver | File export |

### License

[MIT](./LICENSE) © 2026 Image Diff Tool Contributors