Update app.py

app.py

@@ -15,16 +15,15 @@ from collections import Counter
 # Gradio
 import gradio as gr
 
-# YOLO (Ultralytics)
+# PyTorch, YOLO, FaceNet, and deep_sort
 from ultralytics import YOLO
-
-# FaceNet
 from facenet_pytorch import InceptionResnetV1
 from torchvision import transforms
-
-# DeepSORT tracking
 from deep_sort_realtime.deepsort_tracker import DeepSort
 
+# Mediapipe for face mesh, iris detection, blink detection, and hand tracking
+import mediapipe as mp
+
 # --------------------------------------------------------------------
 # LOGGING
 # --------------------------------------------------------------------
@@ -35,8 +34,9 @@ logging.basicConfig(
 )
 logger = logging.getLogger(__name__)
 
-# Mute some debug logs from third-party libraries
+# Mute debug logs from third-party libraries
 logging.getLogger('torch').setLevel(logging.ERROR)
+logging.getLogger('mediapipe').setLevel(logging.ERROR)
 logging.getLogger('deep_sort_realtime').setLevel(logging.ERROR)
 
 # --------------------------------------------------------------------
@@ -47,12 +47,17 @@ DEFAULT_DB_PATH = os.path.expanduser("~/.face_pipeline/known_faces.pkl")
 MODEL_DIR = os.path.expanduser("~/.face_pipeline/models")
 CONFIG_PATH = os.path.expanduser("~/.face_pipeline/config.pkl")
 
-# If you still want blink detection or face mesh references, keep them
+# Landmark indices for blink detection
 LEFT_EYE_IDX = [33, 160, 158, 133, 153, 144]
 RIGHT_EYE_IDX = [263, 387, 385, 362, 380, 373]
 
+# Mediapipe references
+mp_drawing = mp.solutions.drawing_utils
+mp_face_mesh = mp.solutions.face_mesh
+mp_hands = mp.solutions.hands
+
 # --------------------------------------------------------------------
-# PIPELINE CONFIG
+# DATACLASS: PipelineConfig
 # --------------------------------------------------------------------
 @dataclass
 class PipelineConfig:
@@ -65,8 +70,10 @@ class PipelineConfig:
     hand: Dict = field(default_factory=dict)
     eye_color: Dict = field(default_factory=dict)
     enabled_components: Dict = field(default_factory=dict)
+
     detection_conf_thres: float = 0.4
     recognition_conf_thres: float = 0.85
+
     bbox_color: Tuple[int, int, int] = (0, 255, 0)
     spoofed_bbox_color: Tuple[int, int, int] = (0, 0, 255)
     unknown_bbox_color: Tuple[int, int, int] = (0, 0, 255)
@@ -210,19 +217,19 @@ class YOLOFaceDetector:
         self.device = device
         try:
             if not os.path.exists(model_path):
-                logger.info(f"Model file not found at {model_path}. Attempting to download...")
-                response = requests.get(DEFAULT_MODEL_URL)
-                response.raise_for_status()
+                logger.info(f"Model not found at {model_path}. Downloading from GitHub...")
+                resp = requests.get(DEFAULT_MODEL_URL)
+                resp.raise_for_status()
                 os.makedirs(os.path.dirname(model_path), exist_ok=True)
                 with open(model_path, 'wb') as f:
-                    f.write(response.content)
+                    f.write(resp.content)
                 logger.info(f"Downloaded YOLO model to {model_path}")
 
             self.model = YOLO(model_path)
             self.model.to(device)
             logger.info(f"Loaded YOLO model from {model_path}")
         except Exception as e:
-            logger.error(f"YOLO initialization failed: {str(e)}")
+            logger.error(f"YOLO init failed: {str(e)}")
             raise
 
     def detect(self, image: np.ndarray, conf_thres: float) -> List[Tuple[int, int, int, int, float, int]]:
@@ -240,11 +247,11 @@ class YOLOFaceDetector:
             logger.debug(f"Detected {len(detections)} faces.")
             return detections
         except Exception as e:
-            logger.error(f"Detection failed: {str(e)}")
+            logger.error(f"Detection error: {str(e)}")
             return []
 
 # --------------------------------------------------------------------
-# FACE TRACKER
+# FACE TRACKER (DeepSort)
 # --------------------------------------------------------------------
 class FaceTracker:
     def __init__(self, max_age: int = 30):
@@ -260,7 +267,7 @@ class FaceTracker:
             logger.debug(f"Updated tracker with {len(tracks)} tracks.")
             return tracks
         except Exception as e:
-            logger.error(f"Tracking update failed: {str(e)}")
+            logger.error(f"Tracking error: {str(e)}")
             return []
 
 # --------------------------------------------------------------------
@@ -283,12 +290,229 @@ class FaceNetEmbedder:
             tens = self.transform(pil_img).unsqueeze(0).to(self.device)
             with torch.no_grad():
                 embedding = self.model(tens)[0].cpu().numpy()
-            logger.debug(f"Generated embedding: {embedding[:5]}...")
+            logger.debug(f"Generated embedding sample: {embedding[:5]}...")
             return embedding
         except Exception as e:
-            logger.error(f"Embedding generation failed: {str(e)}")
+            logger.error(f"Embedding failed: {str(e)}")
             return None
 
