Faces: Improve "photoprism faces audit --fix" command

Signed-off-by: Michael Mayer <[email protected]>

Author: lastzero

internal/ai/face/README.md

@@ -1,6 +1,6 @@
 ## Face Detection and Embedding Guidelines
 
-**Last Updated:** October 2, 2025
+**Last Updated:** October 5, 2025
 
 ### Overview
 
@@ -44,7 +44,7 @@ All embeddings, regardless of origin, are normalized to unit length (‖x‖₂
 - `NewEmbedding` normalizes the raw float32 inference output.
 - `EmbeddingsMidpoint` normalizes each contributor, averages component-wise, and renormalizes the centroid.
 - `UnmarshalEmbedding` and `UnmarshalEmbeddings` normalize data when loading from persisted JSON.
-- Static datasets (`KidsEmbeddings`, `IgnoredEmbeddings`) and random generators now normalize their entries after perturbation.
+- Static datasets (children/background samples) and random generators now normalize their entries after perturbation.
 - `photoprism faces audit --fix` re-normalizes persisted embeddings, rekeys face IDs, and re-links markers (ID + `FaceDist`) so historical data adopts the canonical unit-length vectors.
 - `Faces.Match` pre-filters matchable clusters, keeps an in-memory veto list for freshly cleared markers, and caches embeddings to avoid redundant distance checks; `BenchmarkSelectBestFace` (1024 faces) now reports a bucket size of ~16 candidates out of 1024 (≈98 % fewer distance evaluations) at ≈0.55 ms/op with zero allocations.
 - Face clusters update their sample statistics (`Samples`, `SampleRadius`) from the latest matches via `Face.UpdateMatchStats`, avoiding stale radii during optimize loops.
@@ -75,13 +75,11 @@ This guarantees that Euclidean distance comparisons are equivalent to cosine com
 
 ### Configuration Summary
 
-| Setting             | Default                      | Description                                                                     |
-|---------------------|------------------------------|---------------------------------------------------------------------------------|
-| `FACE_ANGLE`        | `-0.3,0,0.3`                 | Detection angles (radians) swept by Pigo.                                       |
-| `FACE_SCORE`        | `9.0` (with dynamic offsets) | Base quality threshold before scale adjustments.                                |
-| `FACE_OVERLAP`      | `42`                         | Maximum allowed IoU when deduplicating markers.                                 |
-| `FACE_KIDS_DIST`    | `0.695`                      | Distance cutoff for kids-face detection (still interpreted in Euclidean space). |
-| `FACE_IGNORED_DIST` | `0.86`                       | Distance cutoff for ignoring generic embeddings.                                |
+| Setting                | Default                      | Description                                                                          |
+|------------------------|------------------------------|--------------------------------------------------------------------------------------|
+| `FACE_ANGLE`           | `-0.3,0,0.3`                 | Detection angles (radians) swept by Pigo.                                            |
+| `FACE_SCORE`           | `9.0` (with dynamic offsets) | Base quality threshold before scale adjustments.                                     |
+| `FACE_OVERLAP`         | `42`                         | Maximum allowed IoU when deduplicating markers.                                      |
 
 ### Benchmark Reference
 

internal/ai/face/background.go

@@ -28,7 +28,7 @@ func TestClustersContains(t *testing.T) {
 		assert.False(t, clusters.Contains(embedding))
 	})
 
