# ImgProcess

**Repository Path**: weifd/img-process

## Basic Information

- **Project Name**: ImgProcess
- **Description**: 一款纯本地离线运行的 Windows 桌面图片批量处理工具。所有操作只在你自己的电脑上完成，不上传任何文件、不联网。
基于 Electron + sharp 构建，安装包开箱即用，源码开放（MIT 协议）。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-10-29
- **Last Updated**: 2026-10-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 图片批处理工具 (ImgProcess)

Gitee 仓库：<https://gitee.com/weifd/img-process>

一款**纯本地离线**运行的 Windows 桌面图片批量处理工具。所有操作只在你自己的电脑上完成，**不上传任何文件、不联网**。

基于 Electron + sharp 构建，安装包开箱即用，源码开放（MIT 协议）。

## 🖼️ 界面预览

**浏览图片**——选择文件夹后缩略图秒出，左侧文件夹树管理目录，显示名称 / 格式 / 大小 / 像素尺寸：

![浏览图片](docs/screenshot-browse.png)

**批量操作**——多选后一键批量压缩 / 重命名 / 转格式 / 移动 / 移到回收站（一次最多 100 张）：

![批量操作](docs/screenshot-action.png)

## ✨ 功能

### 浏览与管理
- **文件夹浏览**：选择文件夹后加载其中的图片（JPG / PNG / WebP / BMP / GIF / TIFF / AVIF），左侧文件夹树可展开/折叠、新建、重命名文件夹
- **小 / 中 / 大**三档缩略图尺寸，显示文件名、格式、大小、像素尺寸、修改时间
- **时间线归档**：一键按拍摄/修改日期分组浏览，每天多少张一目了然
- **相似度去重**：基于感知哈希（aHash / dHash / pHash + 汉明距离）自动找出相似的图片，归为一组放同一行，方便清理重复照片

### 批量操作（一次最多选 100 张）
- **移到回收站**：进入系统回收站，可恢复
- **批量重命名**：模板名 + 起始序号 + 序号位数 + 前缀/后缀，实时预览，重名自动避让
- **批量压缩**：智能压缩到指定大小以下（自动二分查找最优质量），或手动指定质量；可覆盖原文件或输出到 `compressed/` 子文件夹
- **批量转格式**：JPG / PNG / WebP / BMP / TIFF / GIF / AVIF 七种格式互转，覆盖原文件前会二次确认
- **移动到其他文件夹**：拖拽图片到左侧文件夹树，或用「移动到…」按钮选择目标

### 操作体验
- Windows 风格选择：**单击**选中/取消（可连续点选）、**Shift+点击**连选、**Ctrl+A** 全选、**双击**预览大图
- **Ctrl+Z 撤销**移动和批量重命名
- 处理成功的提示自动消失，只有出现失败项才弹出明细窗口
- 支持拖拽移动、处理结果绿色标记、单图预览与单独操作

## 📥 下载安装

**普通用户无需看下面的开发内容，直接下载安装包即可：**

> 前往 Gitee 仓库的 [**Releases（发行版）**](https://gitee.com/weifd/img-process/releases) 页面下载 `ImgProcess_x.x.x.exe`（或打包好的 zip）。

- 双击安装，可自选安装目录，安装后桌面出现「图片批处理工具」快捷方式
- 系统要求：**Windows 10 / 11（64 位）**，无需安装任何其他环境
- 首次运行如弹出 SmartScreen 提示（软件未签名），点击「更多信息 → 仍要运行」即可
- 完全离线运行，不收集任何数据

## 🛠️ 从源码构建（开发者）

### 环境要求

- Node.js ≥ 18
- npm
- Windows（打包 `.exe` 安装包；日常开发与调试其他平台代码也基本通用）

### 运行

```bash
git clone <本仓库地址>
cd imgprocess
npm install
npm start
```

### 测试

项目内置了一套自生成的测试数据与自动化测试（不依赖任何外部图片）：

```bash
npm run test:gen     # 生成测试图片到 test-images/（含子文件夹结构）
npm run test:ops     # 核心逻辑测试（扫描/压缩/转码/重命名/移动/哈希等 39 项）
npm run start:test   # 启动应用并自动加载测试目录，手动体验
npm run test:trash   # 回收站功能诊断
```

### 打包

```bash
npm run dist         # 生成 NSIS 安装包到 dist/
```

> 国内网络如下载 Electron 二进制失败，设置镜像后重试：
>
> ```bash
> export ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"
> export ELECTRON_BUILDER_BINARIES_MIRROR="https://npmmirror.com/mirrors/electron-builder-binaries/"
> npm run dist
> ```

## 📁 项目结构

```
├── main.js            # Electron 主进程：窗口、IPC、文件操作调度
├── preload.js         # 预加载脚本：安全暴露 API 给渲染进程
├── lib/
│   └── imaging.js     # 核心逻辑（纯 Node，无 Electron 依赖，可单元测试）
│                      #   扫描/压缩(二分质量)/格式转码/BMP编解码/
│                      #   重命名/移动/感知哈希(aHash/dHash/pHash)/相似分组
├── renderer/          # 渲染端 UI
│   ├── index.html
│   ├── style.css
│   └── app.js         # 视图渲染、选择逻辑、批量操作、撤销、拖拽
└── test/
    ├── gen-images.js  # 生成测试图片
    ├── diag-ops.js    # 核心逻辑自动化测试
    └── diag-trash.js  # 回收站诊断
```

### 架构要点

- **核心逻辑与 UI 解耦**：所有图像处理、文件操作都在 `lib/imaging.js`，是纯 Node 模块，不依赖 Electron，可以独立测试
- **感知哈希**：sharp 缩小 + 灰度后计算 aHash（8×8 均值）、dHash（9×8 差值）、pHash（32×32 手写 DCT 取低频），三个 64 位指纹的平均汉明距离 ≤ 10 判定为相似（`SIMILAR_THRESHOLD` 可调），union-find 分组
- **压缩**：智能模式下二分查找能压进目标大小的最高 JPEG/WebP 质量
- **BMP 兼容**：sharp 原生不支持 BMP，项目内实现了 24/32 位 BMP 编解码器
- **安全模型**：`contextIsolation` 开启，渲染进程无法直接访问 Node API，全部通过 `preload.js` 白名单 IPC

### 开发调试参数

```bash
npm start -- --folder=D:\photos            # 启动时直接加载指定目录
npm start -- --folder=test-images --screenshot=out.png   # 5 秒后自动截屏退出（UI 冒烟测试）
npm start -- --folder=test-images --demo=select          # 自动选中图片并打开批量压缩弹窗（演示/截图用）
```

> README 中的界面截图由 `--screenshot` + `--demo` 参数自动生成，存放在 `docs/` 目录。

## 📄 开源协议

[MIT License](LICENSE) — 可自由使用、修改、分发，请保留版权声明。