+# --------------------------------------------------------------------
+# BLINK DETECTION
+# --------------------------------------------------------------------
+def detect_blink(face_roi: np.ndarray, threshold: float = 0.25) -> Tuple[bool, float, float, np.ndarray, np.ndarray]:
+    """
+    Returns:
+      (blink_bool, left_ear, right_ear, left_eye_points, right_eye_points).
+    """
+    try:
+        face_mesh_proc = mp_face_mesh.FaceMesh(
+            static_image_mode=True,
+            max_num_faces=1,
+            refine_landmarks=True,
+            min_detection_confidence=0.5
+        )
+        result = face_mesh_proc.process(cv2.cvtColor(face_roi, cv2.COLOR_BGR2RGB))
+        face_mesh_proc.close()
+
+        if not result.multi_face_landmarks:
+            return False, 0.0, 0.0, None, None
+
+        landmarks = result.multi_face_landmarks[0].landmark
+        h, w = face_roi.shape[:2]
+
+        def eye_aspect_ratio(indices):
+            pts = [(landmarks[i].x * w, landmarks[i].y * h) for i in indices]
+            vertical = np.linalg.norm(np.array(pts[1]) - np.array(pts[5])) + \
+                       np.linalg.norm(np.array(pts[2]) - np.array(pts[4]))
+            horizontal = np.linalg.norm(np.array(pts[0]) - np.array(pts[3]))
+            return vertical / (2.0 * horizontal + 1e-6)
+
+        left_ear = eye_aspect_ratio(LEFT_EYE_IDX)
+        right_ear = eye_aspect_ratio(RIGHT_EYE_IDX)
+
+        blink = (left_ear < threshold) and (right_ear < threshold)
+
+        left_eye_pts = np.array([(int(landmarks[i].x * w), int(landmarks[i].y * h)) for i in LEFT_EYE_IDX])
+        right_eye_pts = np.array([(int(landmarks[i].x * w), int(landmarks[i].y * h)) for i in RIGHT_EYE_IDX])
+
+        return blink, left_ear, right_ear, left_eye_pts, right_eye_pts
+
+    except Exception as e:
+        logger.error(f"Blink detection error: {str(e)}")
+        return False, 0.0, 0.0, None, None
+
+# --------------------------------------------------------------------
+# FACE MESH + IRIS DETECTION / DRAWING
+# --------------------------------------------------------------------
+def process_face_mesh(face_roi: np.ndarray):
+    try:
+        fm_proc = mp_face_mesh.FaceMesh(
+            static_image_mode=True,
+            max_num_faces=1,
+            refine_landmarks=True,
+            min_detection_confidence=0.5
+        )
+        result = fm_proc.process(cv2.cvtColor(face_roi, cv2.COLOR_BGR2RGB))
+        fm_proc.close()
+        if result.multi_face_landmarks:
+            return result.multi_face_landmarks[0]
+        return None
+    except Exception as e:
+        logger.error(f"Face mesh error: {str(e)}")
+        return None
+
+def draw_face_mesh(image: np.ndarray, face_landmarks, config: Dict, pipeline_config: PipelineConfig):
+    mesh_color_bgr = pipeline_config.mesh_color[::-1]
+    contour_color_bgr = pipeline_config.contour_color[::-1]
+    iris_color_bgr = pipeline_config.iris_color[::-1]
+
+    if config.get('tesselation'):
+        mp_drawing.draw_landmarks(
+            image,
+            face_landmarks,
+            mp_face_mesh.FACEMESH_TESSELATION,
+            landmark_drawing_spec=mp_drawing.DrawingSpec(color=mesh_color_bgr, thickness=1, circle_radius=1),
+            connection_drawing_spec=mp_drawing.DrawingSpec(color=mesh_color_bgr, thickness=1),
+        )
+    if config.get('contours'):
+        mp_drawing.draw_landmarks(
+            image,
+            face_landmarks,
+            mp_face_mesh.FACEMESH_CONTOURS,
+            landmark_drawing_spec=None,
+            connection_drawing_spec=mp_drawing.DrawingSpec(color=contour_color_bgr, thickness=2)
+        )
+    if config.get('irises'):
+        mp_drawing.draw_landmarks(
+            image,
+            face_landmarks,
+            mp_face_mesh.FACEMESH_IRISES,
+            landmark_drawing_spec=None,
+            connection_drawing_spec=mp_drawing.DrawingSpec(color=iris_color_bgr, thickness=2)
+        )
+
+# --------------------------------------------------------------------
+# EYE COLOR DETECTION
+# --------------------------------------------------------------------
+EYE_COLOR_RANGES = {
+    "amber": (255, 191, 0),
+    "blue": (0, 0, 255),
+    "brown": (139, 69, 19),
+    "green": (0, 128, 0),
+    "gray": (128, 128, 128),
+    "hazel": (102, 51, 0),
+}
+
+def classify_eye_color(rgb_color: Tuple[int,int,int]) -> str:
+    if rgb_color is None:
+        return "Unknown"
+    min_dist = float('inf')
+    best = "Unknown"
+    for color_name, ref_rgb in EYE_COLOR_RANGES.items():
+        dist = math.sqrt(sum([(a-b)**2 for a,b in zip(rgb_color, ref_rgb)]))
+        if dist < min_dist:
+            min_dist = dist
+            best = color_name
+    return best
+
+def get_dominant_color(image_roi, k=3):
+    if image_roi.size == 0:
+        return None
+    pixels = np.float32(image_roi.reshape(-1, 3))
+    criteria = (cv2.TERM_CRITERIA_EPS + cv2.TERM_CRITERIA_MAX_ITER, 100, 0.1)
+    _, labels, palette = cv2.kmeans(pixels, k, None, criteria, 10, cv2.KMEANS_RANDOM_CENTERS)
+    _, counts = np.unique(labels, return_counts=True)
+    dom_color = tuple(palette[np.argmax(counts)].astype(int).tolist())
+    return dom_color
+
+def detect_eye_color(face_roi: np.ndarray, face_landmarks) -> Optional[str]:
+    if face_landmarks is None:
+        return None
+    h, w = face_roi.shape[:2]
+    iris_inds = set()
+    for conn in mp_face_mesh.FACEMESH_IRISES:
+        iris_inds.update(conn)
+
+    iris_points = []
+    for idx in iris_inds:
+        lm = face_landmarks.landmark[idx]
+        iris_points.append((int(lm.x * w), int(lm.y * h)))
+    if not iris_points:
+        return None
+
+    min_x = min(pt[0] for pt in iris_points)
+    max_x = max(pt[0] for pt in iris_points)
+    min_y = min(pt[1] for pt in iris_points)
+    max_y = max(pt[1] for pt in iris_points)
+
+    pad = 5
+    x1 = max(0, min_x - pad)
+    y1 = max(0, min_y - pad)
+    x2 = min(w, max_x + pad)
+    y2 = min(h, max_y + pad)
+
+    eye_roi = face_roi[y1:y2, x1:x2]
+    # Resize for more stable KMeans
+    eye_roi_resize = cv2.resize(eye_roi, (40, 40), interpolation=cv2.INTER_AREA)
+
+    if eye_roi_resize.size == 0:
+        return None
+
+    dom_rgb = get_dominant_color(eye_roi_resize)
+    if dom_rgb is not None:
+        return classify_eye_color(dom_rgb)
+    return None
+
+# --------------------------------------------------------------------
+# HAND TRACKER
+# --------------------------------------------------------------------
+class HandTracker:
+    def __init__(self, min_detection_confidence=0.5, min_tracking_confidence=0.5):
+        self.hands = mp_hands.Hands(
+            static_image_mode=True,
+            max_num_hands=2,
+            min_detection_confidence=min_detection_confidence,
+            min_tracking_confidence=min_tracking_confidence,
+        )
+        logger.info("Initialized Mediapipe HandTracking")
+
+    def detect_hands(self, image: np.ndarray):
+        try:
+            img_rgb = cv2.cvtColor(image, cv2.COLOR_BGR2RGB)
+            results = self.hands.process(img_rgb)
+            return results.multi_hand_landmarks, results.multi_handedness
+        except Exception as e:
+            logger.error(f"Hand detection error: {str(e)}")
+            return None, None
+
+    def draw_hands(self, image: np.ndarray, hand_landmarks, handedness, config):
+        if not hand_landmarks:
+            return image
+
+        mpdraw = mp_drawing
+        for i, hlms in enumerate(hand_landmarks):
+            # Convert user config colors from (R,G,B) to (B,G,R)
+            hl_color = config.hand_landmark_color[::-1]
+            hc_color = config.hand_connection_color[::-1]
+            mpdraw.draw_landmarks(
+                image,
+                hlms,
+                mp_hands.HAND_CONNECTIONS,
+                mpdraw.DrawingSpec(color=hl_color, thickness=2, circle_radius=4),
+                mpdraw.DrawingSpec(color=hc_color, thickness=2, circle_radius=2),
+            )
+            if handedness and i < len(handedness):
+                label = handedness[i].classification[0].label
+                score = handedness[i].classification[0].score
+                text = f"{label}: {score:.2f}"
+                # We'll place text near the wrist
+                wrist_lm = hlms.landmark[mp_hands.HandLandmark.WRIST]
+                h, w, _ = image.shape
+                cx, cy = int(wrist_lm.x * w), int(wrist_lm.y * h)
+                ht_color = config.hand_text_color[::-1]
+                cv2.putText(image, text, (cx, cy - 10), cv2.FONT_HERSHEY_SIMPLEX, 0.5, ht_color, 2)
+        return image
+
 # --------------------------------------------------------------------
 # FACE PIPELINE
 # --------------------------------------------------------------------
