Image Cuter

Image Cuter 是一个面向商品图、服装图和批量素材处理的本地离线图片处理工作台。它把自动裁剪、模板拼接、文件夹批处理、AI 辅助裁切、任务进度和全局设置整合到一个 Windows 桌面应用中，适合需要反复处理大量图片素材的本地工作流。

当前公开版本为 0.2.0，采用 MIT 许可证开源。

主要功能

裁剪工作台

• 支持拖拽、选择文件和选择文件夹导入图片。
• 支持图片缩略图队列，便于快速确认已导入素材。
• 支持大图预览，横图、竖图和方图会按预览区域动态等比适配。
• 支持 紧凑、标准、宽松 三档裁剪边距。
• 支持固定裁剪比例或沿用默认比例策略。
• 支持批量队列处理，并在任务面板中查看处理进度、输出路径和失败信息。

自动裁剪引擎

后端核心逻辑位于 autocropcv Python 包中，主要能力包括：

• 读取常见图片格式：jpg、jpeg、png、bmp、tif、tiff、webp 以及部分 JPEG 变体扩展名。
• 使用背景估计、掩码阈值、连通域过滤和边界框扩展计算主体区域。
• 支持 rembg / U2Net 掩码预测，并保留启发式兜底路径。
• 可根据目标比例补边，保持输出构图一致。
• 对超大图片有降采样保护，降低内存压力。
• 输出失败时会尝试本地备用输出目录，减少因为目录权限导致的任务中断。

拼接模板

拼接页面用于快速生成组合展示图，支持：

• h2：两图左右拼接。
• v2：两图上下拼接。
• h3：三图横向拼接。
• g2：四图 2x2 宫格。
• 手动选择素材后导出拼接图。
• 自动生成不覆盖已有文件的输出文件名。

智能批处理

智能批处理面向按文件夹组织的大批量图片：

• 支持扫描一个或多个来源文件夹。
• 按目录自动生成分组。
• 对每个分组执行批量裁剪。
• 可按设置自动为分组输出生成拼接图。
• 保留任务进度、单项状态和失败信息，便于定位问题素材。

AI 裁切

AI 裁切用于处理主体边界复杂或需要语义理解的图片场景。当前支持的后端策略包括：

• heuristic：启发式策略，不依赖外部大模型，速度最快。
• groundingdino_sam：预留 GroundingDINO + SAM 适配入口，需要额外环境和适配器。
• qwen_vl：本地 Qwen-VL 语义理解裁切流程，需要本地模型、transformers、torch、torchvision 等运行依赖。

AI 裁切支持设置：

• 设计目标关键词，例如 neckline、logo、print、hem 等。
• 最大候选区域数量。
• 输出比例，例如默认 3:4。
• 本地模型仓库、本地模型目录和超时时间。
• 运行失败时回退到启发式裁切策略。

AI 模型文件不会包含在仓库中，需要按需自行准备。

任务面板

桌面端内置任务视图：

• 查看运行中、完成、失败任务数量。
• 查看最近任务。
• 查看单个任务进度、总数、完成数、失败数和取消数。
• 查看每张图片的输入路径、输出路径、状态、错误信息和额外元数据。
• 支持取消正在运行的任务。

设置

全局设置集中管理：

• 语言：中文 / English。
• 输出目录。
• 计算设备：auto、CPU 或 GPU 相关策略。
• 默认裁剪比例。
• 批处理拼接模式。
• AI 裁切后端、模型名称、本地模型目录、设计目标、候选区域数量、超时和输出比例。

CLI

除了桌面端，项目也保留 Python CLI：

autocropcv "C:\images" -o "C:\output" --recursive --margin normal
autocropcv img1.jpg img2.png -o out_dir --margin tight
autocropcv img1.jpg img2.jpg -o out_dir --stitch h2

CLI 支持：

• 文件或目录输入。
• 递归扫描目录。
• 三档边距。
• 覆盖输出。
• h2、v2、h3、g2 拼接模式。
• INFO / DEBUG 日志级别。

