repository·master·Indexed 41 days ago
https://github.com/ncoevoet/facetA local-first, AI-powered photo analysis engine that uses computer vision and face recognition to score, rank, and cull photo libraries. It analyzes images across 9 dimensions—including aesthetic quality and technical sharpness—and provides a web gallery for browsing, semantic search, and organization. Supports JPEG, HEIF/HEIC, and various RAW formats. Built with Python 3.10+, FastAPI 0.115+, and Angular 21.
Facet is a local photo-analysis and culling engine designed to run entirely on your machine without requiring cloud services, accounts, or API keys. It analyzes images across 9 dimensions (such as aesthetic quality and face sharpness) to provide scoring, browsing, culling, and organization capabilities via a web gallery.
Key Technical Specifications:
Categories are defined in an array within scoring_config.json. Each category determines how photos are evaluated and prioritized.
Each category object contains:
name: A unique identifier for the category.priority: An integer where lower values indicate higher priority (evaluated first).filters: Conditions used to match photos to this category.weights: Scoring metric weights. These must sum to 100.weights block can include five metric keys: symmetry_percent, balance_percent, edge_entropy_percent, fractal_percent, and color_harmony_percent. These are populated by running --recompute-form.modifiers: Behavior adjustments for the category.tags: CLIP vocabulary used for tag-based matching.Important: Because arrays are replaced wholesale, you must copy the entire default categories array from config/scoring_config.default.json if you wish to modify or add a category.
Facet supports three processing modes to balance performance and hardware constraints:
auto: Automatically selects between multi-pass or single-pass based on available VRAM.multi-pass: Designed for limited VRAM. It loads images in RAM chunks (defined by ram_chunk_size), then sequentially loads a model, processes the chunk, and unloads the model. This allows large models (like tagger/composition VLMs) to run on hardware that couldn't hold all models simultaneously.single-pass: Loads all models into VRAM at once. This is the fastest mode but requires high VRAM capacity.Facet is designed to complement existing photo workflows (Lightroom, darktable, digiKam, etc.) rather than replace them. It achieves this through XMP metadata interoperability:
.xmp files (leaving originals intact by default). It can also embed these into JPEG/HEIC/TIFF/PNG/DNG files using the gallery's "Write metadata to file" action or the CLI flags --export-sidecars --embed-originals.--import-sidecars flag.Facet implements several security measures and delivery guarantees for outgoing webhooks:
http and https protocols are allowed. Hostnames resolving to private, loopback, or link-local addresses (including the cloud metadata IP 169.254.169.254) are rejected.Host header to prevent redirection to private addresses.Fine-tune how your photos are evaluated using these advanced features:
[GPU] [16gb/24gb].--sync-label-comparisons--mine-insights[GPU] [16gb/24gb]: Generates editable text descriptions, available in 5 languages.Facet splits its operations into two distinct workloads to optimize hardware usage:
facet.py): Requires high resources (GPU with 6-24GB VRAM or CPU with 8GB+ RAM) to analyze and score photos.viewer.py): A low-resource component that serves the web gallery. This is the only component that must run on your remote server or NAS.Recommended Workflow: Perform scoring on a powerful workstation, then sync the resulting database to your viewer server.
When per_category is enabled in the normalization config, a single --recompute-average run may not converge if your changes also affect photo categories (e.g., reordering priorities or changing scoring contexts).
Why this happens:
compute_percentiles_per_category groups photos by their currently stored photos.category column. If a config change causes photos to move to new categories, the first recompute uses the old category groupings.
Required Workflow:
--recompute-average once.--recompute-average a second time to ensure percentiles are computed against the updated category column.The plugin system allows you to react to scoring events via Python modules, webhooks, or built-in actions. Enable it using the enabled key in the plugins block.
Configuration Keys:
enabled: Master switch (Default: false).high_score_threshold: Minimum aggregate score to trigger on_high_score events (Default: 8.0).webhooks: A list of webhook endpoints to receive JSON POST payloads.actions: A map of named built-in actions triggered by events.Supported Events and Payloads:
on_score_complete: Triggered after each photo is scored. Payload includes path, filename, aggregate, aesthetic, comp_score, category, and tags.on_new_photo: Triggered when a photo enters the database. Uses the same payload as on_score_complete.on_high_score: Triggered when aggregate score $\ge$ high_score_threshold. Uses the same payload as on_score_complete.on_burst_detected: Triggered when a burst group is identified. Payload includes burst_group_id, photo_count, best_path, and paths.{
"plugins": {
"enabled": true,
"high_score_threshold": 8.0,
"webhooks": [
{
"url": "https://example.com/hook",
"events": ["on_score_complete", "on_high_score"],
"min_score": 8.0
}
],
"actions": {
"copy_high_scores": {
"event": "on_high_score",
"action": "copy_to_folder",
"folder": "/path/to/best-photos",
"min_score": 9.0
}
}
}
}Facet classifies photos into categories and then assigns a score based on that category's specific weights. The process follows five steps:
Note: Reordering categories or using scoring contexts only changes the order in which categories are tried; it cannot force a category to match if its filters (like EXIF data or required tags) are not met.
Facet evaluates every photo across 9 dimensions: aesthetic quality, composition, face quality, eye sharpness, technical sharpness, color, exposure, subject recognition, and dynamic range.
Photos are categorized into over 30 content categories (e.g., Portrait, Landscape, Macro, Street) and evaluated using category-specific weights. You can use the Beste Auswahl (Best Selection) filter to sort your library based on a combined score.
To see a detailed breakdown of a photo's score and its EXIF data, hover your mouse over any photo to reveal a tooltip.