@@ -299,155 +523,231 @@ class FacePipeline:
         self.tracker = None
         self.facenet = None
         self.db = None
+        self.hand_tracker = None
         self._initialized = False
 
     def initialize(self):
         try:
+            # YOLO for face detection
             self.detector = YOLOFaceDetector(
                 model_path=self.config.detector['model_path'],
                 device=self.config.detector['device']
             )
+            # DeepSort tracking
             self.tracker = FaceTracker(max_age=self.config.tracker['max_age'])
+            # FaceNet embedder
             self.facenet = FaceNetEmbedder(device=self.config.detector['device'])
+            # Database
             self.db = FaceDatabase()
+
+            # Hand tracker if enabled
+            if self.config.hand['enable']:
+                self.hand_tracker = HandTracker(
+                    min_detection_confidence=self.config.hand['min_detection_confidence'],
+                    min_tracking_confidence=self.config.hand['min_tracking_confidence']
+                )
+
             self._initialized = True
             logger.info("FacePipeline initialized successfully.")
         except Exception as e:
-            logger.error(f"Pipeline initialization failed: {str(e)}")
+            logger.error(f"Initialization failed: {str(e)}")
             self._initialized = False
             raise
 
     def process_frame(self, frame: np.ndarray) -> Tuple[np.ndarray, List[Dict]]:
+        """
+        Main pipeline processing: detection, tracking, hand detection, face mesh, blink detection, etc.
+        Returns annotated_frame, detection_results.
+        """
         if not self._initialized:
-            logger.error("Pipeline not initialized!")
+            logger.error("Pipeline not initialized.")
             return frame, []
 
         try:
+            # YOLO detection + DeepSort tracking
             detections = self.detector.detect(frame, self.config.detection_conf_thres)
-            tracked_objects = self.tracker.update(detections, frame)
-            annotated_frame = frame.copy()
+            tracked_objs = self.tracker.update(detections, frame)
+            annotated = frame.copy()
             results = []
 
-            for obj in tracked_objects:
+            # Hand detection if enabled
+            hand_landmarks_list = None
+            handedness_list = None
+            if self.config.hand['enable'] and self.hand_tracker:
+                hand_landmarks_list, handedness_list = self.hand_tracker.detect_hands(annotated)
+                annotated = self.hand_tracker.draw_hands(
+                    annotated, hand_landmarks_list, handedness_list, self.config
+                )
+
+            for obj in tracked_objs:
                 if not obj.is_confirmed():
                     continue
+
                 track_id = obj.track_id
