Local, privacy-respecting photo triage and organizer.

Detects blur, closed eyes, exposure issues, groups bursts, clusters faces, searches by visual semantics, and organizes folders by EXIF + quality.

---

Status

SnapGrade is ready for local culling workflows. It provides a FastAPI analyzer backend, SQLite metrics cache, CLI commands, and a React-based web dashboard. It features real-time face clustering, burst grouping, visual semantic search, and configurable quality thresholds.

---

Features & Visual Walkthrough

1. Interactive Contact Sheet & Triage (Web UI)

• Grid vs. Filmstrip Layouts: Switch between a dense contact sheet for rapid scanning, and Filmstrip mode (large hero image with bottom thumbnail strip) for fast arrow-key evaluation.
• Calibrated Themes: Choose between Film Lab (warm amber dark mode), Modern (cool dark grey), and Light Pro (high-contrast light mode) to suit your editing suite's lighting conditions.

---

2. Sharpness & Subject-Aware Detection

• Three Sharpness Signals: Combines Laplacian variance, Tenengrad gradient energy, and FFT directional energy to distinguish camera shake from out-of-focus blur.
• Subject-Aware Focus: Restricts sharpness analysis to detected subjects (using MediaPipe face landmarking or salient subject segmentation fallbacks) to avoid penalizing artistic background bokeh.

---

3. Burst Management (Best-of-Burst)

• Union-Find Grouping: Automatically identifies and groups near-duplicate burst sequences using 64-bit perceptual hashes and timestamp proximity.
• Best-of-Burst Selection: Ranks frames within a group based on a composite quality score (sharpness, smile, exposure, open eyes) and highlights the best candidate.

---

4. Face Detection & Clustering

• Cosine Similarity Grouping: Clusters detected faces using InsightFace buffalo_s embeddings.
• Person Cards: Generates cluster cards for every detected individual in the library, allowing single-click filtering of all images featuring that person.

---

5. Hierarchical Organization & XMP Export

• Custom Folder Templates: Structure your output folder tree using metadata tokens (e.g., {date:YYYY}/{camera_model}/{quality:verdict}). Supports symbolic links or copy/move operations.
• Lightroom Compatibility: Write verdicts, ratings (1–5 stars), and rejection reasons to industry-standard XMP sidecars that Lightroom, darktable, and Bridge read automatically.

---

Installation

1. Prerequisites

• macOS (Apple Silicon or Intel)
• Python 3.10+
• uv — fast Python package manager

Install uv if you don't have it:

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Clone and Install

git clone https://github.com/Bibyutatsu/SnapGrade.git
cd SnapGrade
uv sync --all-extras

3. Verify

uv run snapgrade --help

---

Documentation

For advanced setup, CLI usage, models registry, and configuration options, see:

• SnapGrade Complete Guide & Reference — Comprehensive guide to CLI commands, models, quickstart, and environment variables
• Brand & UI Design System — UI theme colors and visual guidelines

---

License

MIT