photo-organizer 照片智能整理工具
解决手机相册混乱问题：自动识别旅行、聚会等活动事件，将照片和视频整理成清晰的文件夹结构。
适用场景
- 手机照片导出后杂乱无章，想按旅行/活动自动归类
- 照片和视频混在一起，想按时间线整理
- 截图和照片混在一起，想分开存放
- 想保留拍摄地点信息用于分类
核心功能
1. 智能事件识别
自动检测照片中的旅行/活动事件，按「年份+节日+地点」命名：
2026年国庆厦门之旅/
2025年春节福建之旅/
2024年五一杭州之旅/
识别逻辑：
- 按拍摄时间排序，同一天的照片归为一组
- 组内按城市名聚类（GPS 坐标解析为城市）
- 自动识别春节、国庆、五一、端午、中秋等中国节日
- 至少 5 张照片才会形成一个事件
2. 年月归类
未归入事件的照片按拍摄时间分到 YYYY/MM/ 文件夹：
2024/
├── 01/
├── 03/
└── 12/
3. 截图自动分离
在年月文件夹内，截图单独放入 截图/ 子文件夹：
2024/06/
├── IMG_001.jpg
└── 截图/
└── Screenshot_20240615.png
4. 视频支持
支持常见视频格式（mp4、mov、mkv 等），通过 ffprobe 提取拍摄时间和 GPS 信息。
输出结构示例
输出目录/
├── 2026年国庆厦门之旅/
│ ├── IMG_001.jpg
│ ├── VID_002.mp4
│ └── IMG_003.jpg
├── 2025年春节福建之旅/
│ └── IMG_004.jpg
├── 2024/
│ ├── 01/
│ │ ├── IMG_005.jpg
│ │ └── 截图/
│ │ └── Screenshot_001.png
│ └── 06/
│ └── VID_006.mov
└── 其他/
└── IMG_no_exif.jpg
使用方法
python photo_organizer.py <源目录> <输出目录> [选项]
常用命令
# 预览整理计划（不实际操作）
python photo_organizer.py ~/Photos ~/Photos_整理 --dry-run
# 执行整理（复制模式）
python photo_organizer.py ~/Photos ~/Photos_整理
# 移动文件（而非复制）
python photo_organizer.py ~/Photos ~/Photos_整理 --move
# 详细输出每个文件的去向
python photo_organizer.py ~/Photos ~/Photos_整理 --dry-run --verbose
参数说明
| 参数 | 说明 | 默认值 |
|---|---|---|
--min-event-size N |
事件最少文件数，低于此数不形成事件 | 5 |
--time-gap HOURS |
时间间隔阈值，超过则切分为不同事件 | 24 小时 |
--move |
移动文件（默认为复制） | 关闭 |
--dry-run |
仅显示计划，不实际操作 | 关闭 |
--verbose, -v |
详细输出 | 关闭 |
支持的格式
照片： jpg, jpeg, png, gif, bmp, tiff, webp, heic, heif, avif, raw, cr2, nef, arw, dng 等
视频： mp4, mov, avi, mkv, wmv, flv, webm, m4v, 3gp, mts, m2ts 等
依赖安装
# 必需依赖
pip install Pillow
# 可选：安装 ffprobe 以获取视频的准确拍摄时间和 GPS
# macOS
brew install ffmpeg
# Ubuntu/Debian
apt install ffmpeg
# Windows: 从 https://ffmpeg.org 下载并添加到 PATH
特点
- 离线可用：不依赖网络，不采集或上传任何用户数据
- 跨平台：支持 macOS、Linux、Windows
- 安全操作：默认复制模式，不会修改原始文件
- 智能降级：无 GPS 信息时按时间分类，无 ffprobe 时用文件修改时间
适用范围与限制
适用范围：
- 包含 EXIF 元数据的照片（拍摄时间、GPS 坐标）
- 常见照片格式（jpg、png、heic 等）和视频格式（mp4、mov 等）
- 中国境内地理位置识别（内置省市坐标映射）
已知限制：
- 无 EXIF 时间信息的文件将按文件修改时间分类，可能不准确
- 无 GPS 信息的文件无法按地点归类，仅按时间分组
- 视频 GPS 信息依赖 ffprobe，需单独安装 FFmpeg
- 地理识别覆盖中国主要城市和省份，偏远地区可能无法识别
- 节日识别基于固定日期范围，农历节日（春节）需每年更新数据
安全说明：
- 本工具完全离线运行，不联网、不上传、不采集用户数据
- 默认使用复制模式，原始文件不会被修改或删除
- 使用 --move 参数时会移动文件，建议先用 --dry-run 预览
