Update utils/cv_processing.py

utils/cv_processing.py

@@ -31,7 +31,7 @@
 PROFESSIONAL_BACKGROUNDS = {
     "office_modern": {
         "name": "Modern Office",
-        "type": "gradient", 
+        "type": "gradient",
         "colors": ["#f8f9fa", "#e9ecef", "#dee2e6"],
         "direction": "diagonal",
         "description": "Clean, contemporary office environment",
@@ -102,12 +102,13 @@ class BackgroundReplacementError(Exception):
     pass
 
 # ============================================================================
-# BACKGROUND HELPERS (NEW)
+# BACKGROUND HELPERS (LETTERBOX)
 # ============================================================================
 
 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:
@@ -138,100 +139,86 @@ def segment_person_hq(image: np.ndarray, predictor: Any, fallback_enabled: bool
     """High-quality person segmentation with intelligent automation"""
     if not USE_ENHANCED_SEGMENTATION:
         return segment_person_hq_original(image, predictor, fallback_enabled)
-    
+
     logger.debug("Using ENHANCED segmentation with intelligent automation")
-    
+
     if image is None or image.size == 0:
         raise SegmentationError("Invalid input image")
-    
+
     try:
-        # SAFE PREDICTOR CHECK - Added comprehensive validation
         if predictor is None:
             if fallback_enabled:
                 logger.warning("SAM2 predictor not available, using fallback")
                 return _fallback_segmentation(image)
-            else:
-                raise SegmentationError("SAM2 predictor not available")
-        
-        # Check if predictor has required methods
+            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)
-            else:
-                raise SegmentationError("Invalid predictor object")
-        
-        # Safe set_image call
+            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)
-            else:
-                raise SegmentationError(f"Predictor setup failed: {e}")
-        
+            raise SegmentationError(f"Predictor setup failed: {e}")
+
         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 not _validate_mask_quality(mask, image.shape[:2]):
             logger.warning("Mask quality validation failed")
             if fallback_enabled:
                 return _fallback_segmentation(image)
-            else:
-                raise SegmentationError("Poor mask quality")
-        
+            raise SegmentationError("Poor mask quality")
+
         logger.debug(f"Enhanced 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)
-        else:
-            raise SegmentationError(f"Unexpected error: {e}")
+        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"""
     if image is None or image.size == 0:
         raise SegmentationError("Invalid input image")
-    
+
     try:
-        # SAFE PREDICTOR CHECK - Added comprehensive validation
         if predictor is None:
             if fallback_enabled:
                 logger.warning("SAM2 predictor not available, using fallback")
                 return _fallback_segmentation(image)
-            else:
-                raise SegmentationError("SAM2 predictor not available")
-        
-        # Check if predictor has required methods
+            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)
-            else:
-                raise SegmentationError("Invalid predictor object")
-        
-        # Safe set_image call
+            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)
-            else:
-                raise SegmentationError(f"Predictor setup failed: {e}")
-        
+            raise SegmentationError(f"Predictor setup failed: {e}")
+
         h, w = image.shape[:2]
-        
+
         points = np.array([
             [w//2, h//4],
             [w//2, h//2],
@@ -242,10 +229,9 @@ def segment_person_hq_original(image: np.ndarray, predictor: Any, fallback_enabl
             [w//4, 2*h//3],
             [3*w//4, 2*h//3],
         ], dtype=np.float32)
-        
+
         labels = np.ones(len(points), dtype=np.int32)
-        
-        # Safe prediction with error handling
+
         try:
             with torch.no_grad():
                 masks, scores, _ = predictor.predict(
@@ -257,16 +243,14 @@ def segment_person_hq_original(image: np.ndarray, predictor: Any, fallback_enabl
             logger.error(f"SAM2 prediction failed: {e}")
             if fallback_enabled:
                 return _fallback_segmentation(image)
-            else:
-                raise SegmentationError(f"Prediction failed: {e}")
-        
+            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)
-            else:
-                raise SegmentationError("No masks generated")
-        
+            raise SegmentationError("No masks generated")
+
         if scores is None or len(scores) == 0:
             logger.warning("SAM2 returned no scores")
             best_mask = masks[0]
@@ -274,122 +258,117 @@ def segment_person_hq_original(image: np.ndarray, predictor: Any, fallback_enabl
             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)
-        
+
         if not _validate_mask_quality(mask, image.shape[:2]):
             logger.warning("Mask quality validation failed")
             if fallback_enabled:
                 return _fallback_segmentation(image)
-            else:
-                raise SegmentationError("Poor mask quality")
-        
+            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)
-        else:
-            raise SegmentationError(f"Unexpected error: {e}")
+        raise SegmentationError(f"Unexpected error: {e}")
 
 # ============================================================================
-# MASK REFINEMENT FUNCTIONS
+# MASK REFINEMENT
 # ============================================================================
 
-def refine_mask_hq(image: np.ndarray, mask: np.ndarray, matanyone_processor: Any, 
+def refine_mask_hq(image: np.ndarray, mask: np.ndarray, matanyone_processor: Any,
                    fallback_enabled: bool = True) -> np.ndarray:
     """Enhanced mask refinement with MatAnyone and robust fallbacks"""
     if image is None or mask is None:
         raise MaskRefinementError("Invalid input image or mask")
-    
+
     try:
         mask = _process_mask(mask)
-        
+
         if matanyone_processor is not None:
             try:
                 logger.debug("Attempting MatAnyone refinement")
                 refined_mask = _matanyone_refine(image, mask, matanyone_processor)
-                
+
                 if refined_mask is not None and _validate_mask_quality(refined_mask, image.shape[:2]):
                     logger.debug("MatAnyone refinement successful")
                     return refined_mask
                 else:
                     logger.warning("MatAnyone produced poor quality mask")
-                    
+
             except Exception as e:
                 logger.warning(f"MatAnyone refinement failed: {e}")
-        
+
         if fallback_enabled:
             logger.debug("Using enhanced OpenCV refinement")
             return enhance_mask_opencv_advanced(image, mask)
-        else:
-            raise MaskRefinementError("MatAnyone failed and fallback disabled")
-            
+
+        raise MaskRefinementError("MatAnyone failed and fallback disabled")
+
     except MaskRefinementError:
         raise
     except Exception as e:
         logger.error(f"Unexpected mask refinement error: {e}")
         if fallback_enabled:
             return enhance_mask_opencv_advanced(image, mask)
-        else:
-            raise MaskRefinementError(f"Unexpected error: {e}")
+        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"""
     try:
         if len(mask.shape) == 3:
             mask = cv2.cvtColor(mask, cv2.COLOR_BGR2GRAY)
-        
+
         if mask.max() <= 1.0:
             mask = (mask * 255).astype(np.uint8)
-        
+
         refined_mask = cv2.bilateralFilter(mask, 9, 75, 75)
         refined_mask = _guided_filter_approx(image, refined_mask, radius=8, eps=0.2)
-        
+
         kernel_close = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (5, 5))
         refined_mask = cv2.morphologyEx(refined_mask, cv2.MORPH_CLOSE, kernel_close)
-        
+
         kernel_open = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (3, 3))
         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
