Improve Face Clustering Accuracy & Enable Automatic Clustering on Folder Add

backend/app/config/settings.py

@@ -23,3 +23,6 @@
 DATABASE_PATH = "app/database/PictoPy.db"
 THUMBNAIL_IMAGES_PATH = "./images/thumbnails"
 IMAGES_PATH = "./images"
+
+# Face Alignment (improves accuracy for angled/profile faces)
+FACE_ALIGNMENT_ENABLED = True  # Set to True to enable face alignment preprocessing

backend/app/models/FaceDetector.py

@@ -44,11 +44,10 @@ def detect_faces(self, image_id: str, image_path: str, forSearch: bool = False):
                 bboxes.append(bbox)
                 confidences.append(float(score))
 
-                padding = 20
-                face_img = img[
-                    max(0, y1 - padding) : min(img.shape[0], y2 + padding),
-                    max(0, x1 - padding) : min(img.shape[1], x2 + padding),
-                ]
+                # Use face alignment utility for better pose handling
+                from app.utils.face_alignment import align_face_simple
+
+                face_img = align_face_simple(img, bbox, padding=20)
                 processed_face = FaceNet_util_preprocess_image(face_img)
                 processed_faces.append(processed_face)
 

backend/app/routes/folders.py

@@ -69,6 +69,8 @@ def post_folder_add_sequence(folder_path: str, folder_id: int):
         logger.info(f"Add folder: {folder_data}")
         # Process images in all folders
         image_util_process_folder_images(folder_data)
+        image_util_process_untagged_images()
+        cluster_util_face_clusters_sync(force_full_reclustering=True)  # Force full reclustering for new photos
 
         # Restart sync microservice watcher after processing images
         API_util_restart_sync_microservice_watcher()
