Skip to content

Alleyf/pianke

BranchesTags
 
 

Repository files navigation

片刻 (Pianke)

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

Python 3.10+ Platform License

界面预览

着陆页 分析进度 初筛复核
着陆页 分析进度 初筛复核
分组预览 擂台 PK 完成 · Winner 总览
分组预览 擂台 PK 完成

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

当前仓库同时提供两条桌面路径：

  • 轻量预览桌面壳：直接在本机把现有 Flask + Web 前端嵌进窗口，适合本地快速运行。
  • 正式可安装桌面版（Tauri 2.x）：Rust 原生安装包、可分发、可走 CI 构建，Python 后端会被 PyInstaller 打成 sidecar 二进制后随桌面应用一起分发，支持全部三种模式。

核心特性

  • 🔒 纯本地与隐私保护：除"天眼模式"外，所有照片的分析、初筛、分组均在本地完成，不上传任何云端，保护隐私。
  • 🤖 智能质量初筛：自动识别并剔除模糊、过曝、欠曝、闭眼等技术性废片，并支持一键复核召回。
    • 极速模式：多锐度指标融合（拉普拉斯 + Tenengrad + FFT 高频比 + 边缘宽度），可区分失焦与运动模糊，9 宫格局部曝光 + 构图分析。
    • 专家模式：NIMA（人像/风景偏好）+ MUSIQ（抓拍/纪实友好）+ CLIP-IQA+（构图偏好）三模型互补评分，配合 InsightFace 人脸检测（闭眼/人脸模糊/贴边裁剪）。
  • 📁 多信号相似分组：
    • 极速模式：4 Hash 融合（pHash + dHash + wHash + aHash）+ HSV 分块直方图 + ORB 几何强验证（BFMatcher + RANSAC 单应性）+ EXIF 时间/GPS + 文件名连号。
    • 专家模式：DINOv2 视觉语义 + 人脸特征识别 + EXIF 时间/GPS + 文件名序号，人像场景自动提升人脸权重。
  • ⚔️ 双图擂台比拼：通过 ←/→ 键盘快捷键在相似照片中进行两两对决，极速筛选。
  • 🧠 偏好学习：擂台选择过程中自动学习你对美学、锐度、亮度的偏好，用于优化 AI 候选排序。
  • 📸 RAW 格式原生支持：
    • RAW+JPG 双拍：以 JPG 进行极速分析与呈现，文件操作时 RAW 与 JPG 自动配对（包括 .xmp 伴随文件）同步搬运或重命名。
    • 纯 RAW 拍摄：毫秒级提取 RAW 内嵌预览图进行分析，不进行缓慢的 demosaic 解码。
    • 支持 CR2/CR3、NEF、ARW、DNG、RAF、ORF、RW2 等 13 种 RAW 格式。
  • 🔄 无损反悔与自动续做：
    • 多级撤销：支持单步撤销、整组重选及全局重做。
    • 进度保存：状态实时持久化于照片目录，随时关闭，下次启动自动恢复进度。

工作模式对比

你可以根据硬件配置和照片类型，在网页首页自由切换以下三种模式：

模式 核心定位 废片初筛方式 分组逻辑 首次启动开销 联网要求
极速 (Fast) 纯本地、极速、适合低配设备 多锐度融合 + 运动模糊区分 + 9 宫格曝光 + 构图分析 4 Hash 融合 + HSV + ORB 几何验证 + EXIF + GPS 约 200MB 依赖 完全不需要
专家 (Expert) 本地 AI、识人更准 NIMA + MUSIQ + CLIP-IQA+ 三模型互补 + InsightFace 人脸 DINOv2 + 人脸识别 + EXIF + GPS（人像场景人脸权重 ×2.5） 约 2-3GB 依赖 / 首次需下载 600MB 模型 仅首次下载模型
天眼 (Tycoon) 大模型视觉判定、人话解说 远程多模态大模型 (火山/OpenAI/SiliconFlow/DeepSeek等) 与专家模式相同 约 5MB 依赖 / 配置 API Key 每张图调用 LLM 接口