-	t.Run("DisabledClusterIgnored", func(t *testing.T) {
+	t.Run("DisabledClusterBackground", func(t *testing.T) {
 		clusters := Clusters{
 			{Radius: 1, Embedding: Embedding{0, 0}, Disabled: true},
 		}

internal/ai/face/background_test.go

@@ -13,10 +13,10 @@ var (
 
 func init() {
 	// Disable ignore/skip for background and children if legacy env variables are set.
-	if os.Getenv("PHOTOPRISM_FACE_KIDS_DIST") != "" {
+	if os.Getenv("PHOTOPRISM_FACE_CHILDREN_DIST") != "" || os.Getenv("PHOTOPRISM_FACE_KIDS_DIST") != "" {
 		SkipChildren = false
 	}
-	if os.Getenv("PHOTOPRISM_FACE_IGNORED_DIST") != "" {
+	if os.Getenv("PHOTOPRISM_FACE_BACKGROUND_DIST") != "" || os.Getenv("PHOTOPRISM_FACE_IGNORED_DIST") != "" {
 		IgnoreBackground = false
 	}
 }

internal/ai/face/clusters_test.go

@@ -28,12 +28,12 @@ func NewEmbedding(inference []float32) Embedding {
 	return result
 }
 
-// Kind returns the type of face e.g. regular, kids, or ignored.
+// Kind returns the type of face e.g. regular, children, or background.
 func (m Embedding) Kind() Kind {
 	if m.IsChild() {
-		return KidsFace
+		return ChildrenFace
 	} else if m.IsBackground() {
-		return IgnoredFace
+		return BackgroundFace
 	}
 
 	return RegularFace

internal/ai/face/config.go

@@ -8,8 +8,8 @@ type Kind int
 
 const (
 	RegularFace Kind = iota + 1
-	KidsFace
-	IgnoredFace
+	ChildrenFace
+	BackgroundFace
 	AmbiguousFace
 )
 
@@ -35,10 +35,10 @@ func RandomEmbeddings(n int, k Kind) (result Embeddings) {
 		switch k {
 		case RegularFace:
 			result[i] = RandomEmbedding()
-		case KidsFace:
-			result[i] = RandomKidsEmbedding()
-		case IgnoredFace:
-			result[i] = RandomIgnoredEmbedding()
+		case ChildrenFace:
+			result[i] = RandomChildrenEmbedding()
+		case BackgroundFace:
+			result[i] = RandomBackgroundEmbedding()
 		}
 
 	}
@@ -67,8 +67,8 @@ func RandomEmbedding() (result Embedding) {
 	return result
 }
 
-// RandomKidsEmbedding returns a random kids embedding for testing.
-func RandomKidsEmbedding() (result Embedding) {
+// RandomChildrenEmbedding returns a random children embedding for testing.
+func RandomChildrenEmbedding() (result Embedding) {
 	result = make(Embedding, 512)
 
 	if len(Children) == 0 {
@@ -88,13 +88,17 @@ func RandomKidsEmbedding() (result Embedding) {
 	return result
 }
 
-// RandomIgnoredEmbedding returns a random ignored embedding for testing.
-func RandomIgnoredEmbedding() (result Embedding) {
+// RandomBackgroundEmbedding returns a random background embedding for testing.
+func RandomBackgroundEmbedding() (result Embedding) {
 	result = make(Embedding, 512)
 
+	if len(Background) == 0 {
+		return result
+	}
+
 	d := 0.1 / 512.0
-	n := 1 + rand.IntN(len(TestEmbeddings)-1)
-	e := TestEmbeddings[n]
+	n := rand.IntN(len(Background))
+	e := Background[n].Embedding
 
 	for i := range result {
 		result[i] = RandomFloat64(e[i], d)

internal/ai/face/embedding.go

@@ -23,15 +23,15 @@ func TestRandomEmbeddings(t *testing.T) {
 			assert.False(t, e[i].IsBackground())
 		}
 	})
-	t.Run("Kids", func(t *testing.T) {
-		e := RandomEmbeddings(2, KidsFace)
+	t.Run("Children", func(t *testing.T) {
+		e := RandomEmbeddings(2, ChildrenFace)
 		for i := range e {
 			assert.False(t, e[i].IsBackground())
 			assert.True(t, e[i].IsChild())
 		}
 	})
-	t.Run("Ignored", func(t *testing.T) {
-		e := RandomEmbeddings(2, IgnoredFace)
+	t.Run("Background", func(t *testing.T) {
+		e := RandomEmbeddings(2, BackgroundFace)
 		for i := range e {
 			assert.True(t, e[i].IsBackground())
 			assert.False(t, e[i].IsChild())