{"id":46830827,"url":"https://github.com/ncoevoet/facet","last_synced_at":"2026-04-01T17:40:35.180Z","repository":{"id":338831181,"uuid":"1159371371","full_name":"ncoevoet/facet","owner":"ncoevoet","description":"Local AI photo scoring, culling, and gallery — score, organise, and explore your library with face recognition and semantic search. No cloud, no subscriptions.","archived":false,"fork":false,"pushed_at":"2026-03-26T12:05:51.000Z","size":26483,"stargazers_count":72,"open_issues_count":0,"forks_count":6,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-03-26T19:48:23.734Z","etag":null,"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"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ncoevoet.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-16T16:44:55.000Z","updated_at":"2026-03-26T12:05:58.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ncoevoet/facet","commit_stats":null,"previous_names":["ncoevoet/facet"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/ncoevoet/facet","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ncoevoet%2Ffacet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ncoevoet%2Ffacet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ncoevoet%2Ffacet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ncoevoet%2Ffacet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ncoevoet","download_url":"https://codeload.github.com/ncoevoet/facet/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ncoevoet%2Ffacet/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31290539,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["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"],"created_at":"2026-03-10T10:00:16.651Z","updated_at":"2026-04-01T17:40:35.155Z","avatar_url":"https://github.com/ncoevoet.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Facet\n\n**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.\n\n![Python](https://img.shields.io/badge/python-3.10+-blue)\n![Angular](https://img.shields.io/badge/Angular-20-dd0031)\n![FastAPI](https://img.shields.io/badge/FastAPI-0.115+-009688)\n![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux%20%7C%20Docker-lightgrey)\n![License](https://img.shields.io/badge/license-MIT-green)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshots/hero-mosaic.jpg\" alt=\"Facet — Top Picks mosaic gallery\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n## How It Works\n\n1. **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).\n2. **Browse** — Open the web gallery to explore your library with filters, search, and multiple view modes.\n3. **Cull** — Find your best shots instantly. Facet auto-detects bursts, flags blinks, groups similar photos, and highlights top picks.\n\nEverything runs 100% locally. GPU is auto-detected and optional — Facet adapts to your hardware from CPU-only to 24 GB VRAM.\n\n## Features\n\n### Score\n\nAI 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.\n\nHover over any photo for a detailed tooltip with the full score breakdown and EXIF data.\n\n\u003cimg src=\"docs/screenshots/hover-tooltip.jpg\" alt=\"Hover tooltip with score breakdown\" width=\"100%\"\u003e\n\n### Cull\n\nDedicated tools to find your keepers fast:\n\n- **Burst detection** — groups rapid-fire shots and auto-selects the best one based on sharpness, quality, and blink detection\n- **Similarity groups** — finds visually similar photos across your entire library, regardless of when they were taken\n- **Blink detection** — flags closed-eye shots so you can hide or reject them in one click\n- **Duplicate detection** — identifies near-identical images via perceptual hashing\n\n\u003cimg src=\"docs/screenshots/burst-culling.jpg\" alt=\"Burst culling\" width=\"100%\"\u003e\n\n### Browse\n\nMultiple ways to explore your library:\n\n- **Gallery modes** — mosaic (justified rows preserving aspect ratios) and grid (uniform cards with metadata overlay)\n- **Filters** — date range, content tag, composition pattern, camera, lens, person, quality level, star rating, and custom metric ranges\n- **Semantic search** — type a natural-language query like \"sunset on the beach\" or \"child playing in snow\" and find matching photos\n- **Timeline** — chronological browser with year/month navigation and infinite scroll\n- **Map** — browse geotagged photos on an interactive map with marker clustering\n- **Capsules** — AI-curated themed slideshows: journeys with place names, golden collection, seasonal palettes, moments with a person, and more\n- **Folders** — browse by directory structure with breadcrumb navigation and cover photos\n- **Memories** — \"On This Day\" retrospective showing photos from the same date in previous years\n- **Slideshow** — full-screen mode with themed transitions, auto-chaining between capsules, and keyboard controls\n\n\u003ctable\u003e\u003ctr\u003e\n\u003ctd\u003e\u003cimg src=\"docs/screenshots/filter-panel.jpg\" alt=\"Filter sidebar\" width=\"100%\"\u003e\u003c/td\u003e\n\u003ctd\u003e\u003cimg src=\"docs/screenshots/semantic-search.jpg\" alt=\"Semantic search results\" width=\"100%\"\u003e\u003c/td\u003e\n\u003c/tr\u003e\u003c/table\u003e\n\n### Organize\n\n- **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.\n- **Albums** — manual collections with drag-and-drop, or smart albums that auto-populate from saved filter combinations\n- **Ratings \u0026 favorites** — star ratings (1–5), favorites, and reject flags. Cycle through ratings with a single click.\n- **Tags** — AI-generated content tags with configurable vocabulary. Click any tag to filter the gallery.\n- **Batch operations** — multi-select with Shift+click and Ctrl+click. Set ratings, toggle favorites, mark rejects, or add to albums in bulk.\n\n\u003ctable\u003e\u003ctr\u003e\n\u003ctd\u003e\u003cimg src=\"docs/screenshots/persons-manage.jpg\" alt=\"Manage Persons page\" width=\"100%\"\u003e\u003c/td\u003e\n\u003ctd\u003e\u003cimg src=\"docs/screenshots/person-gallery.jpg\" alt=\"Person gallery\" width=\"100%\"\u003e\u003c/td\u003e\n\u003c/tr\u003e\u003c/table\u003e\n\n### Understand\n\n- **Statistics** — interactive dashboards: equipment usage, category breakdown, shooting timeline, and custom metric correlations\n- **AI critique** — detailed score breakdown showing each metric's contribution. VLM-powered natural-language assessment available with 16+ GB VRAM.\n- **Weight tuning** — per-category weight editor with live score preview. A/B photo comparison learns from your choices and suggests optimized weights.\n- **Snapshots** — save, restore, and compare weight configurations\n- **AI captions** — natural-language photo descriptions, editable and translatable to 5 languages\n\n\u003ctable\u003e\u003ctr\u003e\n\u003ctd\u003e\u003cimg src=\"docs/screenshots/stats-gear.jpg\" alt=\"Equipment statistics\" width=\"100%\"\u003e\u003c/td\u003e\n\u003ctd\u003e\u003cimg src=\"docs/screenshots/stats-categories.jpg\" alt=\"Category analytics\" width=\"100%\"\u003e\u003c/td\u003e\n\u003c/tr\u003e\u003c/table\u003e\n\n\u003ctable\u003e\u003ctr\u003e\n\u003ctd\u003e\u003cimg src=\"docs/screenshots/critique.jpg\" alt=\"AI Critique dialog\" width=\"100%\"\u003e\u003c/td\u003e\n\u003ctd\u003e\u003cimg src=\"docs/screenshots/snapshots.jpg\" alt=\"Snapshots\" width=\"100%\"\u003e\u003c/td\u003e\n\u003c/tr\u003e\u003c/table\u003e\n\n\u003ctable\u003e\u003ctr\u003e\n\u003ctd\u003e\u003cimg src=\"docs/screenshots/weights-sliders.jpg\" alt=\"Category weight sliders\" width=\"100%\"\u003e\u003c/td\u003e\n\u003ctd\u003e\u003cimg src=\"docs/screenshots/weights-compare.jpg\" alt=\"A/B photo comparison\" width=\"100%\"\u003e\u003c/td\u003e\n\u003c/tr\u003e\u003c/table\u003e\n\n### Share\n\n- **Album sharing** — generate shareable links for any album, no login required for recipients. Revoke access at any time.\n- **Photo download** — download individual photos or selections from the gallery\n- **Export** — export all scores to CSV or JSON for external analysis\n\n### More\n\n- **Dark \u0026 light mode** with 10 accent color themes, respects system preference\n- **Responsive** — adapts from mobile to desktop\n- **5 languages** — English, French, German, Spanish, Italian\n- **Multi-user** — per-user directories, ratings, and role-based access for family NAS setups\n- **Plugins \u0026 webhooks** — extend Facet with custom actions on scoring events\n- **Scan from web UI** — trigger photo scanning directly from the browser (superadmin role)\n\n\u003ctable\u003e\u003ctr\u003e\n\u003ctd width=\"33%\"\u003e\u003cimg src=\"docs/screenshots/mobile-gallery.jpg\" alt=\"Mobile gallery\" width=\"100%\"\u003e\u003c/td\u003e\n\u003ctd width=\"33%\"\u003e\u003cimg src=\"docs/screenshots/tablet-gallery.jpg\" alt=\"Tablet gallery\" width=\"100%\"\u003e\u003c/td\u003e\n\u003ctd width=\"33%\"\u003e\u003cimg src=\"docs/screenshots/gallery-mosaic.jpg\" alt=\"Desktop mosaic\" width=\"100%\"\u003e\u003c/td\u003e\n\u003c/tr\u003e\u003c/table\u003e\n\n## Quick Start\n\n### Docker (recommended)\n\n```bash\ndocker compose up\n# Open http://localhost:5000\n```\n\nGPU 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`.\n\n### Manual Install\n\n```bash\ngit clone https://github.com/ncoevoet/facet.git \u0026\u0026 cd facet\nbash install.sh          # auto-detects GPU, creates venv, installs everything\npython facet.py /photos  # score photos\npython viewer.py         # start web viewer → http://localhost:5000\n```\n\nThe 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).\n\n\u003cdetails\u003e\n\u003csummary\u003eStep-by-step manual install\u003c/summary\u003e\n\n```bash\n# 1. Install exiftool (optional but recommended)\n# Ubuntu/Debian: sudo apt install libimage-exiftool-perl\n# macOS:         brew install exiftool\n\n# 2. Create virtual environment\npython -m venv venv \u0026\u0026 source venv/bin/activate\n\n# 3. Install PyTorch with CUDA (pick your version at https://pytorch.org/get-started/locally)\npip install torch torchvision --index-url https://download.pytorch.org/whl/cu128\n\n# 4. Install Python dependencies (all at once — see Troubleshooting if you hit conflicts)\npip install -r requirements.txt\n\n# 5. Install ONNX Runtime for face detection (choose ONE)\npip install onnxruntime-gpu\u003e=1.17.0   # GPU (CUDA 12.x)\n# pip install onnxruntime\u003e=1.15.0     # CPU fallback\n\n# 6. Build Angular frontend\ncd client \u0026\u0026 npm ci \u0026\u0026 npx ng build \u0026\u0026 cd ..\n\n# 7. Score photos and start viewer\npython facet.py /path/to/photos\npython viewer.py\n```\n\u003c/details\u003e\n\nRun `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).\n\n## Documentation\n\n| Document | Description |\n|----------|-------------|\n| [Installation](docs/INSTALLATION.md) | Requirements, GPU setup, VRAM profiles, dependencies |\n| [Commands](docs/COMMANDS.md) | All CLI commands reference |\n| [Configuration](docs/CONFIGURATION.md) | Full `scoring_config.json` reference |\n| [Scoring](docs/SCORING.md) | Categories, weights, tuning guide |\n| [Face Recognition](docs/FACE_RECOGNITION.md) | Face workflow, clustering, person management |\n| [Viewer](docs/VIEWER.md) | Web gallery features and usage |\n| [Deployment](docs/DEPLOYMENT.md) | Production deployment (Synology NAS, Linux, Docker) |\n| [Contributing](CONTRIBUTING.md) | Development setup, architecture, code style |\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fncoevoet%2Ffacet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fncoevoet%2Ffacet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fncoevoet%2Ffacet/lists"}