本地 API

Electron 桌面端会自动启动本地 FastAPI 后端。后端仅绑定本机回环地址，并使用一次性会话令牌保护接口。

主要接口：

• GET /health
• GET /settings
• PUT /settings
• POST /import/scan
• POST /jobs
• GET /jobs
• GET /jobs/{job_id}
• POST /jobs/{job_id}/cancel
• POST /stitch/export
• POST /open-path
• WS /ws/events

受保护接口需要 X-Session-Token 或 Authorization: Bearer <token>。

技术栈

桌面端

• Electron
• React
• TypeScript
• Vite
• Material Design 3 风格组件
• Playwright UI 回归测试

后端

• Python 3.11+
• FastAPI
• WebSocket
• OpenCV
• Pillow
• NumPy
• rembg / U2Net
• transformers / torch / torchvision，用于可选 AI 模型能力

项目结构

.
├─ autocropcv/
│  ├─ src/autocropcv/          # Python 后端、裁剪引擎、拼接和 AI 裁切逻辑
│  ├─ tests/                   # Python 测试
│  ├─ installer/               # 后端 PyInstaller 配置
│  ├─ desktop/
│  │  ├─ electron/             # Electron 主进程、preload、窗口控制
│  │  ├─ frontend/             # React + TypeScript 前端
│  │  ├─ tests/                # 桌面端单测与 UI 回归测试
│  │  └─ package.json
│  └─ pyproject.toml
├─ docs/                       # 调研、方案和执行计划文档
├─ tests/                      # 跨项目辅助测试
├─ LICENSE
└─ README.md

开发环境要求

• Windows 10/11，当前主要开发和验证平台。
• Python 3.11+。
• Node.js 20+。
• npm。
• 可选：CUDA / GPU 环境，用于部分 AI 或 ONNX Runtime GPU 场景。

本地开发

1. 安装 Python 后端

cd autocropcv
python -m venv .venv312
.\.venv312\Scripts\activate
pip install -e .

2. 安装桌面端依赖

cd desktop
npm install

3. 启动开发版桌面软件

npm run dev

开发模式会同时启动：

• Vite 前端开发服务器。
• Electron 桌面窗口。
• 本地 Python 后端服务。

4. 启动生产构建预览

npm run build:web
$env:IMAGE_CUTER_RENDERER_TARGET="dist"
npm run start

后端单独启动

调试本地 API 时可以单独启动后端：

cd autocropcv
.\.venv312\Scripts\python -m autocropcv.server.app_main --host 127.0.0.1 --port 43125 --token dev-token

测试

Python 测试

cd autocropcv
pytest

前端单元测试

cd autocropcv\desktop
npm run test:frontend:unit

Electron / 桌面端单元测试

cd autocropcv\desktop
npm run test:desktop:unit

UI 回归测试

cd autocropcv\desktop
npm run test:ui-regression

UI 回归会构建前端、启动测试页面、模拟桌面桥接和后端 API，并输出截图到本地 output/ui-regression。

Windows 打包

1. 构建 Python 后端资源

cd autocropcv
pyinstaller -y --clean "installer\Image Cuter Backend.spec"

2. 构建 Electron 安装包

cd autocropcv\desktop
npm run pack:win

Electron Builder 会从 ../dist/Image Cuter Backend 读取后端资源并打进安装包。

版本说明

• v0.1：公开仓库中原有版本，作为开源前的初始快照保留。
• v0.2：上传当前本地开发项目，包含新的桌面端布局、裁剪工作台缩略图队列、动态大图预览、窗口缩放稳定性修复、任务和元数据增强等改动。

注意事项

• 仓库不包含 node_modules、构建产物、模型文件、运行日志和本地测试输出。
• AI 模型需要自行下载或配置本地目录。
• 当前主要面向 Windows 桌面环境，其他平台需要额外验证。
• 本地 API 设计为 Electron 桌面端内部使用，不建议直接暴露到公网。

许可证

本项目基于 MIT License 开源。详见 LICENSE。