📷 Lighttable

本地优先的 AI 摄影挑片工作台

一次出行几百张 RAW，自动评分 / 分类 / 相似成组 → 你不用一张张看 → 逐组精选 → 一键导出 NEF 原档 + 修图 JPG。

纯本地运行，不依赖任何云服务或容器 —— 一个 Python 进程 + 一个前端，开箱即跑。

English (TL;DR) — Lighttable is a local-first AI photo-culling workbench: import hundreds of RAW files from one shoot, let it auto-score / classify / group-by-similarity, then keep the choice in your hands — review group by group and export the keepers as original NEF + edited JPG. Runs fully on your machine — no cloud, no containers, no GPU required (one Python process + one frontend). The AI only subtracts; you decide what stays.

Quickstart: npm install · pip install -r requirements.txt · the 4 small ML models ship in this repo — only the 1.7 GB CLIP model needs downloading: run scripts/fetch-models.sh (Linux/macOS) or scripts/fetch-models.ps1 (Windows). Then npm run dev and open http://localhost:5174. Set a library_root (your photo folder) and you're scanning. RAW editing / detection / LLM description are optional and degrade gracefully if absent. Full docs in Chinese below and in docs/.

lighttable-intro.mp4

_{📺 45 秒速览：几百张 RAW → 自动评分成组 → F 键逐组精选 → AF/鸟框证据复核 → 3D 流程与地图。逐项大图见下方「五个值得一看的功能」。}

---

为什么做这个

打鸟、风光、出游回来动辄几百上千张 RAW，逐张看完再挑是体力活。市面挑片工具要么是云服务、要么吃 GPU、要么不懂"对焦有没有咬在鸟身上"。Lighttable 想解决的就一件事：

把"一次拍摄的几百张" 压缩成"值得修的少数几张"，并把选择权牢牢留在你手里。

• 🧠 AI 只做减法，不替你决定：算法给评分、规则、证据（AF 框、鸟框、锐度），最终留哪张是你按一次键的事。
• 🔒 数据不出本机：照片、评分、修图全程本地；星级写回 NEF 的 XMP 边车，PS / Lightroom / 任何 DAM 都认。
• 🪶 零重型依赖：后端是 Python 标准库 HTTP + SQLite，核心只要 Pillow + numpy；鸟检测、RAW 修图、LLM 描述都是可选增强，缺了也能跑。

---

北极星工作流

导入 RAW ──▶ 自动筛选/分类 ──▶ 自动修图 ──▶ 人工复核 ──▶ 精选导出 ──▶ 不满意的去 PS/LR
 (NEF…)     评分·规则·相似组     RawTherapee    原图+修图对比   NEF原档+修图JPG

顶部常驻一条 5 步进度条（导入→整理→挑片→修图→导出），每一步"进来第一眼就知道这步在干嘛 + 一个主按钮指向下一步动作"，不会跳过去就懵。

---

✨ 五个值得一看的功能

🧩 相似组挑片 —— 几百张连拍，每组只留一张

时间连拍自动成组，一屏铺开一整组：星级、keeper、AI 建议精选全标好。按 F 留一张自动跳下一组，进度条一路推到 100%，不漏张也不重复看。

🐦 AF 框 + 鸟框 —— AI 给证据，不替你做决定

绿框 = YOLO 检测到的鸟，黄框 = 相机 AF 点，一眼看出"对焦有没有咬在鸟身上"；评分给出锐度 / 曝光 / 降级原因等完整证据链，Space 1:1 放大复核对焦。

🎨 修图对比 —— 左右一拉，前后立现

RawTherapee / darktable 自动修图后，A/B 滑块左右拉动对比修图前后；Profile Matrix 一次排队试多种风格，逐张选最顺眼的那版。

🗺️ 3D 拍摄地图 —— 照片打在中国地图上

有 GPS 的照片按拍摄地立在 3D 大屏上，拖拽旋转、缩放、点省份下钻，一眼看到自己去过哪、在哪拍得最多。

🏢 3D 流程可视化 —— 流水线是一间工作室

处理流水线拟人成一间 3D 办公室：质检员、修图师、标注师各守一个岗位，谁在干活、进度到哪实时看。

---

🛠️ 技术栈

层	选型
前端	React 19 + Vite 5 + TypeScript（无 UI 框架，lucide 图标）
后端	Python 3.11+ 标准库 http.server + SQLite（WAL）——无 Web 框架、无 ORM
影像	Pillow + numpy（核心）；OpenCV（质量/检测）；onnxruntime（可选，鸟/人脸检测）
RAW 修图	RawTherapee-cli / darktable-cli（可选）
元数据	exiftool（可选，XMP 写回 + RAW 预览抽取）
AI 描述/向量	任意 OpenAI 兼容端点（如 LM Studio，可选）