-                bbox = obj.to_tlbr()
-                x1, y1, x2, y2 = bbox.astype(int)
+                bbox = obj.to_tlbr().astype(int)
+                x1, y1, x2, y2 = bbox
                 conf = getattr(obj, 'score', 1.0)
                 cls = getattr(obj, 'class_id', 0)
 
                 face_roi = frame[y1:y2, x1:x2]
                 if face_roi.size == 0:
-                    logger.warning(f"Empty face ROI for track {track_id}")
+                    logger.warning(f"Empty face ROI for track={track_id}")
                     continue
 
-                # Anti-spoof
+                # Anti-spoofing
                 is_spoofed = False
-                if self.config.anti_spoof['enable']:
+                if self.config.anti_spoof.get('enable', True):
                     is_spoofed = not self.is_real_face(face_roi)
                     if is_spoofed:
-                        cls = 1
+                        cls = 1  # Mark as spoofed
 
                 if is_spoofed:
                     box_color_bgr = self.config.spoofed_bbox_color[::-1]
                     name = "Spoofed"
                     similarity = 0.0
                 else:
-                    embedding = self.facenet.get_embedding(face_roi)
-                    if embedding is not None and self.config.recognition['enable']:
-                        name, similarity = self.recognize_face(
-                            embedding, self.config.recognition_conf_thres
-                        )
+                    # Face embedding + recognition
+                    emb = self.facenet.get_embedding(face_roi)
+                    if emb is not None and self.config.recognition.get('enable', True):
+                        name, similarity = self.recognize_face(emb, self.config.recognition_conf_thres)
                     else:
                         name = "Unknown"
                         similarity = 0.0
 
-                    box_color_rgb = (
-                        self.config.bbox_color
-                        if name != "Unknown"
-                        else self.config.unknown_bbox_color
-                    )
+                    box_color_rgb = (self.config.bbox_color if name != "Unknown" 
+                                     else self.config.unknown_bbox_color)
                     box_color_bgr = box_color_rgb[::-1]
 
-                label_text = f"{name}"
-                cv2.rectangle(annotated_frame, (x1, y1), (x2, y2), box_color_bgr, 2)
-                cv2.putText(
-                    annotated_frame, label_text, (x1, y1 - 10),
-                    cv2.FONT_HERSHEY_SIMPLEX, 0.5, box_color_bgr, 2
-                )
+                label_text = name
+                cv2.rectangle(annotated, (x1, y1), (x2, y2), box_color_bgr, 2)
+                cv2.putText(annotated, label_text, (x1, y1 - 10),
+                            cv2.FONT_HERSHEY_SIMPLEX, 0.5, box_color_bgr, 2)
 
+                # Blink detection
+                blink = False
+                if self.config.blink.get('enable', False):
+                    blink, left_ear, right_ear, left_eye_pts, right_eye_pts = detect_blink(
+                        face_roi, threshold=self.config.blink.get('ear_thresh', 0.25)
+                    )
+                    if left_eye_pts is not None and right_eye_pts is not None:
+                        # Shift points to global coords
+                        le_g = left_eye_pts + np.array([x1, y1])
+                        re_g = right_eye_pts + np.array([x1, y1])
+                        # Outline eyes
+                        eye_outline_bgr = self.config.eye_outline_color[::-1]
+                        cv2.polylines(annotated, [le_g], True, eye_outline_bgr, 1)
+                        cv2.polylines(annotated, [re_g], True, eye_outline_bgr, 1)
+                        if blink:
+                            blink_msg_color = self.config.blink_text_color[::-1]
+                            cv2.putText(annotated, "Blink Detected",
+                                        (x1, y2 + 20),
+                                        cv2.FONT_HERSHEY_SIMPLEX, 0.5,
+                                        blink_msg_color, 2)
+
+                # Face mesh + eye color
+                face_mesh_landmarks = None
+                eye_color_name = None
+                if (self.config.face_mesh_options.get('enable') or 
+                    self.config.eye_color.get('enable')):
+                    face_mesh_landmarks = process_face_mesh(face_roi)
+                    if face_mesh_landmarks:
+                        # If user wants to draw face mesh
+                        if self.config.face_mesh_options.get('enable', False):
+                            draw_face_mesh(
+                                annotated[y1:y2, x1:x2],
+                                face_mesh_landmarks,
+                                self.config.face_mesh_options,
+                                self.config
+                            )
+                        # Eye color
+                        if self.config.eye_color.get('enable', False):
+                            color_found = detect_eye_color(face_roi, face_mesh_landmarks)
+                            if color_found:
+                                eye_color_name = color_found
+                                text_col_bgr = self.config.eye_color_text_color[::-1]
+                                cv2.putText(
+                                    annotated, f"Eye Color: {eye_color_name}",
+                                    (x1, y2 + 40),
+                                    cv2.FONT_HERSHEY_SIMPLEX, 0.5,
+                                    text_col_bgr, 2
+                                )
+
+                # Record result
                 detection_info = {
-                    'track_id': track_id,
-                    'bbox': (x1, y1, x2, y2),
-                    'confidence': float(conf),
-                    'class_id': cls,
-                    'name': name,
-                    'similarity': float(similarity),
+                    "track_id": track_id,
+                    "bbox": (x1, y1, x2, y2),
+                    "confidence": float(conf),
+                    "class_id": cls,
+                    "name": name,
+                    "similarity": similarity,
+                    "blink": blink if self.config.blink.get('enable') else None,
+                    "face_mesh": bool(face_mesh_landmarks) if self.config.face_mesh_options.get('enable') else False,
+                    "hands_detected": bool(hand_landmarks_list),
+                    "hand_count": len(hand_landmarks_list) if hand_landmarks_list else 0,
+                    "eye_color": eye_color_name if self.config.eye_color.get('enable') else None
                 }
                 results.append(detection_info)
 
-            return annotated_frame, results
+            return annotated, results
 
         except Exception as e:
