https://github.com/ncoevoet/facet
Local AI photo scoring, culling, and gallery — score, organise, and explore your library with face recognition and semantic search. No cloud, no subscriptions.
https://github.com/ncoevoet/facet
aesthetic-quality angular clip computer-vision face-recognition fastapi image-analysis image-quality photo photo-culling photo-management photo-scoring photography pytorch self-hosted selfhosted sqlite topiq
Last synced: 17 days ago
JSON representation
Local AI photo scoring, culling, and gallery — score, organise, and explore your library with face recognition and semantic search. No cloud, no subscriptions.
- Host: GitHub
- URL: https://github.com/ncoevoet/facet
- Owner: ncoevoet
- License: mit
- Created: 2026-02-16T16:44:55.000Z (2 months ago)
- Default Branch: master
- Last Pushed: 2026-03-26T12:05:51.000Z (24 days ago)
- Last Synced: 2026-03-26T19:48:23.734Z (23 days ago)
- Topics: aesthetic-quality, angular, clip, computer-vision, face-recognition, fastapi, image-analysis, image-quality, photo, photo-culling, photo-management, photo-scoring, photography, pytorch, self-hosted, selfhosted, sqlite, topiq
- Language: Python
- Size: 25.3 MB
- Stars: 72
- Watchers: 1
- Forks: 6
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Facet
**Your photos deserve more than a star rating.** Facet is a local photo analysis engine that scores every image across 9 dimensions — from aesthetic appeal to face sharpness — then lets you browse, cull, and organize through an interactive web gallery. No cloud, no subscriptions, no API keys. Your photos stay on your machine.
## How It Works
1. **Scan** — Point Facet at a folder of photos. AI models analyze each image for quality, composition, faces, and more. Supports JPG and 10 RAW formats (CR2, CR3, NEF, ARW, RAF, RW2, DNG, ORF, SRW, PEF).
2. **Browse** — Open the web gallery to explore your library with filters, search, and multiple view modes.
3. **Cull** — Find your best shots instantly. Facet auto-detects bursts, flags blinks, groups similar photos, and highlights top picks.
Everything runs 100% locally. GPU is auto-detected and optional — Facet adapts to your hardware from CPU-only to 24 GB VRAM.
## Features
### Score
AI models analyze every photo across 9 scoring dimensions: aesthetic quality, composition, face quality, eye sharpness, technical sharpness, color, exposure, subject saliency, and dynamic range. Each photo is automatically categorized (portrait, landscape, macro, street, etc. — 17 categories) and scored with category-specific weights. A **Top Picks** filter surfaces your best photos across the library.
Hover over any photo for a detailed tooltip with the full score breakdown and EXIF data.
### Cull
Dedicated tools to find your keepers fast:
- **Burst detection** — groups rapid-fire shots and auto-selects the best one based on sharpness, quality, and blink detection
- **Similarity groups** — finds visually similar photos across your entire library, regardless of when they were taken
- **Blink detection** — flags closed-eye shots so you can hide or reject them in one click
- **Duplicate detection** — identifies near-identical images via perceptual hashing
### Browse
Multiple ways to explore your library:
- **Gallery modes** — mosaic (justified rows preserving aspect ratios) and grid (uniform cards with metadata overlay)
- **Filters** — date range, content tag, composition pattern, camera, lens, person, quality level, star rating, and custom metric ranges
- **Semantic search** — type a natural-language query like "sunset on the beach" or "child playing in snow" and find matching photos
- **Timeline** — chronological browser with year/month navigation and infinite scroll
- **Map** — browse geotagged photos on an interactive map with marker clustering
- **Capsules** — AI-curated themed slideshows: journeys with place names, golden collection, seasonal palettes, moments with a person, and more
- **Folders** — browse by directory structure with breadcrumb navigation and cover photos
- **Memories** — "On This Day" retrospective showing photos from the same date in previous years
- **Slideshow** — full-screen mode with themed transitions, auto-chaining between capsules, and keyboard controls
### Organize
- **Face recognition** — automatic face detection, grouping into persons, and blink detection. Search, rename, merge, and organize person clusters from the management UI. **Merge suggestions** find similar-looking clusters that may be the same person.
- **Albums** — manual collections with drag-and-drop, or smart albums that auto-populate from saved filter combinations
- **Ratings & favorites** — star ratings (1–5), favorites, and reject flags. Cycle through ratings with a single click.
- **Tags** — AI-generated content tags with configurable vocabulary. Click any tag to filter the gallery.
- **Batch operations** — multi-select with Shift+click and Ctrl+click. Set ratings, toggle favorites, mark rejects, or add to albums in bulk.
### Understand
- **Statistics** — interactive dashboards: equipment usage, category breakdown, shooting timeline, and custom metric correlations
- **AI critique** — detailed score breakdown showing each metric's contribution. VLM-powered natural-language assessment available with 16+ GB VRAM.
- **Weight tuning** — per-category weight editor with live score preview. A/B photo comparison learns from your choices and suggests optimized weights.
- **Snapshots** — save, restore, and compare weight configurations
- **AI captions** — natural-language photo descriptions, editable and translatable to 5 languages
### Share
- **Album sharing** — generate shareable links for any album, no login required for recipients. Revoke access at any time.
- **Photo download** — download individual photos or selections from the gallery
- **Export** — export all scores to CSV or JSON for external analysis
### More
- **Dark & light mode** with 10 accent color themes, respects system preference
- **Responsive** — adapts from mobile to desktop
- **5 languages** — English, French, German, Spanish, Italian
- **Multi-user** — per-user directories, ratings, and role-based access for family NAS setups
- **Plugins & webhooks** — extend Facet with custom actions on scoring events
- **Scan from web UI** — trigger photo scanning directly from the browser (superadmin role)
## Quick Start
### Docker (recommended)
```bash
docker compose up
# Open http://localhost:5000
```
GPU acceleration requires the [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html). Mount your photos directory in `docker-compose.yml`.
### Manual Install
```bash
git clone https://github.com/ncoevoet/facet.git && cd facet
bash install.sh # auto-detects GPU, creates venv, installs everything
python facet.py /photos # score photos
python viewer.py # start web viewer → http://localhost:5000
```
The install script auto-detects your CUDA version, installs the right PyTorch variant, builds the Angular frontend, and verifies all imports. Options: `--cpu` (force CPU), `--cuda 12.8` (override CUDA version), `--skip-client` (skip frontend build).
Step-by-step manual install
```bash
# 1. Install exiftool (optional but recommended)
# Ubuntu/Debian: sudo apt install libimage-exiftool-perl
# macOS: brew install exiftool
# 2. Create virtual environment
python -m venv venv && source venv/bin/activate
# 3. Install PyTorch with CUDA (pick your version at https://pytorch.org/get-started/locally)
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu128
# 4. Install Python dependencies (all at once — see Troubleshooting if you hit conflicts)
pip install -r requirements.txt
# 5. Install ONNX Runtime for face detection (choose ONE)
pip install onnxruntime-gpu>=1.17.0 # GPU (CUDA 12.x)
# pip install onnxruntime>=1.15.0 # CPU fallback
# 6. Build Angular frontend
cd client && npm ci && npx ng build && cd ..
# 7. Score photos and start viewer
python facet.py /path/to/photos
python viewer.py
```
Run `python facet.py --doctor` to diagnose GPU issues. See [Installation](docs/INSTALLATION.md) for VRAM profiles, VLM tagging packages (16gb/24gb), optional dependencies, and [dependency troubleshooting](docs/INSTALLATION.md#troubleshooting-dependency-conflicts).
## Documentation
| Document | Description |
|----------|-------------|
| [Installation](docs/INSTALLATION.md) | Requirements, GPU setup, VRAM profiles, dependencies |
| [Commands](docs/COMMANDS.md) | All CLI commands reference |
| [Configuration](docs/CONFIGURATION.md) | Full `scoring_config.json` reference |
| [Scoring](docs/SCORING.md) | Categories, weights, tuning guide |
| [Face Recognition](docs/FACE_RECOGNITION.md) | Face workflow, clustering, person management |
| [Viewer](docs/VIEWER.md) | Web gallery features and usage |
| [Deployment](docs/DEPLOYMENT.md) | Production deployment (Synology NAS, Linux, Docker) |
| [Contributing](CONTRIBUTING.md) | Development setup, architecture, code style |
## License
[MIT](LICENSE)