Update utils/cv_processing.py

utils/cv_processing.py

@@ -3,7 +3,7 @@
 Contains segmentation, mask refinement, background replacement, and helper functions
 """
 
-# Set OMP_NUM_THREADS at the very beginning to prevent libgomp errors
+# ---- Early thread env (defensive) ----
 import os
 if 'OMP_NUM_THREADS' not in os.environ:
     os.environ['OMP_NUM_THREADS'] = '4'
@@ -23,10 +23,18 @@
 
 # Version control flags for CV functions
 USE_ENHANCED_SEGMENTATION = True
-USE_AUTO_TEMPORAL_CONSISTENCY = True
+USE_AUTO_TEMPORAL_CONSISTENCY = True  # reserved for future temporal smoothing
 USE_INTELLIGENT_PROMPTING = True
 USE_ITERATIVE_REFINEMENT = True
 
+# Validator thresholds (softened to avoid false negatives)
+MIN_AREA_RATIO = 0.015   # 1.5% of frame
+MAX_AREA_RATIO = 0.97    # 97% of frame
+
+# GrabCut / saliency config
+GRABCUT_ITERS = 3
+SALIENCY_THRESH = 0.65
+
 # Professional background templates
 PROFESSIONAL_BACKGROUNDS = {
     "office_modern": {
@@ -102,14 +110,10 @@ class BackgroundReplacementError(Exception):
     pass
 
 # ============================================================================
-# BACKGROUND HELPERS (LETTERBOX)
+# LETTERBOX FIT (RGB in, RGB out) for custom background images
 # ============================================================================
 
 def _fit_image_letterbox(img_rgb: np.ndarray, dst_w: int, dst_h: int, fill=(32, 32, 32)) -> np.ndarray:
-    """
-    Fit an RGB image into (dst_h, dst_w) with letterboxing (no stretch), borders filled with `fill`.
-    Returns an RGB image.
-    """
     h, w = img_rgb.shape[:2]
     if h == 0 or w == 0:
         return np.full((dst_h, dst_w, 3), fill, dtype=np.uint8)
@@ -136,7 +140,7 @@ def _fit_image_letterbox(img_rgb: np.ndarray, dst_w: int, dst_h: int, fill=(32,
 # ============================================================================
 
 def segment_person_hq(image: np.ndarray, predictor: Any, fallback_enabled: bool = True) -> np.ndarray:
-    """High-quality person segmentation with intelligent automation"""
+    """High-quality person segmentation with intelligent automation and robust cascade"""
     if not USE_ENHANCED_SEGMENTATION:
         return segment_person_hq_original(image, predictor, fallback_enabled)
 
@@ -146,50 +150,40 @@ def segment_person_hq(image: np.ndarray, predictor: Any, fallback_enabled: bool
         raise SegmentationError("Invalid input image")
 
     try:
-        if predictor is None:
-            if fallback_enabled:
-                logger.warning("SAM2 predictor not available, using fallback")
-                return _fallback_segmentation(image)
-            raise SegmentationError("SAM2 predictor not available")
-
-        if not hasattr(predictor, 'set_image') or not hasattr(predictor, 'predict'):
-            logger.warning("Predictor missing required methods, using fallback")
-            if fallback_enabled:
-                return _fallback_segmentation(image)
-            raise SegmentationError("Invalid predictor object")
-
-        try:
-            predictor.set_image(image)
-        except Exception as e:
-            logger.error(f"Failed to set image in predictor: {e}")
-            if fallback_enabled:
-                return _fallback_segmentation(image)
-            raise SegmentationError(f"Predictor setup failed: {e}")
+        # 1) SAM2 (if available)
+        if predictor and hasattr(predictor, 'set_image') and hasattr(predictor, 'predict'):
+            try:
+                predictor.set_image(image)
+                if USE_INTELLIGENT_PROMPTING:
+                    mask = _segment_with_intelligent_prompts(image, predictor, fallback_enabled=True)
+                else:
+                    mask = _segment_with_basic_prompts(image, predictor, fallback_enabled=True)
 
-        if USE_INTELLIGENT_PROMPTING:
-            mask = _segment_with_intelligent_prompts(image, predictor, fallback_enabled)
-        else:
-            mask = _segment_with_basic_prompts(image, predictor, fallback_enabled)
+                if USE_ITERATIVE_REFINEMENT and mask is not None:
+                    mask = _auto_refine_mask_iteratively(image, mask, predictor)
 
-        if USE_ITERATIVE_REFINEMENT and mask is not None:
-            mask = _auto_refine_mask_iteratively(image, mask, predictor)
+                if _validate_mask_quality(mask, image.shape[:2]):
+                    logger.debug("SAM2 mask accepted by validator")
+                    return mask
+                logger.warning("SAM2 mask failed validation; cascading to classical methods.")
+            except Exception as e:
+                logger.warning(f"SAM2 segmentation error: {e}")
 
-        if not _validate_mask_quality(mask, image.shape[:2]):
-            logger.warning("Mask quality validation failed")
-            if fallback_enabled:
-                return _fallback_segmentation(image)
-            raise SegmentationError("Poor mask quality")
+        # 2) Classical cascade when SAM2 is absent/weak
+        classical = _classical_segmentation_cascade(image)
+        if _validate_mask_quality(classical, image.shape[:2]):
+            logger.debug("Classical cascade mask accepted by validator")
+            return classical
 
-        logger.debug(f"Enhanced segmentation successful - mask range: {mask.min()}-{mask.max()}")
-        return mask
+        logger.warning("Classical cascade produced weak mask; using geometric fallback.")
+        return _geometric_person_mask(image)
 
-    except SegmentationError:
-        raise
     except Exception as e:
         logger.error(f"Unexpected segmentation error: {e}")
         if fallback_enabled:
-            return _fallback_segmentation(image)
-        raise SegmentationError(f"Unexpected error: {e}")
+            return _geometric_person_mask(image)
+        else:
+            raise SegmentationError(f"Unexpected error: {e}")
 
 def segment_person_hq_original(image: np.ndarray, predictor: Any, fallback_enabled: bool = True) -> np.ndarray:
     """Original version of person segmentation for rollback"""
@@ -197,89 +191,56 @@ def segment_person_hq_original(image: np.ndarray, predictor: Any, fallback_enabl
         raise SegmentationError("Invalid input image")
 
     try:
-        if predictor is None:
-            if fallback_enabled:
-                logger.warning("SAM2 predictor not available, using fallback")
-                return _fallback_segmentation(image)
-            raise SegmentationError("SAM2 predictor not available")
-
-        if not hasattr(predictor, 'set_image') or not hasattr(predictor, 'predict'):
-            logger.warning("Predictor missing required methods, using fallback")
-            if fallback_enabled:
-                return _fallback_segmentation(image)
-            raise SegmentationError("Invalid predictor object")
-
-        try:
+        # SAFE PREDICTOR CHECK
+        if predictor and hasattr(predictor, 'set_image') and hasattr(predictor, 'predict'):
+            h, w = image.shape[:2]
             predictor.set_image(image)
-        except Exception as e:
-            logger.error(f"Failed to set image in predictor: {e}")
-            if fallback_enabled:
-                return _fallback_segmentation(image)
-            raise SegmentationError(f"Predictor setup failed: {e}")
 
-        h, w = image.shape[:2]
-
-        points = np.array([
-            [w//2, h//4],
-            [w//2, h//2],
-            [w//2, 3*h//4],
-            [w//3, h//2],
-            [2*w//3, h//2],
-            [w//2, h//6],
-            [w//4, 2*h//3],
-            [3*w//4, 2*h//3],
-        ], dtype=np.float32)
+            points = np.array([
+                [w//2, h//4],
+                [w//2, h//2],
+                [w//2, 3*h//4],
+                [w//3, h//2],
+                [2*w//3, h//2],
+                [w//2, h//6],
+                [w//4, 2*h//3],
+                [3*w//4, 2*h//3],
+            ], dtype=np.float32)
 
-        labels = np.ones(len(points), dtype=np.int32)
+            labels = np.ones(len(points), dtype=np.int32)
 
-        try:
             with torch.no_grad():
                 masks, scores, _ = predictor.predict(
                     point_coords=points,
                     point_labels=labels,
                     multimask_output=True
                 )
-        except Exception as e:
-            logger.error(f"SAM2 prediction failed: {e}")
-            if fallback_enabled:
-                return _fallback_segmentation(image)
-            raise SegmentationError(f"Prediction failed: {e}")
 
-        if masks is None or len(masks) == 0:
-            logger.warning("SAM2 returned no masks")
-            if fallback_enabled:
-                return _fallback_segmentation(image)
-            raise SegmentationError("No masks generated")
+            if masks is None or len(masks) == 0:
+                logger.warning("SAM2 returned no masks")
+            else:
+                best_idx = np.argmax(scores) if (scores is not None and len(scores) > 0) else 0
+                best_mask = masks[best_idx]
+                mask = _process_mask(best_mask)
+                if _validate_mask_quality(mask, image.shape[:2]):
+                    logger.debug("Original SAM2 mask accepted by validator")
+                    return mask
 
-        if scores is None or len(scores) == 0:
-            logger.warning("SAM2 returned no scores")
-            best_mask = masks[0]
+        if fallback_enabled:
+            logger.warning("Falling back to classical segmentation")
+            return _classical_segmentation_cascade(image)
         else:
-            best_idx = np.argmax(scores)
-            best_mask = masks[best_idx]
-            logger.debug(f"Selected mask {best_idx} with score {scores[best_idx]:.3f}")
-
-        mask = _process_mask(best_mask)
+            raise SegmentationError("SAM2 failed and fallback disabled")
 
-        if not _validate_mask_quality(mask, image.shape[:2]):
-            logger.warning("Mask quality validation failed")
-            if fallback_enabled:
-                return _fallback_segmentation(image)
-            raise SegmentationError("Poor mask quality")
-
-        logger.debug(f"Segmentation successful - mask range: {mask.min()}-{mask.max()}")
-        return mask
-
-    except SegmentationError:
-        raise
     except Exception as e:
         logger.error(f"Unexpected segmentation error: {e}")
         if fallback_enabled:
-            return _fallback_segmentation(image)
-        raise SegmentationError(f"Unexpected error: {e}")
+            return _classical_segmentation_cascade(image)
+        else:
+            raise SegmentationError(f"Unexpected error: {e}")
 
 # ============================================================================
-# MASK REFINEMENT
+# MASK REFINEMENT FUNCTIONS
 # ============================================================================
 
 def refine_mask_hq(image: np.ndarray, mask: np.ndarray, matanyone_processor: Any,
@@ -291,6 +252,7 @@ def refine_mask_hq(image: np.ndarray, mask: np.ndarray, matanyone_processor: Any
     try:
         mask = _process_mask(mask)
 
+        # 1) MatAnyOne (if present)
         if matanyone_processor is not None:
             try:
                 logger.debug("Attempting MatAnyone refinement")
@@ -300,16 +262,43 @@ def refine_mask_hq(image: np.ndarray, mask: np.ndarray, matanyone_processor: Any
                     logger.debug("MatAnyone refinement successful")
                     return refined_mask
                 else:
-                    logger.warning("MatAnyone produced poor quality mask")
+                    logger.warning("MatAnyOne produced poor quality mask")
 
             except Exception as e:
-                logger.warning(f"MatAnyone refinement failed: {e}")
+                logger.warning(f"MatAnyOne refinement failed: {e}")
 
-        if fallback_enabled:
+        # 2) Advanced OpenCV refinement
+        try:
             logger.debug("Using enhanced OpenCV refinement")
-            return enhance_mask_opencv_advanced(image, mask)
+            opencv_mask = enhance_mask_opencv_advanced(image, mask)
+            if _validate_mask_quality(opencv_mask, image.shape[:2]):
+                return opencv_mask
+        except Exception as e:
+            logger.warning(f"OpenCV advanced refinement failed: {e}")
+
+        # 3) GrabCut refinement (auto rect from saliency)
+        try:
+            logger.debug("Using GrabCut refinement fallback")
+            gc_mask = _refine_with_grabcut(image, mask)
+            if _validate_mask_quality(gc_mask, image.shape[:2]):
+                return gc_mask
+        except Exception as e:
+            logger.warning(f"GrabCut refinement failed: {e}")
 
-        raise MaskRefinementError("MatAnyone failed and fallback disabled")
+        # 4) Saliency flood-fill refinement
+        try:
+            logger.debug("Using saliency refinement fallback")
+            sal_mask = _refine_with_saliency(image, mask)
+            if _validate_mask_quality(sal_mask, image.shape[:2]):
+                return sal_mask
+        except Exception as e:
+            logger.warning(f"Saliency refinement failed: {e}")
+
+        if fallback_enabled:
+            logger.debug("Returning original mask after failed refinements")
+            return mask
+        else:
+            raise MaskRefinementError("All refinements failed")
 
     except MaskRefinementError:
         raise
@@ -317,7 +306,8 @@ def refine_mask_hq(image: np.ndarray, mask: np.ndarray, matanyone_processor: Any
         logger.error(f"Unexpected mask refinement error: {e}")
         if fallback_enabled:
             return enhance_mask_opencv_advanced(image, mask)
-        raise MaskRefinementError(f"Unexpected error: {e}")
+        else:
+            raise MaskRefinementError(f"Unexpected error: {e}")
 
 def enhance_mask_opencv_advanced(image: np.ndarray, mask: np.ndarray) -> np.ndarray:
     """Advanced OpenCV-based mask enhancement with multiple techniques"""
@@ -338,6 +328,7 @@ def enhance_mask_opencv_advanced(image: np.ndarray, mask: np.ndarray) -> np.ndar
         refined_mask = cv2.morphologyEx(refined_mask, cv2.MORPH_OPEN, kernel_open)
 
         refined_mask = cv2.GaussianBlur(refined_mask, (3, 3), 0.8)
+
         _, refined_mask = cv2.threshold(refined_mask, 127, 255, cv2.THRESH_BINARY)
 
         return refined_mask
@@ -353,22 +344,23 @@ def enhance_mask_opencv_advanced(image: np.ndarray, mask: np.ndarray) -> np.ndar
 def _matanyone_refine(image: np.ndarray, mask: np.ndarray, matanyone_processor: Any) -> Optional[np.ndarray]:
     """Safe MatAnyOne refinement for a single frame with correct interface."""
     try:
+        # Check for correct MatAnyOne interface
         if not hasattr(matanyone_processor, 'step') or not hasattr(matanyone_processor, 'output_prob_to_mask'):
             logger.warning("MatAnyOne processor missing required methods (step, output_prob_to_mask)")
             return None
 
-        # image → float32 RGB CHW
+        # Preprocess image: ensure float32, RGB, (C, H, W)
         if isinstance(image, np.ndarray):
             img = image.astype(np.float32)
             if img.max() > 1.0:
                 img /= 255.0
             if img.shape[2] == 3:
-                img = np.transpose(img, (2, 0, 1))
+                img = np.transpose(img, (2, 0, 1))  # (H, W, C) → (C, H, W)
             img_tensor = torch.from_numpy(img)
         else:
-            img_tensor = image
+            img_tensor = image  # assume already tensor
 
-        # mask → float32 HW
+        # Preprocess mask: ensure float32, (H, W)
         if isinstance(mask, np.ndarray):
             mask_tensor = mask.astype(np.float32)
             if mask_tensor.max() > 1.0:
@@ -379,14 +371,20 @@ def _matanyone_refine(image: np.ndarray, mask: np.ndarray, matanyone_processor:
         else:
             mask_tensor = mask
 
+        # Move tensors to processor's device if available
         device = getattr(matanyone_processor, 'device', 'cpu')
         img_tensor = img_tensor.to(device)
         mask_tensor = mask_tensor.to(device)
 
+        # Step: encode mask on this frame
+        objects = [1]  # single object id
         with torch.no_grad():
-            output_prob = matanyone_processor.step(img_tensor, mask_tensor, objects=[1])
+            output_prob = matanyone_processor.step(img_tensor, mask_tensor, objects=objects)
+            # MatAnyOne returns output_prob as tensor
+
             refined_mask_tensor = matanyone_processor.output_prob_to_mask(output_prob)
 
+        # Convert to numpy and to uint8
         refined_mask = refined_mask_tensor.squeeze().detach().cpu().numpy()
         if refined_mask.max() <= 1.0:
             refined_mask = (refined_mask * 255).astype(np.uint8)
@@ -401,11 +399,11 @@ def _matanyone_refine(image: np.ndarray, mask: np.ndarray, matanyone_processor:
         return None
 
 # ============================================================================
-# BACKGROUND REPLACEMENT
+# BACKGROUND REPLACEMENT FUNCTIONS
 # ============================================================================
 
 def replace_background_hq(frame: np.ndarray, mask: np.ndarray, background: np.ndarray,
-                         fallback_enabled: bool = True) -> np.ndarray:
+                          fallback_enabled: bool = True) -> np.ndarray:
     """Enhanced background replacement with comprehensive error handling"""
     if frame is None or mask is None or background is None:
         raise BackgroundReplacementError("Invalid input frame, mask, or background")
@@ -433,7 +431,8 @@ def replace_background_hq(frame: np.ndarray, mask: np.ndarray, background: np.nd
             logger.warning(f"Advanced compositing failed: {e}")
             if fallback_enabled:
                 return _simple_compositing(frame, mask, background)
-            raise BackgroundReplacementError(f"Advanced compositing failed: {e}")
+            else:
+                raise BackgroundReplacementError(f"Advanced compositing failed: {e}")
 
     except BackgroundReplacementError:
         raise
@@ -441,62 +440,65 @@ def replace_background_hq(frame: np.ndarray, mask: np.ndarray, background: np.nd
         logger.error(f"Unexpected background replacement error: {e}")
         if fallback_enabled:
             return _simple_compositing(frame, mask, background)
-        raise BackgroundReplacementError(f"Unexpected error: {e}")
+        else:
+            raise BackgroundReplacementError(f"Unexpected error: {e}")
 
 def create_professional_background(bg_config: Dict[str, Any] | str, width: int, height: int) -> np.ndarray:
     """