-        
+
     except Exception as e:
         logger.warning(f"Enhanced OpenCV refinement failed: {e}")
         return cv2.GaussianBlur(mask, (5, 5), 1.0)
 
 # ============================================================================
-# MATANYONE REFINEMENT (NEW LOGIC)
+# MATANYONE REFINEMENT (SAFE)
 # ============================================================================
 
 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
 
-        # Preprocess image: ensure float32, RGB, (C, H, W)
+        # image → float32 RGB CHW
         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))  # (H, W, C) → (C, H, W)
+                img = np.transpose(img, (2, 0, 1))
             img_tensor = torch.from_numpy(img)
         else:
-            img_tensor = image  # assume already tensor
+            img_tensor = image
 
-        # Preprocess mask: ensure float32, (H, W)
+        # mask → float32 HW
         if isinstance(mask, np.ndarray):
             mask_tensor = mask.astype(np.float32)
             if mask_tensor.max() > 1.0:
@@ -400,15 +379,12 @@ 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=objects)
+            output_prob = matanyone_processor.step(img_tensor, mask_tensor, objects=[1])
             refined_mask_tensor = matanyone_processor.output_prob_to_mask(output_prob)
 
         refined_mask = refined_mask_tensor.squeeze().detach().cpu().numpy()
@@ -425,7 +401,7 @@ def _matanyone_refine(image: np.ndarray, mask: np.ndarray, matanyone_processor:
         return None
 
 # ============================================================================
-# BACKGROUND REPLACEMENT FUNCTIONS
+# BACKGROUND REPLACEMENT
 # ============================================================================
 
 def replace_background_hq(frame: np.ndarray, mask: np.ndarray, background: np.ndarray,
@@ -433,138 +409,138 @@ def replace_background_hq(frame: np.ndarray, mask: np.ndarray, background: np.nd
     """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")
-    
+
     try:
-        background = cv2.resize(background, (frame.shape[1], frame.shape[0]), 
-                               interpolation=cv2.INTER_LANCZOS4)
-        
+        background = cv2.resize(background, (frame.shape[1], frame.shape[0]),
+                                interpolation=cv2.INTER_LANCZOS4)
+
         if len(mask.shape) == 3:
             mask = cv2.cvtColor(mask, cv2.COLOR_BGR2GRAY)
-        
+
         if mask.dtype != np.uint8:
             mask = mask.astype(np.uint8)
-        
+
         if mask.max() <= 1.0:
             logger.debug("Converting normalized mask to 0-255 range")
             mask = (mask * 255).astype(np.uint8)
-        
+
         try:
             result = _advanced_compositing(frame, mask, background)
             logger.debug("Advanced compositing successful")
             return result
-            
+
         except Exception as e:
             logger.warning(f"Advanced compositing failed: {e}")
             if fallback_enabled:
                 return _simple_compositing(frame, mask, background)
-            else:
-                raise BackgroundReplacementError(f"Advanced compositing failed: {e}")
-        
+            raise BackgroundReplacementError(f"Advanced compositing failed: {e}")
+
     except BackgroundReplacementError:
         raise
     except Exception as e:
         logger.error(f"Unexpected background replacement error: {e}")
         if fallback_enabled:
             return _simple_compositing(frame, mask, background)
-        else:
-            raise BackgroundReplacementError(f"Unexpected error: {e}")
+        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'}
-      (also backwards compatible with older dicts that contained 'type'/'colors')
-    - If 'custom_path' exists, we load that image and letterbox-fit it.
-    - Returns RGB np.ndarray of shape (height, width, 3).
+      (backwards compatible with older dicts that contained 'type'/'colors')
+    - If 'custom_path' exists, load and letterbox-fit it.
+    - Returns **BGR** (consistent with OpenCV).
     """
-    # Normalize inputs
     choice = "minimalist"
     custom_path = None
 
     if isinstance(bg_config, dict):
-        # new form
         choice = bg_config.get("background_choice", bg_config.get("name", "minimalist"))
         custom_path = bg_config.get("custom_path")
-        # Custom image takes precedence
+
+        # 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)
-                return _fit_image_letterbox(img_rgb, width, height, fill=(32, 32, 32))
-            else:
-                logger.warning(f"Failed to read custom background at {custom_path}. Falling back to style.")
-        # old form (has type/colors) – build from spec if present
+                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)
+                background = _create_solid_background(bg_config, width, height)  # already BGR
             else:
-                background = _create_gradient_background_enhanced(bg_config, width, height)
+                background = _create_gradient_background_enhanced(bg_config, width, height)  # returns BGR
             return _apply_background_adjustments(background, bg_config)
 
     elif isinstance(bg_config, str):
         choice = bg_config
 
-    # No custom path → use our lightweight styles
+    # 3) Built-in styles
     choice = (choice or "minimalist").lower()
     if choice not in PROFESSIONAL_BACKGROUNDS:
         choice = "minimalist"
     cfg = PROFESSIONAL_BACKGROUNDS[choice]
 
     if cfg.get("type") == "color":
-        background = _create_solid_background(cfg, width, height)
+        background = _create_solid_background(cfg, width, height)           # BGR
     else:
-        background = _create_gradient_background_enhanced(cfg, width, height)
+        background = _create_gradient_background_enhanced(cfg, width, height)  # BGR
 
     background = _apply_background_adjustments(background, cfg)
     return background
 
 # ============================================================================
-# VALIDATION FUNCTION
+# VALIDATION
 # ============================================================================
 
 def validate_video_file(video_path: str) -> Tuple[bool, str]:
     """Enhanced video file validation with detailed checks"""
     if not video_path or not os.path.exists(video_path):
         return False, "Video file not found"
-    
+
     try:
         file_size = os.path.getsize(video_path)
         if file_size == 0:
             return False, "Video file is empty"
-        
+
         if file_size > 2 * 1024 * 1024 * 1024:
             return False, "Video file too large (>2GB)"
-        
+
         cap = cv2.VideoCapture(video_path)
         if not cap.isOpened():
             return False, "Cannot open video file"
-        
+
         frame_count = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
         fps = cap.get(cv2.CAP_PROP_FPS)
         width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
         height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
-        
+
         cap.release()
-        
+
         if frame_count == 0:
             return False, "Video appears to be empty (0 frames)"
-        
+
         if fps <= 0 or fps > 120:
             return False, f"Invalid frame rate: {fps}"
-        
+
         if width <= 0 or height <= 0:
             return False, f"Invalid resolution: {width}x{height}"
-        
+
         if width > 4096 or height > 4096:
             return False, f"Resolution too high: {width}x{height} (max 4096x4096)"
-        
+
         duration = frame_count / fps
         if duration > 300:
             return False, f"Video too long: {duration:.1f}s (max 300s)"
-        
+
         return True, f"Valid video: {width}x{height}, {fps:.1f}fps, {duration:.1f}s"
-        
+
     except Exception as e:
         return False, f"Error validating video: {str(e)}"
 
@@ -575,117 +551,111 @@ 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)
-            else:
-                raise SegmentationError("Invalid predictor in intelligent prompts")
-        
+            raise SegmentationError("Invalid predictor in intelligent prompts")
+
         h, w = image.shape[:2]
         pos_points, neg_points = _generate_smart_prompts(image)
-        
+
         if len(pos_points) == 0:
             pos_points = np.array([[w//2, h//2]], dtype=np.float32)
-        
+
         points = np.vstack([pos_points, neg_points])
         labels = np.hstack([
             np.ones(len(pos_points), dtype=np.int32),
             np.zeros(len(neg_points), dtype=np.int32)
         ])
-        
+
         logger.debug(f"Using {len(pos_points)} positive, {len(neg_points)} negative points")
-        
+
         with torch.no_grad():
             masks, scores, _ = predictor.predict(
                 point_coords=points,
                 point_labels=labels,
                 multimask_output=True
             )
-        
+
         if masks is None or len(masks) == 0:
             raise SegmentationError("No masks generated")
-        
+
         if scores is not None and len(scores) > 0:
             best_idx = np.argmax(scores)
             best_mask = masks[best_idx]
             logger.debug(f"Selected mask {best_idx} with score {scores[best_idx]:.3f}")
         else:
             best_mask = masks[0]
-        
+
         return _process_mask(best_mask)
-        
+
     except Exception as e:
         logger.error(f"Intelligent prompting failed: {e}")
         if fallback_enabled:
             return _fallback_segmentation(image)
-        else:
-            raise
+        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)
-            else:
-                raise SegmentationError("Invalid predictor in basic prompts")
-        
+            raise SegmentationError("Invalid predictor in basic prompts")
+
         h, w = image.shape[:2]
-        
+
         positive_points = np.array([
             [w//2, h//3],
             [w//2, h//2],
             [w//2, 2*h//3],
         ], dtype=np.float32)
-        
+
         negative_points = np.array([
             [w//10, h//10],
             [9*w//10, h//10],
             [w//10, 9*h//10],
             [9*w//10, 9*h//10],
         ], dtype=np.float32)
-        
+
         points = np.vstack([positive_points, negative_points])
         labels = np.array([1, 1, 1, 0, 0, 0, 0], dtype=np.int32)
-        
+
         with torch.no_grad():
             masks, scores, _ = predictor.predict(
                 point_coords=points,
                 point_labels=labels,
                 multimask_output=True
             )
-        
+
         if masks is None or len(masks) == 0:
             raise SegmentationError("No masks generated")
-        
+
         best_idx = np.argmax(scores) if scores is not None and len(scores) > 0 else 0
         best_mask = masks[best_idx]
-        
+
         return _process_mask(best_mask)
-        
+
     except Exception as e:
         logger.error(f"Basic prompting failed: {e}")
         if fallback_enabled:
             return _fallback_segmentation(image)
-        else:
-            raise
+        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), 
+                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]:
@@ -695,13 +665,13 @@ def _generate_smart_prompts(image: np.ndarray) -> Tuple[np.ndarray, np.ndarray]:
                             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([
@@ -709,7 +679,7 @@ def _generate_smart_prompts(image: np.ndarray) -> Tuple[np.ndarray, np.ndarray]:
                 [w//2, h//2],
                 [w//2, 2*h//3],
             ], dtype=np.float32)
-        
+
         negative_points = np.array([
             [10, 10],
             [w-10, 10],
@@ -718,9 +688,9 @@ def _generate_smart_prompts(image: np.ndarray) -> Tuple[np.ndarray, np.ndarray]:
             [w//2, 5],
             [w//2, h-5],
         ], dtype=np.float32)
-        
+
         return positive_points, negative_points
-        
+
     except Exception as e:
         logger.warning(f"Smart prompt generation failed: {e}")
         h, w = image.shape[:2]
@@ -732,32 +702,31 @@ def _generate_smart_prompts(image: np.ndarray) -> Tuple[np.ndarray, np.ndarray]:
 # HELPER FUNCTIONS - REFINEMENT
 # ============================================================================
 
-def _auto_refine_mask_iteratively(image: np.ndarray, initial_mask: np.ndarray, 
-                                predictor: Any, max_iterations: int = 2) -> np.ndarray:
+def _auto_refine_mask_iteratively(image: np.ndarray, initial_mask: np.ndarray,
+                                  predictor: Any, max_iterations: int = 2) -> np.ndarray:
     """Automatically refine mask based on quality assessment with safe predictor access"""
     try:
-        # Check predictor validity before iterative refinement
         if predictor is None or not hasattr(predictor, 'predict'):
             logger.warning("Predictor invalid for iterative refinement, returning initial mask")
             return initial_mask
-        
+
         current_mask = initial_mask.copy()
-        
+
         for iteration in range(max_iterations):
             quality_score = _assess_mask_quality(current_mask, image)
             logger.debug(f"Iteration {iteration}: quality score = {quality_score:.3f}")
-            
+
             if quality_score > 0.85:
                 logger.debug(f"Quality sufficient after {iteration} iterations")
                 break
-            
+
             problem_areas = _find_mask_errors(current_mask, image)
-            
+
             if np.any(problem_areas):
                 corrective_points, corrective_labels = _generate_corrective_prompts(
                     image, current_mask, problem_areas
                 )
-                
+
                 if len(corrective_points) > 0:
                     try:
                         with torch.no_grad():
@@ -767,26 +736,26 @@ def _auto_refine_mask_iteratively(image: np.ndarray, initial_mask: np.ndarray,
                                 mask_input=current_mask[None, :, :],
                                 multimask_output=False
                             )
-                        
+
                         if masks is not None and len(masks) > 0:
                             refined_mask = _process_mask(masks[0])
-                            
+
                             if _assess_mask_quality(refined_mask, image) > quality_score:
                                 current_mask = refined_mask
                                 logger.debug(f"Improved mask in iteration {iteration}")
                             else:
                                 logger.debug(f"Refinement didn't improve quality in iteration {iteration}")
                                 break
-                        
+
                     except Exception as e:
                         logger.debug(f"Refinement iteration {iteration} failed: {e}")
                         break
             else:
                 logger.debug("No problem areas detected")
                 break
-        
+
         return current_mask
-        
+
     except Exception as e:
         logger.warning(f"Iterative refinement failed: {e}")
         return initial_mask
@@ -796,11 +765,11 @@ def _assess_mask_quality(mask: np.ndarray, image: np.ndarray) -> float:
     try:
         h, w = image.shape[:2]
         scores = []
-        
+
         mask_area = np.sum(mask > 127)
         total_area = h * w
         area_ratio = mask_area / total_area
-        
+
         if 0.05 <= area_ratio <= 0.8:
             area_score = 1.0
         elif area_ratio < 0.05:
@@ -808,32 +777,32 @@ def _assess_mask_quality(mask: np.ndarray, image: np.ndarray) -> float:
         else:
             area_score = max(0, 1.0 - (area_ratio - 0.8) / 0.2)
         scores.append(area_score)
-        
+
         mask_binary = mask > 127
         if np.any(mask_binary):
             mask_center_y, mask_center_x = np.where(mask_binary)
             center_y = np.mean(mask_center_y) / h
             center_x = np.mean(mask_center_x) / w
-            
+
             center_score = 1.0 - min(abs(center_x - 0.5), abs(center_y - 0.5))
             scores.append(center_score)
         else:
             scores.append(0.0)
-        
+
         edges = cv2.Canny(mask, 50, 150)
         edge_density = np.sum(edges > 0) / total_area
         smoothness_score = max(0, 1.0 - edge_density * 10)
         scores.append(smoothness_score)
-        
+
         num_labels, _ = cv2.connectedComponents(mask)
         connectivity_score = max(0, 1.0 - (num_labels - 2) * 0.2)
         scores.append(connectivity_score)
-        
+
         weights = [0.3, 0.2, 0.3, 0.2]
         overall_score = np.average(scores, weights=weights)
-        
+
         return overall_score
-        
+
     except Exception as e:
         logger.warning(f"Quality assessment failed: {e}")
         return 0.5
@@ -852,35 +821,35 @@ def _find_mask_errors(mask: np.ndarray, image: np.ndarray) -> np.ndarray:
         logger.warning(f"Error detection failed: {e}")
         return np.zeros_like(mask, dtype=bool)
 
-def _generate_corrective_prompts(image: np.ndarray, mask: np.ndarray, 
-                               problem_areas: np.ndarray) -> Tuple[np.ndarray, np.ndarray]:
+def _generate_corrective_prompts(image: np.ndarray, mask: np.ndarray,
+                                 problem_areas: np.ndarray) -> Tuple[np.ndarray, np.ndarray]:
     """Generate corrective prompts based on problem areas"""
     try:
-        contours, _ = cv2.findContours(problem_areas.astype(np.uint8), 
+        contours, _ = cv2.findContours(problem_areas.astype(np.uint8),
                                        cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
-        
+
         corrective_points = []
         corrective_labels = []
-        
+
         for contour in contours:
             if cv2.contourArea(contour) > 100:
                 M = cv2.moments(contour)
                 if M["m00"] != 0:
                     cx = int(M["m10"] / M["m00"])
                     cy = int(M["m01"] / M["m00"])
-                    
+
                     current_mask_value = mask[cy, cx]
-                    
+
                     if current_mask_value < 127:
                         corrective_points.append([cx, cy])
                         corrective_labels.append(1)
                     else:
                         corrective_points.append([cx, cy])
                         corrective_labels.append(0)
-        
+
         return (np.array(corrective_points, dtype=np.float32) if corrective_points else np.array([]).reshape(0, 2),
                 np.array(corrective_labels, dtype=np.int32) if corrective_labels else np.array([], dtype=np.int32))
-        
+
     except Exception as e:
         logger.warning(f"Corrective prompt generation failed: {e}")
         return np.array([]).reshape(0, 2), np.array([], dtype=np.int32)
@@ -894,10 +863,10 @@ def _process_mask(mask: np.ndarray) -> np.ndarray:
     try:
         if len(mask.shape) > 2:
             mask = mask.squeeze()
-        
+
         if len(mask.shape) > 2:
             mask = mask[:, :, 0] if mask.shape[2] > 0 else mask.sum(axis=2)
-        
+
         if mask.dtype == bool:
             mask = mask.astype(np.uint8) * 255
         elif mask.dtype == np.float32 or mask.dtype == np.float64:
@@ -907,15 +876,15 @@ def _process_mask(mask: np.ndarray) -> np.ndarray:
                 mask = np.clip(mask, 0, 255).astype(np.uint8)
         else:
             mask = mask.astype(np.uint8)
-        
+
         kernel = np.ones((3, 3), np.uint8)
         mask = cv2.morphologyEx(mask, cv2.MORPH_CLOSE, kernel)
         mask = cv2.morphologyEx(mask, cv2.MORPH_OPEN, kernel)
-        
+
         _, mask = cv2.threshold(mask, 127, 255, cv2.THRESH_BINARY)
-        
+
         return mask
-        
+
     except Exception as e:
         logger.error(f"Mask processing failed: {e}")
         h, w = mask.shape[:2] if len(mask.shape) >= 2 else (256, 256)
@@ -935,7 +904,6 @@ def _validate_mask_quality(mask: np.ndarray, image_shape: Tuple[int, int]) -> bo
         mask_area = int(np.sum(mask > 127))
         area_ratio = mask_area / total_area
 
-        # Only reject extreme cases
         if area_ratio < 0.02 or area_ratio > 0.95:
             logger.warning(f"Suspicious mask area ratio (hard reject): {area_ratio:.3f}")
             return False
@@ -960,41 +928,41 @@ def _fallback_segmentation(image: np.ndarray) -> np.ndarray:
     try:
         logger.info("Using fallback segmentation strategy")
         h, w = image.shape[:2]
-        
+
         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
-            
+
             kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (7, 7))
             mask = cv2.morphologyEx(mask, cv2.MORPH_CLOSE, kernel)
             mask = cv2.morphologyEx(mask, cv2.MORPH_OPEN, kernel)
-            
+
             if _validate_mask_quality(mask, image.shape[:2]):
                 logger.info("Background subtraction fallback successful")
                 return mask
-                
+
         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
-        
+
         logger.info("Using geometric fallback mask")
         return mask
-        
+
     except Exception as e:
         logger.error(f"All fallback strategies failed: {e}")
         h, w = image.shape[:2]
@@ -1008,28 +976,28 @@ def _guided_filter_approx(guide: np.ndarray, mask: np.ndarray, radius: int = 8,
         guide_gray = cv2.cvtColor(guide, cv2.COLOR_BGR2GRAY) if len(guide.shape) == 3 else guide
         guide_gray = guide_gray.astype(np.float32) / 255.0
         mask_float = mask.astype(np.float32) / 255.0
-        
+
         kernel_size = 2 * radius + 1
-        
+
         mean_guide = cv2.boxFilter(guide_gray, -1, (kernel_size, kernel_size))
         mean_mask = cv2.boxFilter(mask_float, -1, (kernel_size, kernel_size))
         corr_guide_mask = cv2.boxFilter(guide_gray * mask_float, -1, (kernel_size, kernel_size))
-        
+
         cov_guide_mask = corr_guide_mask - mean_guide * mean_mask
         mean_guide_sq = cv2.boxFilter(guide_gray * guide_gray, -1, (kernel_size, kernel_size))
         var_guide = mean_guide_sq - mean_guide * mean_guide
-        
+
         a = cov_guide_mask / (var_guide + eps)
         b = mean_mask - a * mean_guide
-        
+
         mean_a = cv2.boxFilter(a, -1, (kernel_size, kernel_size))
         mean_b = cv2.boxFilter(b, -1, (kernel_size, kernel_size))
-        
+
         output = mean_a * guide_gray + mean_b
         output = np.clip(output * 255, 0, 255).astype(np.uint8)
-        
+
         return output
-        
+
     except Exception as e:
         logger.warning(f"Guided filter approximation failed: {e}")
         return mask
@@ -1043,32 +1011,31 @@ def _advanced_compositing(frame: np.ndarray, mask: np.ndarray, background: np.nd
     try:
         threshold = 100
         _, mask_binary = cv2.threshold(mask, threshold, 255, cv2.THRESH_BINARY)
-        
+
         kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (5, 5))
         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 = 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)
-        
+        mask_smooth = np.where(mask_smooth > 0.5,
+                               np.minimum(mask_smooth * 1.1, 1.0),
+                               mask_smooth * 0.9)
+
         frame_adjusted = _color_match_edges(frame, background, mask_smooth)
-        
+
         alpha_3ch = np.stack([mask_smooth] * 3, axis=2)
-        
+
         frame_float = frame_adjusted.astype(np.float32)
         background_float = background.astype(np.float32)
-        
+
         result = frame_float * alpha_3ch + background_float * (1 - alpha_3ch)
         result = np.clip(result, 0, 255).astype(np.uint8)
-        
+
         return result
-        
+
     except Exception as e:
         logger.error(f"Advanced compositing error: {e}")
         raise
@@ -1079,25 +1046,25 @@ def _color_match_edges(frame: np.ndarray, background: np.ndarray, alpha: np.ndar
         edge_mask = cv2.Sobel(alpha, cv2.CV_64F, 1, 1, ksize=3)
         edge_mask = np.abs(edge_mask)
         edge_mask = (edge_mask > 0.1).astype(np.float32)
-        
+
         edge_areas = edge_mask > 0
         if not np.any(edge_areas):
             return frame
-        
+
         frame_adjusted = frame.copy().astype(np.float32)
         background_float = background.astype(np.float32)
-        
+
         adjustment_strength = 0.1
         for c in range(3):
             frame_adjusted[:, :, c] = np.where(
                 edge_areas,
-                frame_adjusted[:, :, c] * (1 - adjustment_strength) + 
+                frame_adjusted[:, :, c] * (1 - adjustment_strength) +
                 background_float[:, :, c] * adjustment_strength,
                 frame_adjusted[:, :, c]
             )
-        
+
         return np.clip(frame_adjusted, 0, 255).astype(np.uint8)
-        
+
     except Exception as e:
         logger.warning(f"Color matching failed: {e}")
         return frame
@@ -1106,22 +1073,22 @@ def _simple_compositing(frame: np.ndarray, mask: np.ndarray, background: np.ndar
     """Simple fallback compositing method"""
     try:
         logger.info("Using simple compositing fallback")
-        
+
         background = cv2.resize(background, (frame.shape[1], frame.shape[0]))
-        
+
         if len(mask.shape) == 3:
             mask = cv2.cvtColor(mask, cv2.COLOR_BGR2GRAY)
         if mask.max() <= 1.0:
             mask = (mask * 255).astype(np.uint8)
-        
+
         _, mask_binary = cv2.threshold(mask, 127, 255, cv2.THRESH_BINARY)
-        
+
         mask_norm = mask_binary.astype(np.float32) / 255.0
         mask_3ch = np.stack([mask_norm] * 3, axis=2)
-        
+
         result = frame * mask_3ch + background * (1 - mask_3ch)
         return result.astype(np.uint8)
-        
+
     except Exception as e:
         logger.error(f"Simple compositing failed: {e}")
         return frame
@@ -1131,27 +1098,27 @@ 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"""
+    """Create solid color background (returns 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"""
+    """Create enhanced gradient background with better quality (returns BGR)"""
     try:
         colors = bg_config["colors"]
         direction = bg_config.get("direction", "vertical")
-        
+
         rgb_colors = []
         for color_hex in colors:
             color_hex = color_hex.lstrip('#')
             rgb = tuple(int(color_hex[i:i+2], 16) for i in (0, 2, 4))
             rgb_colors.append(rgb)
-        
+
         if not rgb_colors:
             rgb_colors = [(128, 128, 128)]
-        
+
         if direction == "vertical":
             background = _create_vertical_gradient(rgb_colors, width, height)
         elif direction == "horizontal":
@@ -1162,26 +1129,22 @@ def _create_gradient_background_enhanced(bg_config: Dict[str, Any], width: int,
             background = _create_radial_gradient(rgb_colors, width, height, direction == "soft_radial")
         else:
             background = _create_vertical_gradient(rgb_colors, width, height)
-        
+
         return cv2.cvtColor(background, cv2.COLOR_RGB2BGR)
-        
+
     except Exception as e:
         logger.error(f"Gradient creation error: {e}")
         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"""
     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
-    
     return gradient
 
 def _create_horizontal_gradient(colors: list, width: int, height: int) -> np.ndarray:
-    """Create horizontal gradient using NumPy for performance"""
     gradient = np.zeros((height, width, 3), dtype=np.uint8)
     for x in range(width):
         progress = x / width if width > 0 else 0
@@ -1190,59 +1153,53 @@ def _create_horizontal_gradient(colors: list, width: int, height: int) -> np.nda
     return gradient
 
 def _create_diagonal_gradient(colors: list, width: int, height: int) -> np.ndarray:
-    """Create diagonal gradient using vectorized operations"""
     y_coords, x_coords = np.mgrid[0:height, 0:width]
     max_distance = width + height
     progress = (x_coords + y_coords) / max_distance
     progress = np.clip(progress, 0, 1)
-    
+
     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 _create_radial_gradient(colors: list, width: int, height: int, soft: bool = False) -> np.ndarray:
-    """Create radial gradient using vectorized operations"""
     center_x, center_y = width // 2, height // 2
     max_distance = np.sqrt(center_x**2 + center_y**2)
-    
-    y_coords, x_coords = np.mgrid[0:height, 0:width]
+
+    y, x = np.mgrid[0:height, 0:width]
     distances = np.sqrt((x - center_x)**2 + (y - center_y)**2)
     progress = distances / max_distance
     progress = np.clip(progress, 0, 1)
-    
+
     if soft:
         progress = np.power(progress, 0.7)
-    
+
     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)
-    
+
     num_segments = len(colors) - 1
     segment_progress = progress * num_segments
     segment_indices = np.floor(segment_progress).astype(int)
     segment_indices = np.clip(segment_indices, 0, num_segments - 1)
     local_progress = segment_progress - segment_indices
-    
+
     start_colors = np.array([colors[i][channel] for i in range(len(colors))])
     end_colors = np.array([colors[min(i + 1, len(colors) - 1)][channel] for i in range(len(colors))])
-    
+
     start_vals = start_colors[segment_indices]
     end_vals = end_colors[segment_indices]
-    
+
     result = start_vals + (end_vals - start_vals) * local_progress
     return np.clip(result, 0, 255).astype(np.uint8)
 
 def _interpolate_color(colors: list, progress: float) -> tuple:
-    """Interpolate between multiple colors"""
     if len(colors) == 1:
         return colors[0]
     elif len(colors) == 2:
@@ -1263,18 +1220,17 @@ 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)
-        
+
         if brightness != 1.0 or contrast != 1.0:
             background = background.astype(np.float32)
             background = background * contrast * brightness
             background = np.clip(background, 0, 255).astype(np.uint8)
-        
+
         return background
-        
+
     except Exception as e:
         logger.warning(f"Background adjustment failed: {e}")
         return background