From 239d9d15b8d65e43f1c05e690a18064585b9c964 Mon Sep 17 00:00:00 2001 From: sudolulo Date: Wed, 10 Jun 2026 15:53:39 -0400 Subject: [PATCH] Update README.md --- README.md | 107 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 100 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index f73d861..53be1aa 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,8 @@ # if-curator-headless -fork of [if-curator](https://github.com/ds-sebastian/if_curator) with automatic Frigate face training upload and Docker support. +Headless fork of [if-curator](https://github.com/ds-sebastian/if_curator) with automatic Frigate face training upload and Docker support. + +> *A specialized tool to extract **high-quality, diverse** training images from your Immich library for Frigate's Face Recognition (ArcFace) and Object/State Classification models.* ## What This Adds @@ -8,11 +10,77 @@ fork of [if-curator](https://github.com/ds-sebastian/if_curator) with automatic - **Auto-discover people** — processes all named people from Immich automatically instead of picking one at a time - **Frigate upload** — sends curated face crops directly to Frigate's face training API after processing - **People filtering** — skip specific people, whitelist only certain people, or set a minimum photo count -- **Docker** — Dockerfile and compose config with NVIDIA GPU support, ready for TrueNAS +- **Docker** — pre-built image with NVIDIA GPU support, ready for TrueNAS -All of if-curator's original functionality (smart diversity, quality filtering, face alignment, blur rejection, etc.) is unchanged. +All of if-curator's original functionality is unchanged. -## New Environment Variables +--- + +## Why This Tool? + +> **"Diversity matters far more than volume."** — *Frigate Developer Tips* + +Training AI models on "bulk" data is often harmful. If you feed the model 50 images from the same 10-second video clip, it learns to recognize the *lighting and background*, not the actual *face* or *object*. + +`if-curator` solves this using **AI-powered diversity selection** and **quality filtering**: + +| Mode | Embedding Model | Algorithm | +| :--- | :--- | :--- | +| **👤 Face** | InsightFace (ArcFace) | K-Medoids Clustering + FPS + Hard Example Weighting | +| **🐶 Object** | SigLIP (Vision Transformer) | K-Medoids Clustering + FPS | + +--- + +## Features + +### Smart Selection +- **Auto Diversity [Recommended]**: Clusters images by visual similarity, selects representatives from each cluster, then fills with maximally-diverse picks until redundancy starts (capped at 80) +- **Standard (30 images)**: Balanced set using Smart Diversity +- **Broad (100 images)**: Extensive set using Smart Diversity +- **Custom Count**: You choose the limit + +### Quality Filtering +Bad training data hurts ArcFace models. Images are automatically rejected if they are: +- **Blurry** — Laplacian variance below threshold +- **Grayscale / IR** — ArcFace is trained on color images only +- **Over/Underexposed** — Washed-out or too dark to use +- **Low confidence** — Partial or occluded face detections +- **Too small** — Faces under 100px (configurable) lack features + +### Face Recognition Prep +- Uses InsightFace embeddings on **face crops** (not full images — avoids wrong-face in group photos) +- **Hard example prioritization** — unusual angles, sunglasses, and low-confidence detections are biased for selection +- **Face alignment** via InsightFace landmarks (standard 112×112 ArcFace input) +- Downloads **full-resolution** originals for final crops (falls back to JPEG preview for HEIC/RAW) + +### Object/State Classification Prep +- Uses **SigLIP** embeddings for semantic diversity +- **YOLOv9c** to detect and crop specific objects (dogs, cars, etc.) +- Captures variation in poses, lighting, and backgrounds + +> **Note:** Frigate does not support uploading custom images for object classification training via the UI or API. Object mode crops are saved to disk for manual YOLO model training. + +### Performance +- Concurrent thumbnail downloads (8 parallel workers) +- Batch-capable SigLIP embeddings for GPU efficiency +- Optional disk-based embedding cache for faster re-runs +- Multi-person batch mode + +--- + +## Requirements + +- **NVIDIA GPU** (recommended) — auto-detects CUDA for faster embedding computation. CPU mode is available via `FORCE_CPU=true` but significantly slower. +- **Python 3.12+** +- **[uv](https://astral.sh/uv/)** +- **Immich Server** (v1.106+) +- **Frigate** (v0.16+, for face recognition API — optional) + +--- + +## Environment Variables + +### New in This Fork | Variable | Default | What it does | | :--- | :--- | :--- | @@ -25,9 +93,34 @@ All of if-curator's original functionality (smart diversity, quality filtering, | `MIN_FACE_COUNT` | `3` | Minimum photos required to process a person | | `OBJECT_CLASS` | `dog` | Object type (only for object mode) | -All original if-curator variables (`IMMICH_URL`, `API_KEY`, `FORCE_CPU`, etc.) still work. +### Original if-curator Variables + +| Variable | Default | Description | +| :--- | :--- | :--- | +| `IMMICH_URL` | *(prompted)* | Full URL to Immich (e.g. `http://192.168.1.10:2283`) | +| `API_KEY` | *(prompted)* | Your Immich API Key | +| `FORCE_CPU` | `false` | Disable GPU acceleration | +| `MIN_FACE_WIDTH` | `100` | Minimum face crop size (pixels) | +| `BLUR_THRESHOLD` | `100.0` | Laplacian variance threshold for blur detection | +| `MIN_CONFIDENCE` | `0.7` | Minimum Immich detection confidence | +| `MAX_AUTO_IMAGES` | `80` | Safety cap for auto-diversity mode | +| `FACE_MARGIN` | `0.15` | Crop margin around face (fraction) | +| `USE_FULL_RESOLUTION` | `true` | Download originals for final crops | +| `ENABLE_FACE_ALIGNMENT` | `true` | Align faces to ArcFace 112×112 format | +| `ENABLE_CACHE` | `false` | Cache embeddings to disk for faster re-runs | +| `CACHE_DIR` | `.if_cache` | Directory for embedding cache | + +--- ## Docker -ghcr.io/sudolulo/if-curator-headless:latest - +See [sudolulo/if-curator-headless](https://github.com/sudolulo/if-curator-docker) for the Dockerfile, compose config, and setup instructions. + +--- + +## Local Install + +```bash +git clone https://github.com/sudolulo/if_curator_headless.git +cd if_curator_headless +uv sync