-    Central background builder.
-    - Accepts a style string OR a dict like:
-        {'background_choice': 'minimalist', 'custom_path': '/path/to/image.jpg'}
-      (backwards compatible with older dicts that contained 'type'/'colors')
-    - If 'custom_path' exists, load and letterbox-fit it.
-    - Returns **BGR** (consistent with OpenCV).
+    Enhanced professional background creation with quality improvements.
+    Accepts style string or dict (can include custom_path). Returns BGR (OpenCV).
     """
-    choice = "minimalist"
-    custom_path = None
-
-    if isinstance(bg_config, dict):
-        choice = bg_config.get("background_choice", bg_config.get("name", "minimalist"))
-        custom_path = bg_config.get("custom_path")
-
-        # 1) Custom image takes precedence
-        if custom_path and os.path.exists(custom_path):
-            img_bgr = cv2.imread(custom_path, cv2.IMREAD_COLOR)
-            if img_bgr is not None:
-                # Fit in RGB, convert back to BGR for consistency
-                img_rgb = cv2.cvtColor(img_bgr, cv2.COLOR_BGR2RGB)
-                fitted_rgb = _fit_image_letterbox(img_rgb, width, height, fill=(32, 32, 32))
-                fitted_bgr = cv2.cvtColor(fitted_rgb, cv2.COLOR_RGB2BGR)
-                return fitted_bgr
-            logger.warning(f"Failed to read custom background at {custom_path}. Falling back to style.")
-
-        # 2) Old dict form with 'type'/'colors'
-        if "type" in bg_config and "colors" in bg_config:
-            if bg_config["type"] == "color":
-                background = _create_solid_background(bg_config, width, height)  # already BGR
-            else:
-                background = _create_gradient_background_enhanced(bg_config, width, height)  # returns BGR
-            return _apply_background_adjustments(background, bg_config)
+    try:
+        choice = "minimalist"
+        custom_path = None
+
+        if isinstance(bg_config, dict):
+            choice = bg_config.get("background_choice", bg_config.get("name", "minimalist"))
+            custom_path = bg_config.get("custom_path")
+
+            # Custom background path (letterboxed + BGR out)
+            if custom_path and os.path.exists(custom_path):
+                img_bgr = cv2.imread(custom_path, cv2.IMREAD_COLOR)
+                if img_bgr is not None:
+                    img_rgb = cv2.cvtColor(img_bgr, cv2.COLOR_BGR2RGB)
+                    fitted_rgb = _fit_image_letterbox(img_rgb, width, height, fill=(32, 32, 32))
+                    fitted_bgr = cv2.cvtColor(fitted_rgb, cv2.COLOR_RGB2BGR)
+                    return fitted_bgr
+                else:
+                    logger.warning(f"Failed to read custom background at {custom_path}. Falling back to style.")
 
-    elif isinstance(bg_config, str):
-        choice = bg_config
+            # Direct dict colors/type form support
+            if "type" in bg_config and "colors" in bg_config:
+                if bg_config["type"] == "color":
+                    background = _create_solid_background(bg_config, width, height)
+                else:
+                    background = _create_gradient_background_enhanced(bg_config, width, height)
+                background = _apply_background_adjustments(background, bg_config)
+                return background
 
-    # 3) Built-in styles
-    choice = (choice or "minimalist").lower()
-    if choice not in PROFESSIONAL_BACKGROUNDS:
-        choice = "minimalist"
-    cfg = PROFESSIONAL_BACKGROUNDS[choice]
+        elif isinstance(bg_config, str):
+            choice = bg_config
 
-    if cfg.get("type") == "color":
-        background = _create_solid_background(cfg, width, height)           # BGR
-    else:
-        background = _create_gradient_background_enhanced(cfg, width, height)  # BGR
+        choice = (choice or "minimalist").lower()
+        if choice not in PROFESSIONAL_BACKGROUNDS:
+            choice = "minimalist"
+
+        cfg = PROFESSIONAL_BACKGROUNDS[choice]
 
-    background = _apply_background_adjustments(background, cfg)
-    return background
+        if cfg.get("type") == "color":
+            background = _create_solid_background(cfg, width, height)
+        else:
+            background = _create_gradient_background_enhanced(cfg, width, height)
+
+        background = _apply_background_adjustments(background, cfg)
+        return background
+
+    except Exception as e:
+        logger.error(f"Background creation error: {e}")
+        return np.full((height, width, 3), (128, 128, 128), dtype=np.uint8)
 
 # ============================================================================
-# VALIDATION
+# VALIDATION FUNCTION
 # ============================================================================
 
 def validate_video_file(video_path: str) -> Tuple[bool, str]:
@@ -551,10 +553,12 @@ def validate_video_file(video_path: str) -> Tuple[bool, str]:
 def _segment_with_intelligent_prompts(image: np.ndarray, predictor: Any, fallback_enabled: bool = True) -> np.ndarray:
     """Intelligent automatic prompt generation for segmentation with safe predictor access"""
     try:
+        # Double-check predictor validity
         if predictor is None or not hasattr(predictor, 'predict'):
             if fallback_enabled:
-                return _fallback_segmentation(image)
-            raise SegmentationError("Invalid predictor in intelligent prompts")
+                return _classical_segmentation_cascade(image)
+            else:
+                raise SegmentationError("Invalid predictor in intelligent prompts")
 
         h, w = image.shape[:2]
         pos_points, neg_points = _generate_smart_prompts(image)
@@ -592,16 +596,19 @@ def _segment_with_intelligent_prompts(image: np.ndarray, predictor: Any, fallbac
     except Exception as e:
         logger.error(f"Intelligent prompting failed: {e}")
         if fallback_enabled:
-            return _fallback_segmentation(image)
-        raise
+            return _classical_segmentation_cascade(image)
+        else:
+            raise
 
 def _segment_with_basic_prompts(image: np.ndarray, predictor: Any, fallback_enabled: bool = True) -> np.ndarray:
     """Basic prompting method for segmentation with safe predictor access"""
     try:
+        # Double-check predictor validity
         if predictor is None or not hasattr(predictor, 'predict'):
             if fallback_enabled:
-                return _fallback_segmentation(image)
-            raise SegmentationError("Invalid predictor in basic prompts")
+                return _classical_segmentation_cascade(image)
+            else:
+                raise SegmentationError("Invalid predictor in basic prompts")
 
         h, w = image.shape[:2]
 
@@ -639,57 +646,47 @@ def _segment_with_basic_prompts(image: np.ndarray, predictor: Any, fallback_enab
     except Exception as e:
         logger.error(f"Basic prompting failed: {e}")
         if fallback_enabled:
-            return _fallback_segmentation(image)
-        raise
+            return _classical_segmentation_cascade(image)
+        else:
+            raise
 
 def _generate_smart_prompts(image: np.ndarray) -> Tuple[np.ndarray, np.ndarray]:
     """Generate optimal positive/negative points automatically"""
     try:
         h, w = image.shape[:2]
 
-        try:
-            saliency = cv2.saliency.StaticSaliencySpectralResidual_create()
-            success, saliency_map = saliency.computeSaliency(image)
-
-            if success:
-                saliency_thresh = cv2.threshold(saliency_map, 0.7, 1, cv2.THRESH_BINARY)[1]
-                contours, _ = cv2.findContours((saliency_thresh * 255).astype(np.uint8),
-                                               cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
-
-                positive_points = []
-                if contours:
-                    for contour in sorted(contours, key=cv2.contourArea, reverse=True)[:3]:
-                        M = cv2.moments(contour)
-                        if M["m00"] != 0:
-                            cx = int(M["m10"] / M["m00"])
-                            cy = int(M["m01"] / M["m00"])
-                            if 0 < cx < w and 0 < cy < h:
-                                positive_points.append([cx, cy])
-
-                if positive_points:
-                    logger.debug(f"Generated {len(positive_points)} saliency-based points")
-                    positive_points = np.array(positive_points, dtype=np.float32)
-                else:
-                    raise Exception("No valid saliency points found")
-
-        except Exception as e:
-            logger.debug(f"Saliency method failed: {e}, using fallback")
-            positive_points = np.array([
+        saliency = _compute_saliency(image)
+        positive_points = []
+        if saliency is not None:
+            saliency_thresh = (saliency > (SALIENCY_THRESH - 0.1)).astype(np.uint8) * 255
+            contours, _ = cv2.findContours(saliency_thresh, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+
+            if contours:
+                for contour in sorted(contours, key=cv2.contourArea, reverse=True)[:3]:
+                    M = cv2.moments(contour)
+                    if M["m00"] != 0:
+                        cx = int(M["m10"] / M["m00"])
+                        cy = int(M["m01"] / M["m00"])
+                        if 0 < cx < w and 0 < cy < h:
+                            positive_points.append([cx, cy])
+
+        if not positive_points:
+            positive_points = [
                 [w//2, h//3],
                 [w//2, h//2],
                 [w//2, 2*h//3],
-            ], dtype=np.float32)
+            ]
 
-        negative_points = np.array([
+        negative_points = [
             [10, 10],
             [w-10, 10],
             [10, h-10],
             [w-10, h-10],
             [w//2, 5],
             [w//2, h-5],
-        ], dtype=np.float32)
+        ]
 
-        return positive_points, negative_points
+        return np.array(positive_points, dtype=np.float32), np.array(negative_points, dtype=np.float32)
 
     except Exception as e:
         logger.warning(f"Smart prompt generation failed: {e}")
@@ -698,6 +695,146 @@ def _generate_smart_prompts(image: np.ndarray) -> Tuple[np.ndarray, np.ndarray]:
         negative_points = np.array([[10, 10], [w-10, 10]], dtype=np.float32)
         return positive_points, negative_points
 
+# ============================================================================
+# CLASSICAL SEGMENTATION CASCADE
+# ============================================================================
+
+def _classical_segmentation_cascade(image: np.ndarray) -> np.ndarray:
+    """
+    Robust non-AI cascade:
+      1) Background subtraction via edge-median
+      2) Saliency flood-fill
+      3) GrabCut from auto-rect
+      4) Geometric ellipse (final fallback)
+    """
+    # 1) Background subtraction
+    try:
+        gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
+
+        edge_pixels = np.concatenate([
+            gray[0, :], gray[-1, :], gray[:, 0], gray[:, -1]
+        ])
+        bg_color = np.median(edge_pixels)
+
+        diff = np.abs(gray.astype(float) - bg_color)
+        mask = (diff > 30).astype(np.uint8) * 255
+
+        mask = cv2.morphologyEx(mask, cv2.MORPH_CLOSE, cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (7, 7)))
+        mask = cv2.morphologyEx(mask, cv2.MORPH_OPEN,  cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (5, 5)))
+
+        if _validate_mask_quality(mask, image.shape[:2]):
+            logger.info("Background subtraction fallback successful")
+            return mask
+
+    except Exception as e:
+        logger.debug(f"Background subtraction fallback failed: {e}")
+
+    # 2) Saliency flood-fill refinement
+    try:
+        sal_ref = _refine_with_saliency(image, mask if 'mask' in locals() else np.zeros(image.shape[:2], np.uint8))
+        if _validate_mask_quality(sal_ref, image.shape[:2]):
+            return sal_ref
+    except Exception as e:
+        logger.debug(f"Saliency cascade failed: {e}")
+
+    # 3) GrabCut refinement
+    try:
+        gc_mask = _refine_with_grabcut(image, mask if 'mask' in locals() else np.zeros(image.shape[:2], np.uint8))
+        if _validate_mask_quality(gc_mask, image.shape[:2]):
+            return gc_mask
+    except Exception as e:
+        logger.debug(f"GrabCut cascade failed: {e}")
+
+    # 4) Geometric final fallback
+    logger.info("Using geometric fallback mask")
+    return _geometric_person_mask(image)
+
+# ============================================================================
+# SALIENCY / GRABCUT HELPERS
+# ============================================================================
+
+def _compute_saliency(image: np.ndarray) -> Optional[np.ndarray]:
+    try:
+        if hasattr(cv2, "saliency"):
+            sal = cv2.saliency.StaticSaliencySpectralResidual_create()
+            ok, smap = sal.computeSaliency(image)
+            if ok:
+                smap = (smap - smap.min()) / max(1e-6, (smap.max() - smap.min()))
+                return smap
+    except Exception:
+        pass
+    # Fallback spectral-ish hint using DCT trick
+    try:
+        gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY).astype(np.float32) / 255.0
+        log = np.log(gray + 1e-6)
+        dct = cv2.dct(log)
+        dct[:5, :5] = 0
+        recon = cv2.idct(dct)
+        recon = (recon - recon.min()) / max(1e-6, (recon.max() - recon.min()))
+        return recon
+    except Exception:
+        return None
+
+def _auto_person_rect(image: np.ndarray) -> Optional[Tuple[int, int, int, int]]:
+    sal = _compute_saliency(image)
+    if sal is None:
+        return None
+    th = (sal > SALIENCY_THRESH).astype(np.uint8) * 255
+    contours, _ = cv2.findContours(th, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+    if not contours:
+        return None
+    c = max(contours, key=cv2.contourArea)
+    x, y, w, h = cv2.boundingRect(c)
+    # Inflate
+    pad_x, pad_y = int(0.05*w), int(0.05*h)
+    H, W = image.shape[:2]
+    x = max(0, x - pad_x); y = max(0, y - pad_y)
+    w = min(W - x, w + 2*pad_x); h = min(H - y, h + 2*pad_y)
+    return (x, y, w, h)
+
+def _refine_with_grabcut(image: np.ndarray, seed_mask: np.ndarray) -> np.ndarray:
+    h, w = image.shape[:2]
+    gc_mask = np.full((h, w), cv2.GC_PR_BGD, dtype=np.uint8)
+    sure_fg = (seed_mask > 200)
+    gc_mask[sure_fg] = cv2.GC_FGD
+
+    rect = _auto_person_rect(image)
+    if rect is not None:
+        x, y, rw, rh = rect
+    else:
+        rw, rh = int(w * 0.5), int(h * 0.7)
+        x, y = (w - rw)//2, int(h*0.15)
+
+    bgdModel = np.zeros((1, 65), np.float64)
+    fgdModel = np.zeros((1, 65), np.float64)
+
+    cv2.grabCut(image, gc_mask, (x, y, rw, rh), bgdModel, fgdModel, GRABCUT_ITERS, cv2.GC_INIT_WITH_MASK)
+
+    mask_bin = np.where((gc_mask == cv2.GC_FGD) | (gc_mask == cv2.GC_PR_FGD), 255, 0).astype(np.uint8)
+    mask_bin = cv2.morphologyEx(mask_bin, cv2.MORPH_CLOSE, np.ones((3, 3), np.uint8))
+    return mask_bin
+
+def _refine_with_saliency(image: np.ndarray, seed_mask: np.ndarray) -> np.ndarray:
+    sal = _compute_saliency(image)
+    if sal is None:
+        return seed_mask
+    th = (sal > SALIENCY_THRESH).astype(np.uint8) * 255
+
+    # Anchor from seed center mass or center fallback
+    ys, xs = np.where(seed_mask > 127)
+    if len(ys) > 0:
+        cx, cy = int(np.mean(xs)), int(np.mean(ys))
+    else:
+        h, w = image.shape[:2]
+        cx, cy = w//2, h//2
+
+    ff = th.copy()
+    h, w = th.shape
+    mask = np.zeros((h+2, w+2), np.uint8)
+    cv2.floodFill(ff, mask, (cx, cy), 255, loDiff=5, upDiff=5, flags=4)
+    ff = cv2.morphologyEx(ff, cv2.MORPH_CLOSE, np.ones((5,5), np.uint8))
+    return ff
+
 # ============================================================================
 # HELPER FUNCTIONS - REFINEMENT
 # ============================================================================
@@ -887,44 +1024,43 @@ def _process_mask(mask: np.ndarray) -> np.ndarray:
 
     except Exception as e:
         logger.error(f"Mask processing failed: {e}")
-        h, w = mask.shape[:2] if len(mask.shape) >= 2 else (256, 256)
+        h, w = mask.shape[:2] if (mask is not None and hasattr(mask, 'shape') and len(mask.shape) >= 2) else (256, 256)
         fallback = np.zeros((h, w), dtype=np.uint8)
         fallback[h//4:3*h//4, w//4:3*w//4] = 255
         return fallback
 
 def _validate_mask_quality(mask: np.ndarray, image_shape: Tuple[int, int]) -> bool:
-    """
-    Soft validator: only reject clearly broken masks.
-    - Accept area ratios roughly between 2% and 95%.
-    - Don't fail on center; just warn.
-    """
+    """Validate that the mask meets quality criteria (soft reject policy)"""
     try:
         h, w = image_shape
-        total_area = max(1, h * w)
-        mask_area = int(np.sum(mask > 127))
-        area_ratio = mask_area / total_area
+        mask_area = np.sum(mask > 127)
+        total_area = h * w
 
-        if area_ratio < 0.02 or area_ratio > 0.95:
-            logger.warning(f"Suspicious mask area ratio (hard reject): {area_ratio:.3f}")
+        area_ratio = mask_area / total_area
+        if area_ratio < MIN_AREA_RATIO or area_ratio > MAX_AREA_RATIO:
+            logger.warning(f"Suspicious mask area ratio: {area_ratio:.3f}")
             return False
 
-        ys, xs = np.where(mask > 127)
-        if len(ys) == 0:
-            logger.warning("Empty mask (hard reject)")
+        mask_binary = mask > 127
+        mask_center_y, mask_center_x = np.where(mask_binary)
+
+        if len(mask_center_y) == 0:
+            logger.warning("Empty mask")
             return False
 
-        cy, cx = float(np.mean(ys)) / h, float(np.mean(xs)) / w
-        if cy < 0.10 or cy > 0.98:
-            logger.warning(f"Mask center unusual (advisory): y={cy:.2f}")
+        center_y = np.mean(mask_center_y)
+        # Advisory only (we no longer hard-reject based on center)
+        if center_y < h * 0.08 or center_y > h * 0.98:
+            logger.warning(f"Mask center unusual (advisory): y={center_y/h:.2f}")
 
         return True
 
     except Exception as e:
-        logger.warning(f"Mask validation error (allowing): {e}")
+        logger.warning(f"Mask validation error: {e}")
         return True
 
 def _fallback_segmentation(image: np.ndarray) -> np.ndarray:
-    """Fallback segmentation when AI models fail"""
+    """Legacy fallback segmentation; prefer _classical_segmentation_cascade"""
     try:
         logger.info("Using fallback segmentation strategy")
         h, w = image.shape[:2]
@@ -951,15 +1087,8 @@ def _fallback_segmentation(image: np.ndarray) -> np.ndarray:
         except Exception as e:
             logger.warning(f"Background subtraction fallback failed: {e}")
 
-        mask = np.zeros((h, w), dtype=np.uint8)
-
-        center_x, center_y = w // 2, h // 2
-        radius_x, radius_y = w // 3, h // 2.5
-
-        y, x = np.ogrid[:h, :w]
-        mask_ellipse = ((x - center_x) / radius_x) ** 2 + ((y - center_y) / radius_y) ** 2 <= 1
-        mask[mask_ellipse] = 255
-
+        # Geometric ellipse fallback
+        mask = _geometric_person_mask(image)
         logger.info("Using geometric fallback mask")
         return mask
 
@@ -1016,10 +1145,9 @@ def _advanced_compositing(frame: np.ndarray, mask: np.ndarray, background: np.nd
         mask_binary = cv2.morphologyEx(mask_binary, cv2.MORPH_CLOSE, kernel)
         mask_binary = cv2.morphologyEx(mask_binary, cv2.MORPH_OPEN, kernel)
 
-        mask_smooth = cv2.GaussianBlur(mask_binary.astype(np.float32), (5, 5), 1.0)
-        mask_smooth = mask_smooth / 255.0
-
+        mask_smooth = cv2.GaussianBlur(mask_binary.astype(np.float32), (5, 5), 1.0) / 255.0
         mask_smooth = np.power(mask_smooth, 0.8)
+
         mask_smooth = np.where(mask_smooth > 0.5,
                                np.minimum(mask_smooth * 1.1, 1.0),
                                mask_smooth * 0.9)
@@ -1098,14 +1226,14 @@ def _simple_compositing(frame: np.ndarray, mask: np.ndarray, background: np.ndar
 # ============================================================================
 
 def _create_solid_background(bg_config: Dict[str, Any], width: int, height: int) -> np.ndarray:
-    """Create solid color background (returns BGR)"""
+    """Create solid color background (BGR)"""
     color_hex = bg_config["colors"][0].lstrip('#')
     color_rgb = tuple(int(color_hex[i:i+2], 16) for i in (0, 2, 4))
     color_bgr = color_rgb[::-1]
     return np.full((height, width, 3), color_bgr, dtype=np.uint8)
 
 def _create_gradient_background_enhanced(bg_config: Dict[str, Any], width: int, height: int) -> np.ndarray:
-    """Create enhanced gradient background with better quality (returns BGR)"""
+    """Create enhanced gradient background with better quality (BGR out)"""
     try:
         colors = bg_config["colors"]
         direction = bg_config.get("direction", "vertical")
@@ -1137,25 +1265,26 @@ def _create_gradient_background_enhanced(bg_config: Dict[str, Any], width: int,
         return np.full((height, width, 3), (128, 128, 128), dtype=np.uint8)
 
 def _create_vertical_gradient(colors: list, width: int, height: int) -> np.ndarray:
+    """Create vertical gradient using NumPy for performance (RGB)"""
     gradient = np.zeros((height, width, 3), dtype=np.uint8)
     for y in range(height):
-        progress = y / height if height > 0 else 0
-        color = _interpolate_color(colors, progress)
-        gradient[y, :] = color
+        progress = y / max(1, height)
+        gradient[y, :] = _interpolate_color(colors, progress)
     return gradient
 
 def _create_horizontal_gradient(colors: list, width: int, height: int) -> np.ndarray:
+    """Create horizontal gradient using NumPy for performance (RGB)"""
     gradient = np.zeros((height, width, 3), dtype=np.uint8)
     for x in range(width):
-        progress = x / width if width > 0 else 0
-        color = _interpolate_color(colors, progress)
-        gradient[:, x] = color
+        progress = x / max(1, width)
+        gradient[:, x] = _interpolate_color(colors, progress)
     return gradient
 
 def _create_diagonal_gradient(colors: list, width: int, height: int) -> np.ndarray:
+    """Create diagonal gradient using vectorized operations (RGB)"""
     y_coords, x_coords = np.mgrid[0:height, 0:width]
     max_distance = width + height
-    progress = (x_coords + y_coords) / max_distance
+    progress = (x_coords + y_coords) / max(1, max_distance)
     progress = np.clip(progress, 0, 1)
 
     gradient = np.zeros((height, width, 3), dtype=np.uint8)
@@ -1164,12 +1293,13 @@ def _create_diagonal_gradient(colors: list, width: int, height: int) -> np.ndarr
     return gradient
 
 def _create_radial_gradient(colors: list, width: int, height: int, soft: bool = False) -> np.ndarray:
+    """Create radial gradient using vectorized operations (RGB)"""
     center_x, center_y = width // 2, height // 2
     max_distance = np.sqrt(center_x**2 + center_y**2)
 
-    y, x = np.mgrid[0:height, 0:width]
-    distances = np.sqrt((x - center_x)**2 + (y - center_y)**2)
-    progress = distances / max_distance
+    y_coords, x_coords = np.mgrid[0:height, 0:width]
+    distances = np.sqrt((x_coords - center_x)**2 + (y_coords - center_y)**2)
+    progress = distances / max(1e-6, max_distance)
     progress = np.clip(progress, 0, 1)
 
     if soft:
@@ -1178,9 +1308,11 @@ def _create_radial_gradient(colors: list, width: int, height: int, soft: bool =
     gradient = np.zeros((height, width, 3), dtype=np.uint8)
     for c in range(3):
         gradient[:, :, c] = _vectorized_color_interpolation(colors, progress, c)
+
     return gradient
 
 def _vectorized_color_interpolation(colors: list, progress: np.ndarray, channel: int) -> np.ndarray:
+    """Vectorized color interpolation for performance"""
     if len(colors) == 1:
         return np.full_like(progress, colors[0][channel], dtype=np.uint8)
 
@@ -1200,6 +1332,7 @@ def _vectorized_color_interpolation(colors: list, progress: np.ndarray, channel:
     return np.clip(result, 0, 255).astype(np.uint8)
 
 def _interpolate_color(colors: list, progress: float) -> tuple:
+    """Interpolate between multiple colors (RGB tuple)"""
     if len(colors) == 1:
         return colors[0]
     elif len(colors) == 2:
@@ -1210,7 +1343,7 @@ def _interpolate_color(colors: list, progress: float) -> tuple:
     else:
         segment = progress * (len(colors) - 1)
         idx = int(segment)
-        local_progress = segment - idx
+        local_progress = max(0.0, min(1.0, segment - idx))
         if idx >= len(colors) - 1:
             return colors[-1]
         c1, c2 = colors[idx], colors[idx + 1]
@@ -1220,6 +1353,7 @@ def _interpolate_color(colors: list, progress: float) -> tuple:
         return (r, g, b)
 
 def _apply_background_adjustments(background: np.ndarray, bg_config: Dict[str, Any]) -> np.ndarray:
+    """Apply brightness and contrast adjustments to background"""
     try:
         brightness = bg_config.get("brightness", 1.0)
         contrast = bg_config.get("contrast", 1.0)