-            logger.error(f"Frame processing failed: {str(e)}", exc_info=True)
+            logger.error(f"Frame process error: {str(e)}")
             return frame, []
 
     def is_real_face(self, face_roi: np.ndarray) -> bool:
         try:
             gray = cv2.cvtColor(face_roi, cv2.COLOR_BGR2GRAY)
-            lap_var = cv2.Laplacian(gray, cv2.CV_64F).var()
-            return lap_var > self.config.anti_spoof['lap_thresh']
+            lapv = cv2.Laplacian(gray, cv2.CV_64F).var()
+            return lapv > self.config.anti_spoof.get('lap_thresh', 80.0)
         except Exception as e:
-            logger.error(f"Anti-spoof check failed: {str(e)}")
+            logger.error(f"Anti-spoof error: {str(e)}")
             return False
 
-    def recognize_face(self, embedding: np.ndarray, recognition_threshold: float) -> Tuple[str, float]:
+    def recognize_face(self, embedding: np.ndarray, threshold: float) -> Tuple[str, float]:
         try:
-            best_match = "Unknown"
-            best_similarity = 0.0
-            for label, embeddings in self.db.embeddings.items():
-                for db_emb in embeddings:
-                    similarity = FacePipeline.cosine_similarity(embedding, db_emb)
-                    if similarity > best_similarity:
-                        best_similarity = similarity
-                        best_match = label
-            if best_similarity < recognition_threshold:
-                best_match = "Unknown"
-            return best_match, best_similarity
+            best_name = "Unknown"
+            best_sim = 0.0
+            for lbl, embs in self.db.embeddings.items():
+                for db_emb in embs:
+                    sim = FacePipeline.cosine_similarity(embedding, db_emb)
+                    if sim > best_sim:
+                        best_sim = sim
+                        best_name = lbl
+            if best_sim < threshold:
+                best_name = "Unknown"
+            return best_name, best_sim
         except Exception as e:
-            logger.error(f"Face recognition failed: {str(e)}")
-            return "Unknown", 0.0
+            logger.error(f"Recognition error: {str(e)}")
+            return ("Unknown", 0.0)
 
     @staticmethod
     def cosine_similarity(a: np.ndarray, b: np.ndarray) -> float:
-        return float(np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b) + 1e-6))
+        return float(np.dot(a, b) / ((np.linalg.norm(a)*np.linalg.norm(b)) + 1e-6))
 
 # --------------------------------------------------------------------
-# GLOBAL PIPELINE
+# GLOBAL LOADER
 # --------------------------------------------------------------------
 pipeline = None
 def load_pipeline() -> FacePipeline:
     global pipeline
     if pipeline is None:
-        logger.info("Loading pipeline for the first time...")
         cfg = PipelineConfig.load(CONFIG_PATH)
         pipeline = FacePipeline(cfg)
         pipeline.initialize()
     return pipeline
 
 # --------------------------------------------------------------------
-# HELPER FUNCTIONS FOR GRADIO
+# UTILITY: HEX <-> BGR
 # --------------------------------------------------------------------
-def hex_to_bgr(hex_str: str) -> Tuple[int,int,int]:
-    if not hex_str.startswith('#'):
-        hex_str = f"#{hex_str}"
-    hex_str = hex_str.lstrip('#')
-    if len(hex_str) != 6:
+def hex_to_bgr(hexstr: str) -> Tuple[int,int,int]:
+    if not hexstr.startswith('#'):
+        hexstr = '#' + hexstr
+    h = hexstr.lstrip('#')
+    if len(h) != 6:
         return (255, 0, 0)
-    r = int(hex_str[0:2], 16)
-    g = int(hex_str[2:4], 16)
-    b = int(hex_str[4:6], 16)
+    r = int(h[0:2], 16)
+    g = int(h[2:4], 16)
+    b = int(h[4:6], 16)
     return (b,g,r)
 
 def bgr_to_hex(bgr: Tuple[int,int,int]) -> str:
@@ -455,18 +755,18 @@ def bgr_to_hex(bgr: Tuple[int,int,int]) -> str:
     return f"#{r:02x}{g:02x}{b:02x}"
 
 # --------------------------------------------------------------------
-# UPDATE CONFIG
+# GRADIO CALLBACKS
 # --------------------------------------------------------------------
 def update_config(
+    # toggles
     enable_recognition, enable_antispoof, enable_blink, enable_hand, enable_eyecolor, enable_facemesh,
     show_tesselation, show_contours, show_irises,
-    detection_conf, recognition_thresh, antispoof_thresh, blink_thresh,
-    hand_det_conf, hand_track_conf,
-    bbox_hex, spoofed_hex, unknown_hex,
-    eye_hex, blink_hex,
-    hand_landmark_hex, hand_connection_hex, hand_text_hex,
-    mesh_hex, contour_hex, iris_hex,
-    eye_color_text_hex
+    # thresholds
+    detection_conf, recognition_thresh, antispoof_thresh, blink_thresh, hand_det_conf, hand_track_conf,
+    # colors
+    bbox_hex, spoofed_hex, unknown_hex, eye_hex, blink_hex,
+    hand_landmark_hex, hand_connect_hex, hand_text_hex,
+    mesh_hex, contour_hex, iris_hex, eye_color_text_hex
 ):
     pl = load_pipeline()
     cfg = pl.config
