让 AI 协助初筛与分组，把最终的审美决定权留给自己。

片刻 是一款专为摄影师和摄影爱好者设计的本地照片双语/擂台式选片工具。它能够将一次拍摄中相似的几十甚至上百张照片自动归入“同一个瞬间”的组中，然后通过直观的 左右 A/B 擂台 PK 方式，让你快速挑出最满意的一张。

本项目完全免费！不收一分钱！

摄影师可以用它处理付费拍摄的客户照片；但绝对禁止把软件本身拿去卖钱。

• 个人使用——爱好者、学生、个人摄影师整理自己的照片
• 摄影师 / 工作室在日常拍摄业务中使用，包括处理付费客户的照片（拍摄服务是你卖的，软件只是你用的工具）
• 自由修改源码自用、提交 PR
• 在保留原始版权与许可的前提下，免费分享给朋友、同事、摄影社群

• 销售本软件（原版、改名、汉化、二次打包、上架商店——一律不行）
• 把本软件作为付费服务对外提供（付费 SaaS / 在线选片网站 / 收费小程序等）
• 转售、转授权、再许可
• 移除或隐藏"片刻"品牌、版权、作者联系方式
• 用"片刻"或近似名称分发改版软件

如果你想做的事情超出上面"允许"范围（比如把片刻嵌入你的付费产品、做付费 SaaS 等），请联系作者协商单独授权：

微信 15828377122

完整条款见 LICENSE（中文为准、附英文摘要）。

如果你发现有人在卖片刻 / 把它包装成付费服务，欢迎私信举报。

• 🔒 照片不出本地：除"土豪模式"外，所有分析、初筛、分组都在你自己的电脑里完成，不上传任何云端。
• 🤖 自动剔除明显废片：模糊、过曝、欠曝、闭眼，自动识别并归到一边，担心错杀可一键复核召回。
• 📁 把同一瞬间的连拍归到一组：理解"这几张是同一个画面"——同一个人、同一个场景、同一段时间，自动放在一起对比。
• ⚔️ 左右擂台两两对决：按 ← / → 选哪边更好，一组里只留一张（或几张），节奏极快。
• 📸 原生支持 RAW：
  • RAW+JPG 同名双拍：以 JPG 显示与分析，归档时 RAW 跟着自动一起搬走（含 .xmp 伴随文件）。
  • 纯 RAW：从 RAW 文件里直接取出预览图，秒级读图，不卡。
• 🔄 随时反悔、随时续做：
  • 多级撤销：单步撤销、整组重选、全局回头都可以。
  • 进度自动保存：随时关掉，下次启动接着上次继续。

你可以在首页自由切换三种模式，按你的电脑性能和照片类型选：

💡 选择建议：

• 拍物 / 风景 / 旧电脑 ➔ 选 极速，对静物、产品、多角度连拍非常稳。
• 拍人 / 婚礼 / 活动 ➔ 选 专家，能识别"同一个人不同姿势不同背景"并归为一组。
• 需要"人话退片理由" ➔ 选 土豪，会用大白话告诉你"左边小孩闭眼了"这种原因。

💡 强烈推荐小白用户使用 Trae（或 Qoder）：装好 Trae 后用它打开本项目文件夹，直接告诉 AI：

"先把 pip 换成阿里云源（https://mirrors.aliyun.com/pypi/simple/）或清华源（https://pypi.tuna.tsinghua.edu.cn/simple），再安装相关依赖并运行这个项目。"

国内默认走的 PyPI 官方源在没有梯子的情况下经常卡到超时，专家模式光依赖就有 2GB 多，不换源基本装不下来。换成阿里 / 清华镜像后整套依赖几分钟就能装完，剩下的交给 Trae 就行。

适合未安装 Python 环境或不熟悉命令行的用户。

1. 下载项目 ZIP 压缩包 并解压到本地。
2. 双击运行对应的启动器脚本：

注：启动器会自动在项目独立目录下下载并构建 Python 环境，不污染你的系统环境。国内用户默认启用 PyPI 和模型镜像，可以使用环境变量 PIANKE_NO_MIRROR=1 禁用镜像走官方源。

如果你已安装 Python 环境并希望手动控制：

# 1. 创建并激活虚拟环境
python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# 2. 安装项目依赖（包含所有模式的并集）
pip install -r requirements.txt