@@ -117,7 +119,7 @@ def post_sync_folder_sequence(
         # Process images in all folders
         image_util_process_folder_images(folder_data)
         image_util_process_untagged_images()
-        cluster_util_face_clusters_sync()
+        cluster_util_face_clusters_sync(force_full_reclustering=True)  # Force full reclustering for synced photos
 
         # Restart sync microservice watcher after processing images
         API_util_restart_sync_microservice_watcher()
@@ -184,7 +186,7 @@ def add_folder(request: AddFolderRequest, app_state=Depends(get_state)):
         root_folder_id, folder_map = folder_util_add_folder_tree(
             root_path=request.folder_path,
             parent_folder_id=parent_folder_id,
-            AI_Tagging=False,
+            AI_Tagging=True,  # Enable AI tagging by default for automatic face detection
             taggingCompleted=request.taggingCompleted,
         )
 

backend/app/utils/face_alignment.py

@@ -0,0 +1,149 @@
+"""
+Face alignment utilities for improving face recognition accuracy.
+
+This module provides face alignment preprocessing to handle tilted, angled,
+and profile faces. It uses simple geometric transformation based on eye positions.
+"""
+
+import cv2
+import numpy as np
+from typing import Optional, Tuple, Dict
+from app.config.settings import FACE_ALIGNMENT_ENABLED
+from app.logging.setup_logging import get_logger
+
+logger = get_logger(__name__)
+
+
+def estimate_eye_positions(face_image: np.ndarray) -> Optional[Tuple[Tuple[int, int], Tuple[int, int]]]:
+    """
+    Estimate eye positions using simple heuristics for face crops.
+
+    For a cropped face image, eyes are typically:
+    - Horizontally: At 1/4 and 3/4 of width
+    - Vertically: At 1/3 of height from top
+
+    Args:
+        face_image: Cropped face image
+
+    Returns:
+        Tuple of (left_eye, right_eye) coordinates, or None if estimation fails
+    """
+    h, w = face_image.shape[:2]
+
+    # Heuristic eye positions (works reasonably well for frontal faces)
+    left_eye = (int(w * 0.35), int(h * 0.35))
+    right_eye = (int(w * 0.65), int(h * 0.35))
+
+    return (left_eye, right_eye)
+
+
+def align_face_simple(
+    image: np.ndarray,
+    bbox: Dict[str, int],
+    padding: int = 20
+) -> np.ndarray:
+    """
+    Extract and align face using simple geometric heuristics.
+
+    This is a lightweight alignment approach that:
+    1. Crops the face with padding
+    2. Estimates eye positions using heuristics
+    3. Rotates face to align eyes horizontally
+    4. Returns aligned face crop
+
+    Args:
+        image: Full source image
+        bbox: Bounding box dict with keys: x, y, width, height
+        padding: Padding around face in pixels
+
+    Returns:
+        Aligned face crop as numpy array
+    """
+    if not FACE_ALIGNMENT_ENABLED:
+        # Fallback to simple crop when alignment disabled
+        return simple_face_crop(image, bbox, padding)
+
+    try:
+        # Extract face region with padding
+        x, y, w, h = bbox['x'], bbox['y'], bbox['width'], bbox['height']
+        img_h, img_w = image.shape[:2]
+
+        # Calculate crop bounds with padding
+        x1 = max(0, x - padding)
+        y1 = max(0, y - padding)
+        x2 = min(img_w, x + w + padding)
+        y2 = min(img_h, y + h + padding)
+
+        # Crop face region
+        face_crop = image[y1:y2, x1:x2]
+
+        if face_crop.size == 0:
+            logger.warning("Empty face crop, returning original")
+            return simple_face_crop(image, bbox, padding)
+
+        # Estimate eye positions  
+        eyes = estimate_eye_positions(face_crop)
+        if eyes is None:
+            return face_crop
+
+        left_eye, right_eye = eyes
+
+        # Calculate rotation angle to align eyes horizontally
+        dx = right_eye[0] - left_eye[0]
+        dy = right_eye[1] - left_eye[1]
+        angle = np.degrees(np.arctan2(dy, dx))
+
+        # Only apply rotation if angle is significant (> 3 degrees)
+        if abs(angle) < 3:
+            return face_crop
+
+        # Calculate center point for rotation (between eyes)
+        center_x = (left_eye[0] + right_eye[0]) // 2
+        center_y = (left_eye[1] + right_eye[1]) // 2
+        center = (center_x, center_y)
+
+        # Create rotation matrix
+        M = cv2.getRotationMatrix2D(center, angle, scale=1.0)
+
+        # Apply rotation
+        rotated = cv2.warpAffine(
+            face_crop,
+            M,
+            (face_crop.shape[1], face_crop.shape[0]),
+            flags=cv2.INTER_LINEAR,
+            borderMode=cv2.BORDER_REPLICATE
+        )
+
+        logger.debug(f"Aligned face with rotation angle: {angle:.2f} degrees")
+        return rotated
+
+    except Exception as e:
+        logger.warning(f"Face alignment failed: {e}, using simple crop")
+        return simple_face_crop(image, bbox, padding)
+
+
+def simple_face_crop(
+    image: np.ndarray,
+    bbox: Dict[str, int],
+    padding: int = 20
+) -> np.ndarray:
+    """
+    Simple face crop without alignment (fallback method).
+
+    Args:
+        image: Full source image
+        bbox: Bounding box dict with keys: x, y, width, height
+        padding: Padding around face in pixels
+
+    Returns:
+        Face crop as numpy array
+    """
+    x, y, w, h = bbox['x'], bbox['y'], bbox['width'], bbox['height']
+    img_h, img_w = image.shape[:2]
+
+    x1 = max(0, x - padding)
+    y1 = max(0, y - padding)
+    x2 = min(img_w, x + w + padding)
+    y2 = min(img_h, y + h + padding)
+
+    return image[y1:y2, x1:x2]

backend/app/utils/face_clusters.py

@@ -186,19 +186,19 @@ def _validate_embedding(embedding: NDArray, min_norm: float = 1e-6) -> bool:
 
 
 def cluster_util_cluster_all_face_embeddings(
-    eps: float = 0.75,
+    eps: float = 0.5,
     min_samples: int = 2,
-    similarity_threshold: float = 0.85,
+    similarity_threshold: float = 0.65,
     merge_threshold: float = None,
 ) -> List[ClusterResult]:
     """
     Cluster face embeddings using DBSCAN with similarity validation.
 
     Args:
-        eps: DBSCAN epsilon parameter for maximum distance between samples (default: 0.75)
+        eps: DBSCAN epsilon parameter for maximum distance between samples (default: 0.5)
         min_samples: DBSCAN minimum samples parameter for core points (default: 2)
-        similarity_threshold: Minimum similarity to consider same person (default: 0.85, range: 0.75-0.90)
-        merge_threshold: Similarity threshold for post-clustering merge (default: None, uses similarity_threshold)
+        similarity_threshold: Minimum similarity to consider same person (default: 0.65, range: 0.60-0.85)
+        merge_threshold: Similarity threshold for post-clustering merge (default: None, uses 0.60)
 
     Returns:
         List of ClusterResult objects containing face_id, embedding, cluster_uuid, and cluster_name
@@ -306,8 +306,8 @@ def cluster_util_cluster_all_face_embeddings(
             results.append(result)
 
     # Post-clustering merge: merge similar clusters based on representative faces
-    # Use similarity_threshold if merge_threshold not explicitly provided
-    effective_merge_threshold = merge_threshold if merge_threshold is not None else 0.7
+    # Use lower threshold if merge_threshold not explicitly provided to combine similar clusters
+    effective_merge_threshold = merge_threshold if merge_threshold is not None else 0.60
     results = _merge_similar_clusters(
         results, merge_threshold=effective_merge_threshold
     )
@@ -316,7 +316,7 @@ def cluster_util_cluster_all_face_embeddings(
 
 
 def cluster_util_assign_cluster_to_faces_without_clusterId(
-    similarity_threshold: float = 0.8,
+    similarity_threshold: float = 0.65,
 ) -> List[Dict]:
     """
     Assign cluster IDs to faces that don't have clusters using nearest mean method with similarity threshold.
@@ -331,7 +331,7 @@ def cluster_util_assign_cluster_to_faces_without_clusterId(
     Args:
         similarity_threshold:
             Minimum cosine similarity required for assignment (0.0 to 1.0)
-            Higher values = more strict assignment. Default: 0.7
+            Higher values = more strict assignment. Default: 0.65
 
     Returns:
         List of face-cluster mappings ready for batch update