@@ -498,7 +798,7 @@ def update_config(
     cfg.eye_outline_color = hex_to_bgr(eye_hex)[::-1]
     cfg.blink_text_color = hex_to_bgr(blink_hex)[::-1]
     cfg.hand_landmark_color = hex_to_bgr(hand_landmark_hex)[::-1]
-    cfg.hand_connection_color = hex_to_bgr(hand_connection_hex)[::-1]
+    cfg.hand_connection_color = hex_to_bgr(hand_connect_hex)[::-1]
     cfg.hand_text_color = hex_to_bgr(hand_text_hex)[::-1]
     cfg.mesh_color = hex_to_bgr(mesh_hex)[::-1]
     cfg.contour_color = hex_to_bgr(contour_hex)[::-1]
@@ -508,87 +808,68 @@ def update_config(
     cfg.save(CONFIG_PATH)
     return "Configuration saved successfully!"
 
-# --------------------------------------------------------------------
-# ENROLL MULTIPLE IMAGES (using gr.File)
-# --------------------------------------------------------------------
-def enroll_user(name: str, files: List[dict]) -> str:
-    """
-    Each item in `files` is a dict with keys:
-      - 'name': filename
-      - 'size': file size in bytes
-      - 'data': the binary file contents
-    We decode them into OpenCV images and process.
-    """
+def enroll_user(label_name: str, filepaths: List[str]) -> str:
+    """Enrolls a user by name using multiple image file paths."""
     pl = load_pipeline()
-    if not name:
+    if not label_name:
         return "Please provide a user name."
-    if not files or len(files) == 0:
+    if not filepaths or len(filepaths) == 0:
         return "No images provided."
 
-    count_enrolled = 0
-    for f in files:
-        file_bytes = f["data"]
-        np_array = np.frombuffer(file_bytes, np.uint8)
-        img_bgr = cv2.imdecode(np_array, cv2.IMREAD_COLOR)
+    enrolled_count = 0
+    for path in filepaths:
+        if not os.path.isfile(path):
+            continue
+        img_bgr = cv2.imread(path)
         if img_bgr is None:
             continue
-
-        detections = pl.detector.detect(img_bgr, pl.config.detection_conf_thres)
-        for x1, y1, x2, y2, conf, cls in detections:
-            face_roi = img_bgr[y1:y2, x1:x2]
-            if face_roi.size == 0:
+        # Detect face(s)
+        dets = pl.detector.detect(img_bgr, pl.config.detection_conf_thres)
+        for x1, y1, x2, y2, conf, cls in dets:
+            roi = img_bgr[y1:y2, x1:x2]
+            if roi.size == 0:
                 continue
-            emb = pl.facenet.get_embedding(face_roi)
+            emb = pl.facenet.get_embedding(roi)
             if emb is not None:
-                pl.db.add_embedding(name, emb)
-                count_enrolled += 1
+                pl.db.add_embedding(label_name, emb)
+                enrolled_count += 1
 
-    if count_enrolled > 0:
+    if enrolled_count > 0:
         pl.db.save()
-        return f"Enrolled {name} with {count_enrolled} face(s)!"
+        return f"Enrolled '{label_name}' with {enrolled_count} face(s)!"
     else:
-        return "No faces were detected or embedded. Enrollment failed."
+        return "No faces detected in provided images."
 
-# --------------------------------------------------------------------
-# SEARCH / USER MGMT
-# --------------------------------------------------------------------
 def search_by_name(name: str) -> str:
     pl = load_pipeline()
     if not name:
-        return "No name provided"
-    embeddings = pl.db.get_embeddings_by_label(name)
-    if embeddings:
-        return f"User '{name}' found with {len(embeddings)} embedding(s)."
+        return "No name entered."
+    embs = pl.db.get_embeddings_by_label(name)
+    if embs:
+        return f"'{name}' found with {len(embs)} embedding(s)."
     else:
-        return f"No embeddings found for user '{name}'."
+        return f"No embeddings found for '{name}'."
 
-def search_by_image(image: np.ndarray) -> str:
+def search_by_image(img: np.ndarray) -> str:
     pl = load_pipeline()
-    if image is None:
+    if img is None:
         return "No image uploaded."
-
-    # Convert to BGR for pipeline
-    img_bgr = cv2.cvtColor(image, cv2.COLOR_RGB2BGR)
-    detections = pl.detector.detect(img_bgr, pl.config.detection_conf_thres)
-    if not detections:
+    img_bgr = cv2.cvtColor(img, cv2.COLOR_RGB2BGR)
+    dets = pl.detector.detect(img_bgr, pl.config.detection_conf_thres)
+    if not dets:
         return "No faces detected in the uploaded image."
-
-    x1, y1, x2, y2, conf, cls = detections[0]
-    face_roi = img_bgr[y1:y2, x1:x2]
-    if face_roi.size == 0:
+    x1, y1, x2, y2, conf, cls = dets[0]
+    roi = img_bgr[y1:y2, x1:x2]
+    if roi.size == 0:
         return "Empty face ROI in the uploaded image."
 
-    emb = pl.facenet.get_embedding(face_roi)
+    emb = pl.facenet.get_embedding(roi)
     if emb is None:
-        return "Failed to generate embedding from the face."
-
-    search_results = pl.db.search_by_image(emb, pl.config.recognition_conf_thres)
-    if not search_results:
-        return "No matching users found in the database (under current threshold)."
-
-    lines = []
-    for label, sim in search_results:
-        lines.append(f" - {label}, similarity={sim:.3f}")
+        return "Could not generate embedding from face."
+    results = pl.db.search_by_image(emb, pl.config.recognition_conf_thres)
+    if not results:
+        return "No matches in the database under current threshold."
+    lines = [f"- {lbl} (sim={sim:.3f})" for lbl, sim in results]
     return "Search results:\n" + "\n".join(lines)
 
 def remove_user(label: str) -> str:
@@ -606,75 +887,74 @@ def list_users() -> str:
         return "Enrolled users:\n" + ", ".join(labels)
     return "No users enrolled."
 
-# --------------------------------------------------------------------
-# PROCESS SINGLE IMAGE (IMAGE TEST)
-# --------------------------------------------------------------------
 def process_test_image(img: np.ndarray) -> Tuple[np.ndarray, str]:
+    """Single-image test: run pipeline and return annotated image + JSON results."""
     if img is None:
         return None, "No image uploaded."
+
     pl = load_pipeline()
-    img_bgr = cv2.cvtColor(img, cv2.COLOR_RGB2BGR)
-    processed, detections = pl.process_frame(img_bgr)
-    out_rgb = cv2.cvtColor(processed, cv2.COLOR_BGR2RGB)
-    return out_rgb, str(detections)
+    bgr = cv2.cvtColor(img, cv2.COLOR_RGB2BGR)
+    processed, detections = pl.process_frame(bgr)
+    result_rgb = cv2.cvtColor(processed, cv2.COLOR_BGR2RGB)
+    return result_rgb, str(detections)
 
 # --------------------------------------------------------------------
-# BUILD THE GRADIO APP
+# BUILD GRADIO APP
 # --------------------------------------------------------------------
 def build_app():
     with gr.Blocks() as demo:
-        gr.Markdown("# Face Recognition System (Image-Only)")
+        gr.Markdown("# Complete Face Recognition System (Single-Image) with Mediapipe")
 
-        # -- Tab: Image Test --
+        # Tab: Image Test
         with gr.Tab("Image Test"):
-            gr.Markdown("Upload a single image for face detection & recognition:")
-            image_input = gr.Image(type="numpy", label="Upload Image")
-            image_out = gr.Image()
-            image_info = gr.Textbox(label="Detections", interactive=False)
+            gr.Markdown("Upload a single image to detect faces, run blink detection, face mesh, hand tracking, etc.")
+            test_in = gr.Image(type="numpy", label="Upload Image")
+            test_out = gr.Image()
+            test_info = gr.Textbox(label="Detections")
             process_btn = gr.Button("Process Image")
 
             process_btn.click(
                 fn=process_test_image,
-                inputs=image_input,
-                outputs=[image_out, image_info],
+                inputs=test_in,
+                outputs=[test_out, test_info],
             )
 
-        # -- Tab: Configuration --
+        # Tab: Configuration
         with gr.Tab("Configuration"):
-            gr.Markdown("Modify pipeline settings & thresholds.")
+            gr.Markdown("Adjust toggles, thresholds, and colors. Click Save to persist changes.")
 
             with gr.Row():
-                enable_recognition = gr.Checkbox(label="Enable Face Recognition", value=True)
+                enable_recognition = gr.Checkbox(label="Enable Recognition", value=True)
                 enable_antispoof = gr.Checkbox(label="Enable Anti-Spoof", value=True)
                 enable_blink = gr.Checkbox(label="Enable Blink Detection", value=True)
                 enable_hand = gr.Checkbox(label="Enable Hand Tracking", value=True)
                 enable_eyecolor = gr.Checkbox(label="Enable Eye Color Detection", value=False)
                 enable_facemesh = gr.Checkbox(label="Enable Face Mesh", value=False)
 
+            # Face Mesh sub-options
             gr.Markdown("**Face Mesh Options**")
             with gr.Row():
-                show_tesselation = gr.Checkbox(label="Show Tesselation", value=False)
-                show_contours = gr.Checkbox(label="Show Contours", value=False)
-                show_irises = gr.Checkbox(label="Show Irises", value=False)
+                show_tesselation = gr.Checkbox(label="Tesselation", value=False)
+                show_contours = gr.Checkbox(label="Contours", value=False)
+                show_irises = gr.Checkbox(label="Irises", value=False)
 
             gr.Markdown("**Thresholds**")
-            detection_conf = gr.Slider(0.0, 1.0, value=0.4, step=0.01, label="Detection Confidence Threshold")
-            recognition_thresh = gr.Slider(0.5, 1.0, value=0.85, step=0.01, label="Recognition Similarity Threshold")
-            antispoof_thresh = gr.Slider(0, 200, value=80, step=1, label="Anti-Spoof Laplacian Threshold")
-            blink_thresh = gr.Slider(0, 0.5, value=0.25, step=0.01, label="Blink EAR Threshold")
-            hand_det_conf = gr.Slider(0.0, 1.0, value=0.5, step=0.01, label="Hand Detection Confidence")
-            hand_track_conf = gr.Slider(0.0, 1.0, value=0.5, step=0.01, label="Hand Tracking Confidence")
+            detection_conf = gr.Slider(0, 1, 0.4, step=0.01, label="Detection Confidence")
+            recognition_thresh = gr.Slider(0.5, 1.0, 0.85, step=0.01, label="Recognition Threshold")
+            antispoof_thresh = gr.Slider(0, 200, 80, step=1, label="Anti-Spoof Threshold")
+            blink_thresh = gr.Slider(0, 0.5, 0.25, step=0.01, label="Blink EAR Threshold")
+            hand_det_conf = gr.Slider(0, 1, 0.5, step=0.01, label="Hand Detection Confidence")
+            hand_track_conf = gr.Slider(0, 1, 0.5, step=0.01, label="Hand Tracking Confidence")
 
             gr.Markdown("**Color Options (Hex)**")
             bbox_hex = gr.Textbox(label="Box Color (Recognized)", value="#00ff00")
             spoofed_hex = gr.Textbox(label="Box Color (Spoofed)", value="#ff0000")
             unknown_hex = gr.Textbox(label="Box Color (Unknown)", value="#ff0000")
-
             eye_hex = gr.Textbox(label="Eye Outline Color", value="#ffff00")
             blink_hex = gr.Textbox(label="Blink Text Color", value="#0000ff")
 
             hand_landmark_hex = gr.Textbox(label="Hand Landmark Color", value="#ffd24d")
-            hand_connection_hex = gr.Textbox(label="Hand Connection Color", value="#cc6600")
+            hand_connect_hex = gr.Textbox(label="Hand Connection Color", value="#cc6600")
             hand_text_hex = gr.Textbox(label="Hand Text Color", value="#ffffff")
 
             mesh_hex = gr.Textbox(label="Mesh Color", value="#64ff64")
@@ -688,84 +968,81 @@ def build_app():
             save_btn.click(
                 fn=update_config,
                 inputs=[
-                    enable_recognition, enable_antispoof, enable_blink, enable_hand,
-                    enable_eyecolor, enable_facemesh,
+                    enable_recognition, enable_antispoof, enable_blink, enable_hand, enable_eyecolor, enable_facemesh,
                     show_tesselation, show_contours, show_irises,
-                    detection_conf, recognition_thresh, antispoof_thresh, blink_thresh,
-                    hand_det_conf, hand_track_conf,
-                    bbox_hex, spoofed_hex, unknown_hex,
-                    eye_hex, blink_hex,
-                    hand_landmark_hex, hand_connection_hex, hand_text_hex,
+                    detection_conf, recognition_thresh, antispoof_thresh, blink_thresh, hand_det_conf, hand_track_conf,
+                    bbox_hex, spoofed_hex, unknown_hex, eye_hex, blink_hex,
+                    hand_landmark_hex, hand_connect_hex, hand_text_hex,
                     mesh_hex, contour_hex, iris_hex, eye_color_text_hex
                 ],
-                outputs=[save_msg],
+                outputs=[save_msg]
             )
 
-        # -- Tab: Database Management --
+        # Tab: Database Management
         with gr.Tab("Database Management"):
-            gr.Markdown("Enroll Users, Search by Name or Image, Remove or List.")
+            gr.Markdown("Enroll multiple images per user, search by name or image, remove users, list all users.")
 
             with gr.Accordion("User Enrollment", open=False):
-                enroll_name = gr.Textbox(label="Enter name for enrollment")
-                # Use gr.File with multiple file support:
-                enroll_files = gr.File(
-                    file_count="multiple",
-                    type="file",
-                    label="Upload Enrollment Images (multiple allowed)"
-                )
+                enroll_name = gr.Textbox(label="User Name")
+                enroll_paths = gr.File(file_count="multiple", type="filepath", label="Upload Multiple Images")
                 enroll_btn = gr.Button("Enroll User")
-                enroll_result = gr.Textbox(label="", interactive=False)
-                enroll_btn.click(fn=enroll_user, inputs=[enroll_name, enroll_files], outputs=[enroll_result])
+                enroll_result = gr.Textbox()
+
+                enroll_btn.click(
+                    fn=enroll_user,
+                    inputs=[enroll_name, enroll_paths],
+                    outputs=[enroll_result]
+                )
 
             with gr.Accordion("User Search", open=False):
-                search_mode = gr.Radio(["Name", "Image"], value="Name", label="Search Database By")
-                search_name_input = gr.Dropdown(label="Select User", choices=[], value=None, interactive=True)
-                search_image_input = gr.Image(type="numpy", label="Upload Image", visible=False)
+                search_mode = gr.Radio(["Name", "Image"], label="Search By", value="Name")
+                search_name_box = gr.Dropdown(label="Select User", choices=[], value=None, visible=True)
+                search_image_box = gr.Image(label="Upload Search Image", type="numpy", visible=False)
                 search_btn = gr.Button("Search")
-                search_result = gr.Textbox(label="", interactive=False)
+                search_out = gr.Textbox()
 
-                def update_search_visibility(mode):
+                def toggle_search(mode):
                     if mode == "Name":
                         return gr.update(visible=True), gr.update(visible=False)
                     else:
                         return gr.update(visible=False), gr.update(visible=True)
 
                 search_mode.change(
-                    fn=update_search_visibility,
+                    fn=toggle_search,
                     inputs=[search_mode],
-                    outputs=[search_name_input, search_image_input]
+                    outputs=[search_name_box, search_image_box]
                 )
 
-                def search_user(mode, name, img):
+                def do_search(mode, uname, img):
                     if mode == "Name":
-                        return search_by_name(name)
+                        return search_by_name(uname)
                     else:
                         return search_by_image(img)
 
                 search_btn.click(
-                    fn=search_user,
-                    inputs=[search_mode, search_name_input, search_image_input],
-                    outputs=[search_result]
+                    fn=do_search,
+                    inputs=[search_mode, search_name_box, search_image_box],
+                    outputs=[search_out]
                 )
 
             with gr.Accordion("User Management Tools", open=False):
                 list_btn = gr.Button("List Enrolled Users")
-                list_output = gr.Textbox(label="", interactive=False)
-                list_btn.click(fn=lambda: list_users(), inputs=[], outputs=[list_output])
+                list_out = gr.Textbox()
+                list_btn.click(fn=lambda: list_users(), inputs=[], outputs=[list_out])
 
-                def get_user_list():
+                def refresh_choices():
                     pl = load_pipeline()
                     return gr.update(choices=pl.db.list_labels())
 
-                refresh_users_btn = gr.Button("Refresh User List")
-                refresh_users_btn.click(fn=get_user_list, inputs=[], outputs=[search_name_input])
+                refresh_btn = gr.Button("Refresh User List")
+                refresh_btn.click(fn=refresh_choices, inputs=[], outputs=[search_name_box])
 
-                remove_user_select = gr.Dropdown(label="Select User to Remove", choices=[])
-                remove_btn = gr.Button("Remove Selected User")
-                remove_output = gr.Textbox(label="", interactive=False)
+                remove_box = gr.Dropdown(label="Select User to Remove", choices=[])
+                remove_btn = gr.Button("Remove")
+                remove_out = gr.Textbox()
 
-                remove_btn.click(fn=remove_user, inputs=[remove_user_select], outputs=[remove_output])
-                refresh_users_btn.click(fn=get_user_list, inputs=[], outputs=[remove_user_select])
+                remove_btn.click(fn=remove_user, inputs=[remove_box], outputs=[remove_out])
+                refresh_btn.click(fn=refresh_choices, inputs=[], outputs=[remove_box])
 
     return demo
 
@@ -774,5 +1051,5 @@ def build_app():
 # --------------------------------------------------------------------
 if __name__ == "__main__":
     app = build_app()
-    # If concurrency or GPU usage is high, you can use .queue():
+    # queue() is optional if concurrency is expected
     app.queue().launch(server_name="0.0.0.0", server_port=7860)