💡 选择建议：

  • 拍物/风景/低配电脑 ➔ 推荐 极速 (Fast) 模式，零模型依赖，对多角度、静物及产品图有非常稳定的分组表现。
  • 拍人像/婚礼/活动/主流设备 ➔ 推荐 专家 (Expert) 模式，能够精准识别"同人不同姿势不同背景"并归入同组。
  • 需要详细退片理由 ➔ 推荐 天眼 (Tycoon) 模式，大模型将以"人话"解释退片原因（如"左侧小孩闭眼了"）。

快速开始

💡 强烈推荐小白用户使用 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. 双击运行对应的启动器脚本：
系统 启动脚本 首次运行安全提示过关方式
macOS 启动_macOS.command 若提示"身份不明的开发者"：按住 Control 键点击脚本 ➔ 选择 打开 ➔ 弹窗中再次点击 打开。
Windows 启动_Windows.bat 若弹出"Windows 已保护你的电脑"：点击 更多信息 ➔ 选择 仍要运行。
Linux 启动_Linux.sh 首次运行前执行 chmod +x 启动_Linux.sh，若缺少桌面 WebKit/GTK 组件，请按发行版安装。

注：启动器会自动在项目独立目录下下载并构建 Python 环境，不污染你的系统环境。国内用户默认启用 PyPI 和模型镜像，可以使用环境变量 PIANKE_NO_MIRROR=1 禁用镜像走官方源。桌面版默认开启；若你只想跑浏览器版，可在启动前设置 PIC_SELECTER_DESKTOP=0。

方式二：手动启动（适合开发者）

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

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

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

# 3. 运行桌面版（默认自动分配内嵌端口）
python app.py --desktop

# 4. 或运行浏览器版（默认端口 5057，自动打开浏览器）
python app.py

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

方式三：构建正式桌面安装包（Tauri）

如果你要的是可以分发给别人安装的桌面程序，请走这条：

# 1. 安装 Python 运行依赖 + 桌面打包依赖
pip install -r requirements.txt
pip install -r requirements-desktop-build.txt

# 2. 安装 Node / Tauri 前端壳依赖
npm install

# 3. 生成 Tauri 图标资源
python scripts/generate_tauri_icons.py

# 4. 本地开发调试桌面版
npm run desktop:dev

# 5. 构建安装包 / 分发包
npm run desktop:build

构建输出位于 src-tauri/target/release/bundle/，不同系统会生成各自常见格式：

  • Windows：.msi、.exe
  • macOS：.app、.dmg
  • Linux：.deb、.AppImage、.rpm（取决于本机环境）

仓库里还带了 GitHub Actions 工作流 desktop-build.yml，可用于 Windows / macOS / Linux 三端自动产出安装包。

⚠️ 开发模式提示：若手动安装依赖，可能因传递依赖导致 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/ 中创建副本。需要双倍磁盘空间。

相机水印

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

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

ID 名称 风格
A 标准底栏 白色信息条，左机型/镜头 ｜ 中品牌 Logo ｜ 右参数/时间
B_full / B_clean 极简底栏-详尽 / 极简底栏-极简 顶/左/右贴边窄白 + 底部居中 Logo + 信息
C_full / C_clean 毛玻璃悬浮-详尽 / 毛玻璃悬浮-极简 原图模糊作背景 + 缩小照片悬浮居中带阴影
D_full / D_clean 经典白边相框-详尽 / 经典白边相框-极简 顶/左/右窄白 + 底大白边居中放品牌
F_full / F_clean 杂志风-详尽 / 杂志风-极简 左下色卡（从图自动提取）+ 右下品牌信息
G 极简白边 照片四周均匀窄白边，无任何文字
H 相机回放 上原图 + 下模糊版 + 居中富士 X-T5，LCD 与取景器都显示画面

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

天眼模式 · LLM 提供商配置

天眼模式支持所有兼容 OpenAI 协议的视觉大模型。内置 5 个提供商，也支持自定义：

