相似图片分组工具 (Image Similarity Grouper)

基于 scikit-image 的高性能相似图片分组工具，能够识别旋转、裁剪、压缩、水印等多种变换后的相似图片。

✨ 功能特性

支持识别以下类型的相似图片：

• 相同图片的缩放版本
• JPEG 重新压缩版本
• 亮度、对比度、轻微颜色变化
• 90°、180°、270° 旋转
• 任意角度旋转
• 局部裁剪、中心裁剪、边缘裁剪
• 图片加边框、留白
• 轻微透视变换
• 局部水印或文字覆盖
• 水平镜像（可选开启）

🚀 快速开始

安装依赖

pip install -r requirements.txt

或手动安装：

pip install numpy scipy scikit-image pillow

使用方法

预览模式（推荐先运行）：

python group_similar_images.py "path/to/photos" --dry-run

正式移动：

python group_similar_images.py "path/to/photos"

复制而不移动：

python group_similar_images.py "path/to/photos" --copy

开启镜像检测：

python group_similar_images.py "path/to/photos" --include-flips

📁 输出结果

运行后会在目标目录生成：

• similar_group_001/, similar_group_002/, ... — 相似图片分组目录
• similarity_report.csv — 详细的相似度检测报告
• 未分组的图片保留在原目录中

🔧 算法原理

1. 扫描目标目录第一层图片
2. 计算多方向、多裁剪感知哈希 (pHash)，快速筛选候选图片
3. 使用 SIFT 提取旋转、尺度不变特征点
4. 使用描述子匹配 (Lowe ratio test + cross-check)
5. 依次使用相似变换、仿射变换、单应性变换进行 RANSAC
6. 根据匹配内点数、内点比例、空间分布、覆盖率综合判断
7. 使用并查集 (Union-Find) 进行聚类分组
8. 将相似图片移动/复制到分组子目录
9. 输出 CSV 详细报告

两阶段筛选策略

1. 预筛选阶段：多方向 + 多裁剪 pHash，快速排除明显不相似的图片对
2. 精匹配阶段：SIFT 特征 + RANSAC 几何验证，确保高准确率

⚙️ 参数说明

基础参数

参数	默认值	说明
directory	-	待处理图片目录（必填）
--dry-run	False	仅预览，不移动文件
--copy	False	复制图片而不是移动
--group-prefix	similar_group	分组目录前缀
--report-name	similarity_report.csv	报告文件名

性能参数

参数	默认值	说明
--max-size	1600	SIFT 处理时图片长边最大像素
--phash-size	16	感知哈希边长（256位）
--phash-distance	100	多方向哈希最小距离阈值
--no-phash-filter	False	关闭感知哈希预筛选
--include-flips	False	额外检测水平镜像图片

匹配阈值

参数	默认值	说明
--max-ratio	0.80	Lowe ratio 阈值
--min-raw-matches	9	进入 RANSAC 所需最少匹配数
--min-inliers	10	判定相似所需最少内点数
--min-inlier-ratio	0.25	最小内点比例
--min-normalized-inliers	0.018	内点占较少特征点的最小比例
--min-coverage	0.035	内点包围盒的最小面积覆盖率
--min-spatial-spread	0.08	匹配点横纵跨度较小值的最低比例

RANSAC 参数

参数	默认值	说明
--residual-threshold	5.0	RANSAC 像素残差阈值
--max-trials	2000	RANSAC 最大迭代次数

📷 支持的图片格式

• .jpg, .jpeg
• .png
• .bmp
• .tif, .tiff
• .webp

📊 示例

项目包含示例图片和运行结果：

• examples/ — 9 张测试图片（包含各种变换）
• examples_result/ — 示例运行结果（4 个相似组）

运行示例：

python group_similar_images.py examples --dry-run

📝 CSV 报告字段

字段	说明
图片1 / 图片2	对比的两张图片文件名
最小pHash距离	多方向哈希中的最小汉明距离
最佳哈希组合	取得最小距离的哈希变体组合
SIFT匹配数	原始特征点匹配数量
RANSAC内点数	几何模型内点数量
内点比例	内点占总匹配数的比例
归一化内点比例	内点占较少特征点数量的比例
图片1覆盖率 / 图片2覆盖率	内点包围盒占图片面积的比例
图片1空间跨度 / 图片2空间跨度	匹配点空间分布跨度
最佳几何模型	similarity / affine / projective
估计旋转角度	估计的图片旋转角度
是否相似	最终判定结果
说明	详细的判定依据

📄 许可证

MIT License