图片相似度检查工具

这是一个基于 Python 的图片相似度检查和自动分类工具，包含两个主要功能：

1. 根据参考图片查找相似图片 (main.py)
2. 自动分析文件夹中的图片并按相似度分类 (auto_classifier.py)

🚀 功能特点

相似度检查 (main.py)

• 使用 OpenCV 和直方图比较算法计算图片相似度
• 支持多种图片格式：JPG, JPEG, PNG, BMP, TIFF, WEBP, HEIC
• 递归搜索子文件夹
• 可调节相似度阈值
• 支持结果输出到文件
• 带进度条显示

自动分类 (auto_classifier.py)

• 智能聚类算法自动分组相似图片
• 多特征融合：直方图、尺寸、颜色、边缘密度
• 自动创建分类文件夹并移动图片
• 生成详细分类报告
• 支持最小聚类大小设置
• HEIC 格式支持

📦 环境配置

1. 安装 Poetry

如果还没有安装 Poetry，请先安装：

# 使用官方安装脚本 (推荐)
curl -sSL https://install.python-poetry.org | python3 -

# 或者使用 pip 安装
pip install poetry

2. 安装项目依赖

# 克隆项目后，在项目根目录执行
cd similiarpiccheck

# 安装基础依赖
poetry install

# 如果需要 HEIC 格式支持
poetry install --extras heic

# 如果需要开发依赖（测试、代码格式化等）
poetry install --with dev

💻 使用方法

方法一：在 Poetry 环境中运行

# 激活环境
poetry shell

# 然后正常使用
python main.py reference.jpg ./images
python auto_classifier.py ./my_photos

方法二：使用 Poetry run

# 直接通过 Poetry 运行
poetry run python main.py reference.jpg ./images
poetry run python auto_classifier.py ./my_photos

方法三：使用预定义脚本

# 使用 Poetry 脚本快捷命令
poetry run similar-check reference.jpg ./images --threshold 0.8
poetry run auto-classify ./my_photos --min-cluster-size 3

📋 详细用法

相似度检查工具 (main.py)

基本用法

poetry run python main.py <参考图片路径> <搜索文件夹路径>

设置相似度阈值

poetry run python main.py reference.jpg ./images --threshold 0.8

保存结果到文件

poetry run python main.py reference.jpg ./images --output results.txt

自动分类工具 (auto_classifier.py)

基本分类

poetry run python auto_classifier.py /path/to/images

设置参数

# 设置相似度阈值和最小聚类大小
poetry run python auto_classifier.py /path/to/images --threshold 0.8 --min-cluster-size 5

预览模式（不移动文件）

poetry run python auto_classifier.py /path/to/images --dry-run

📋 参数说明

main.py 参数

• reference: 参考图片路径（必需）
• folder: 要搜索的文件夹路径（必需）
• --threshold, -t: 相似度阈值，范围 0.0-1.0，默认 0.7
• --output, -o: 输出结果文件路径（可选）

auto_classifier.py 参数

• folder: 包含图片的文件夹路径（必需，会递归搜索子目录）
• --threshold, -t: 相似度阈值，范围 0.0-1.0，默认 0.75
• --min-cluster-size, -m: 最小聚类大小，默认 3 张
• --dry-run: 仅分析不移动文件

📁 输出结构

自动分类工具会创建如下结构：

原文件夹/
├── classified_20240728_143052/
│   ├── similar_group_001_5pics/     # 相似图片组1 (≥3张)
│   ├── similar_group_002_4pics/     # 相似图片组2 (≥3张)
│   └── notclassified_15pics/        # 未分类图片 (<3张的组合)
└── classification_report_20240728_143052.txt

🔍 算法说明

相似度计算方法：

1. HSV 直方图：主要相似度指标（权重 40%）
2. 图像尺寸：分辨率相似度（权重 20%）
3. 宽高比：比例相似度（权重 15%）
4. 平均颜色：整体色调（权重 15%）
5. 边缘密度：图像复杂度（权重 10%）

聚类算法：

• 使用贪心聚类算法
• 以每张图片为种子，寻找相似图片
• 按聚类大小排序
• 小于最小聚类大小的图片合并到 notclassified 文件夹

🎯 支持的图片格式

• 常用格式：JPG, JPEG, PNG, BMP, TIFF, WEBP, GIF
• 苹果格式：HEIC, HEIF（需要安装 heic 扩展）
• 专业格式：RAW, CR2, NEF, ARW, PSD
• 其他格式：SVG, ICO

⚙️ 注意事项

• 相似度阈值建议设置在 0.6-0.8 之间
• 程序会自动跳过参考图片本身
• 搜索会递归包含所有子文件夹
• HEIC 格式需要安装 heic 扩展：poetry install --extras heic
• 自动分类工具会移动原始文件，建议先备份重要数据

📂 项目结构

similiarpiccheck/
├── pyproject.toml            # Poetry 配置文件
├── main.py                   # 相似度检查主程序
├── auto_classifier.py        # 自动分类工具
├── test_setup.py            # 环境测试脚本
├── requirements.txt          # 传统依赖文件（已弃用）
└── README.md                # 项目说明文档

🔧 开发环境

• Python: 3.8+
• 依赖管理: Poetry
• 主要依赖: OpenCV, NumPy, Pillow, tqdm, scikit-image
• 可选依赖: pillow-heif (HEIC 支持)
• 开发工具: pytest, black, flake8, mypy

📝 开发命令

# 运行测试
poetry run pytest

# 代码格式化
poetry run black .

# 代码检查
poetry run flake8 .

# 类型检查
poetry run mypy .

# 查看依赖
poetry show

# 更新依赖
poetry update

🚀 使用示例

# 安装项目
poetry install --extras heic

# 激活环境
poetry shell

# 查找相似图片
python main.py my_photo.jpg ./photo_collection --threshold 0.8

# 自动分类整个图片库
python auto_classifier.py ./my_photos --min-cluster-size 3

# 预览分类结果
python auto_classifier.py ./my_photos --dry-run

🤝 贡献

欢迎提交 Issue 和 Pull Request 来改进这个工具！

开发流程

1. Fork 本项目
2. 创建功能分支：git checkout -b feature/your-feature
3. 安装开发依赖：poetry install --with dev
4. 进行开发并运行测试：poetry run pytest
5. 提交代码：git commit -am 'Add some feature'
6. 推送分支：git push origin feature/your-feature
7. 创建 Pull Request