提供商 环境变量 说明
火山引擎 Ark ARK_API_KEY 默认提供商，需选择 Seed 系列视觉模型
OpenAI OPENAI_API_KEY 支持 GPT-4o 等视觉模型
SiliconFlow SILICONFLOW_API_KEY 硅基流动平台视觉模型
DeepSeek DEEPSEEK_API_KEY DeepSeek 视觉模型
自定义 CUSTOM_LLM_API_KEY 任意兼容 OpenAI 协议的视觉大模型接口

API Key 可在网页端录入并持久化保存到 ~/.config/pic_selecter/llm_keys/，也可通过环境变量设置（环境变量优先级更高）。

额外配置项：

  • LLM_MAX_WORKERS：并发上限，默认 20（硬上限 32）
  • LLM_INITIAL_CONCURRENCY：初始并发数，默认 10
  • LLM_TIMEOUT：单次请求超时秒，默认 30

常见问题 (FAQ)

1. 启动后没有弹出桌面窗口？ 如果你走的是轻量预览桌面壳，当前系统缺少桌面依赖时程序会自动回退为浏览器版；这时手动访问 http://localhost:5057 即可。若你希望固定走浏览器版，可在启动前设置 PIC_SELECTER_DESKTOP=0。如果你要真正可安装分发的桌面程序，请使用上面的 Tauri 构建流程。
2. 默认的 5057 端口被占用怎么办？ 在启动前设置环境变量改变端口：
  • macOS: export PIC_SELECTER_PORT=8080
  • Windows: set PIC_SELECTER_PORT=8080
后再运行启动器。桌面版默认会在未显式指定端口时自动挑一个空闲端口，通常不需要手动处理。
3. 专家模式首次启动卡在"加载模型"？ 由于首次运行需要下载约 600MB 的 AI 模型文件（DINOv2、NIMA、InsightFace 等），视网络情况可能需要 1-3 分钟。若长时间无响应，请检查终端日志或网络连接。国内用户启动器默认启用 HuggingFace 镜像。
4. 天眼 (Tycoon) 模式如何配置 API Key？ 在网页端选择天眼模式后，可在首页直接选择提供商并输入 API Key（Key 仅安全保存在本地 ~/.config/pic_selecter/llm_keys/）。 也可通过环境变量提前设置，如 ARK_API_KEY=你的key 或 OPENAI_API_KEY=你的key。
5. 极速模式与专家模式在质量初筛上有什么区别？ 两者的质量评估维度不同：
  • 极速模式：多锐度指标融合（拉普拉斯 + Tenengrad + FFT 高频比 + Marziliano 边缘宽度），可区分失焦与运动模糊；9 宫格局部曝光分析；Hough 变换检测地平线倾斜；显著性区域构图分析。零模型依赖。
  • 专家模式：NIMA（人像/风景偏好）+ MUSIQ（抓拍/纪实友好）+ CLIP-IQA+（构图偏好）三模型互补美学评分；InsightFace 人脸检测（闭眼/人脸模糊/贴边裁剪）；显著性区域锐度（对虚化主体更友好）。
6. 极速模式的分组为什么有时比专家模式更准确？ 极速模式使用 ORB 特征点 + RANSAC 单应性矩阵做几何强验证，对"是不是同一物理场景"有非常硬的判断。对于静物、产品、多角度拍摄，ORB 几何匹配比 DINOv2 语义特征更可靠。专家模式的人脸权重在人像场景优势更大。
7. 如何彻底卸载和清理缓存？
  • 清理照片缓存：直接删除对应照片目录下的 winners/、losers/、.pic_selecter_state.json 及 _pic_selecter/ 文件夹（移动模式下请先移回照片）。
  • 完全卸载程序：删除解压出的项目文件夹，并清理本地全局工具缓存：
    • macOS: rm -rf ~/.local/bin/uv ~/.local/share/uv/
    • Windows: 删除 %USERPROFILE%\.local\bin\uv.exe 和 %USERPROFILE%\.local\share\uv\