# 3. 运行服务（默认端口 5057，自动打开浏览器）
python app.py

# 常用参数：
python app.py --port 8080 --no-browser

⚠️ 开发模式提示：若手动安装依赖，可能因传递依赖导致 opencv-python 冲突。可运行以下命令修复：

pip uninstall -y opencv-python opencv-python-headless
pip install --force-reinstall --no-deps "opencv-contrib-python>=4.9"

1. 导入与配置：在首页选择工作模式，输入或拖入照片文件夹的绝对路径，点击 开始整理。
2. 分析与进度：系统流式显示扫描进度和预估剩余时间。
3. 初筛复核：平铺展示被自动淘汰的废片及原因。点击任意照片即可直接将其放回待分组列表。未点击的将直接归入淘汰区。
4. 分组预览与调参：预览分组效果。如果分组过细或过粗，可实时拖动滑块调节阈值并点击 重新分组 即时更新。
5. 左右擂台 PK：在相似组内进行两两对比。
   • ← / →：保留左侧 / 保留右侧 (对侧淘汰)
   • ↑ / ↓：全要 / 全不要
   • [ / ]：仅淘汰左侧 / 仅淘汰右侧 (处理单张图像损坏)
   • S：跳过本组 (暂存至队尾最后处理)
   • Z：切换缩放等级 (1x ➔ 2x ➔ 4x)，两图同步平移
   • Shift + Z：撤销当前组的上一步操作
6. 完成与导出：展示所有 Winner 照片，支持一键打开结果文件夹。

本工具采用单文件夹、单会话策略，会在你指定的照片目录下生成以下结构：

📂 你的照片文件夹/
├── 📂 winners/                # 最终胜出保留的照片 (你的成片)
├── 📂 losers/                 # 被淘汰的照片
├── 📄 .pic_selecter_state.json # 进度持久化文件 (可随时中断并继续)
└── 📂 _pic_selecter/          # 缓存与日志目录
    ├── 📂 thumbs/             # 缩略图缓存 (重复加载近乎瞬时)
    ├── 📄 log.txt             # 详细处理日志
    └── 📄 skipped.log         # 坏图/无法读取文件清单

你可以在首页的”更多选项”中选择以下归档模式：

• 移动模式（默认，推荐）：将原片直接移动到 winners/ 或 losers/ 目录。最省磁盘空间，符合一次性选片直觉。反悔时文件会无损搬回原位。
• 复制模式：原片保持不动，在 winners/ 和 losers/ 中创建副本。需要双倍磁盘空间。

在”更多选项”里还可以选择初筛强度：

• 标准：阈值较宽，只剔除明显废片，适合不放心 AI 判断时使用。
• 进阶（默认推荐）：阈值更严，能多拒一些疑似废片，进入擂台的图片更少。所有被淘汰的图都可以在复核页或完成页召回。

选片完成后，在 Winner 总览页点击 相机水印 可以为胜出的照片批量添加 EXIF 信息水印。 水印会读取照片的相机品牌、机型、镜头、焦距、光圈、快门、ISO、拍摄时间并合成在画面上， 也会自动匹配品牌 Logo（富士、佳能、尼康、索尼、徕卡、哈苏、奥林巴斯等）。

共 11 个样式 ID。详尽程度直接编码在样式名里（-详尽 带镜头·参数·时间； -极简 仅品牌 Logo + 机型）：

输出到 winners/watermarked_<时间戳>/ 子目录，保留原 EXIF（旋转标志归位），JPEG 92 质量、progressive。

1. 极速与专家模式下，所有照片完全在你的电脑里处理，没有任何照片或数据发往外部。
2. 程序起的服务只在你自己的电脑回环地址（127.0.0.1）上监听，局域网和外网设备都访问不到。
3. 接口做了严格的来源校验，防止任何外部网站偷偷调用。需要给脚本开启额外鉴权，可在启动前设置环境变量 PIC_SELECTER_TOKEN=你的口令。
4. ⚠️ 土豪模式例外：该模式下，照片的缩略图会被发到你配置的大模型服务商接口（按 token 计费）。对隐私要求极高的场景请只用极速或专家模式。

欢迎通过 GitHub Issues 提交反馈或建议。

15828377122