前端约 5300 行拆成 pages/(页面) · components/(共享组件) · lib/(纯函数)；后端按 engines/(算法引擎) · tasks/(任务编排) 分层，lighttable_api.py 为 HTTP 入口。

---

🚀 快速开始

1. 依赖

# 前端
node -v        # 需要 Node 18+
npm install

# 后端（建议虚拟环境）
python -m venv .venv
# Windows: .venv\Scripts\activate   |   macOS/Linux: source .venv/bin/activate
pip install -r requirements.txt     # Pillow + numpy + opencv-python
# 可选：鸟/人脸检测
pip install onnxruntime

模型：4 个小模型（YOLO 检测、YuNet 人脸、睁眼、美学头）已随仓库提供，开箱即用；只有 1.7G 的 CLIP 需单独下载—— 跑一次 bash scripts/fetch-models.sh（或 Windows powershell scripts/fetch-models.ps1，断点续传）。 不下也行，美学评分静默跳过，挑片主流程不受影响。来源与许可证见 models/README.md。

2. 配置

不用提前配 —— 第一次打开 Web 会进入配置向导，填一个照片目录就能开始扫描；外部工具路径等后续在「设置」页改，全部落在 data/settings.json。

偏好文件方式的话也可以：

cp settings.example.json data/settings.json   # 手动编辑，与设置页二选一

RAW 修图 / 鸟检测 / AI 描述都是可选项，留空则对应功能优雅降级。

3. 运行

npm run dev        # 同时起 Web(5174) + API(5175)

打开 http://localhost:5174 。第一次会弹出配置向导：填好照片目录 → 扫描图库 → 沿进度条走完 整理 → 挑片 → 修图 → 导出。

服务	端口	用途
Web	5174	Vite + React 管理端（唯一入口）
API	5175	本地 HTTP API

---

⌨️ 挑片快捷键（看图弹窗）

键	动作
1–5 / 0	打星级
P	直接给 5★
X	直接给 0★（淘汰）
F	标记/取消精选（相似组内单选，用于最终导出集）
← →	上一张 / 下一张
↑ ↓	上一组 / 下一组
Space / Z	1:1 放大查看对焦
U	撤销上次评分

---

⚙️ 可选增强

想要	装什么
RAW 自动修图	RawTherapee 或 darktable，在设置填 cli 路径
写回 XMP 星级 + 抽 RAW 预览	ExifTool，设置填路径
鸟 / 人脸检测	pip install onnxruntime + 一个 COCO YOLO 的 .onnx 模型（如 yolov5s/yolov8），设置填模型路径
中文描述 + 语义搜索向量	任意 OpenAI 兼容端点（如本地 LM Studio），配置向导里填端点 + 模型名

---

📁 项目结构

lighttable/
├─ src/                 # 前端
│  ├─ App.tsx           # 应用外壳：状态 / 路由 / 编排
│  ├─ pages/            # 各视图：Dashboard / Cull / Edit / Run / Review / ...
│  ├─ components/       # 共享组件：进度条 / 任务卡 / 面板头 ...
│  ├─ lib/              # 纯函数：format / photo / tasks / edit / health / dom / intent
│  ├─ appData.ts        # 纯数据与映射（规则、步骤、文案）
│  └─ types.ts          # 类型定义
├─ server/              # 后端
│  ├─ lighttable_api.py # HTTP 入口（标准库 http.server）
│  ├─ db.py             # SQLite schema + 增量迁移
│  ├─ engines/          # 算法：quality / cull / bird_detect / person_detect / autoedit / similarity_group
│  └─ tasks/            # 任务编排：scan / ingest / pipelines / xmp_write / runner ...
├─ scripts/             # dev / api 启动脚本
└─ requirements.txt

---

📚 文档

更详细的安装、配置与原理说明都在 docs/ 目录，建议从文档总览开始：

文档	内容
docs/README.md	文档总览与阅读导航
docs/installation.md	安装与首次运行
docs/user-guide.md	完整使用流程走查
docs/configuration.md	配置项与可选增强
docs/architecture.md	前后端结构与数据流
docs/scoring.md	挑片评分 / 规则降级 / 相似成组
CONTRIBUTING.md	参与贡献指南
CHANGELOG.md	版本变更记录

---

🔐 数据与隐私

• 所有运行数据落在 data/（SQLite、预览缓存、修图输出、导出），已 gitignore，不进仓库。
• data/settings.json 含你的本地路径与端点，同样不进仓库；开源分享前请确认无密钥。
• 照片始终在你指定的目录，Lighttable 只读取与生成派生文件，不上传任何第三方。

---

🤝 贡献 & 许可

欢迎 issue / PR。这是个人为自己打鸟挑片打造、再开源出来的工具，规则阈值偏向"鸟类 + AF 锐度"场景，其它题材可按需调 server/constants.py 里的阈值。

本项目以 MIT License 开源。

---

用 📷 和 ⌨️ 打磨，给所有"懒得一张张看片"的人。