8. HEIC 格式图片在网页上无法预览？ Windows 系统可能需要安装微软官方的 HEIF 扩展才能正常在浏览器中预览该格式；片刻工具在后端能够正常分析处理该格式。
9. Tauri 打包时 PyInstaller 崩溃？ onnxruntime 和 insightface 包含大量 C/C++ 扩展模块，PyInstaller 的 --collect-submodules 在尝试导入时会触发访问违规。构建脚本已改用 --hidden-import 避免此问题。如仍遇到问题，请确保使用最新代码。

隐私与安全说明

  1. 本地模式下，所有照片数据、模型特征计算完全在本地运行，无任何外发流量。
  2. Web 服务器仅绑定本地 127.0.0.1 环回地址，局域网及外网设备均无法访问。
  3. 接口提供严格的 Origin 和 Referer 校验，防止跨站请求伪造 (CSRF/DNS Rebinding)。如果需要对脚本访问开启 token 鉴权，可在运行前设置环境变量 PIC_SELECTER_TOKEN=your_token。
  4. ⚠️ 天眼模式例外：该模式下，照片的缩略图会被发送至你配置的大模型服务商接口。如果对数据隐私有极高要求，请仅使用极速或专家模式。

技术架构

┌─────────────────────────────────────────────────┐
│                   前端 (HTML/CSS/JS)              │
│  着陆页 → 分析进度 → 初筛复核 → 分组预览 → 擂台 PK   │
│                         → Winner 总览 → 水印导出    │
├─────────────────────────────────────────────────┤
│              Flask Web Server (app.py)            │
│  REST API + SSE 流式事件 + Origin/Referer 安全校验  │
├──────────┬──────────┬──────────┬────────────────┤
│  极速模式  │  专家模式  │  天眼模式  │    公共模块      │
│          │          │          │                │
│ fast_    │ vision.  │ llm_     │ grouper.py     │
│ quality  │ py:      │ judge.py │  (分组编排)      │
│ .py:     │ DINOv2   │          │                 │
│ 多锐度    │ NIMA     │ 多 Provider│ clustering.py  │
│ 融合     │ MUSIQ    │ 支持      │  (专家分组)      │
│ 9 宫格   │ CLIP-IQA │ 限流自适应 │                 │
│ 曝光     │ +        │          │ fast_clustering. │
│ 构图     │ Insight  │          │ py (极速分组)    │
│          │ Face     │          │                 │
│ fast_    │          │          │ watermark.py     │
│ cluster  │          │          │  (11 种样式)      │
│ ing.py:  │          │          │                 │
│ 4 Hash   │          │          │ desktop.py       │
│ + HSV    │          │          │  (pywebview)      │
│ + ORB    │          │          │                 │
└──────────┴──────────┴──────────┴────────────────┘

┌─────────────────────────────────────────────────┐
│           Tauri 桌面壳 (Rust + Webview)           │
│  lib.rs: 自动端口分配 + Python sidecar 管理        │
│  开发模式: 直接调用本地 python app.py               │
│  发布模式: PyInstaller 打包的 sidecar 二进制        │
└─────────────────────────────────────────────────┘

反馈与贡献

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


未来计划

  • 添加检查更新功能
  • 修复 GitHub Actions 打包发布速度缓慢且 Windows 下安装包失败的问题
  • 添加主题切换功能
  • 添加日志功能，记录操作过程中所有必要的日志，支持导出日志方便排错分析（比如记录视觉模型初筛失败等）
  • 添加tauri-plugin-llm支持内置模型赋能智能支持

About

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

github.com/Alleyf/pianke/releases

Topics

photography tarui

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 2

片刻 v0.1.1 Latest
May 27, 2026
+ 1 release

Packages

 
 
 

Contributors

Languages

  • Python 61.3%
  • JavaScript 18.6%
  • CSS 12.9%
  • HTML 5.3%
  • Rust 0.9%
  • Shell 0.7%
  • Batchfile 0.3%