Update utilities.py

utilities.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 """
-utilities.py - Helper functions and utilities for Video Background Replacement
-CRITICAL FIX: Fixed transparency issue by ensuring mask is properly normalized
+Enhanced utilities.py - Core computer vision functions with improved error handling
+Fixed transparency issues, added fallback strategies, and enhanced memory management
 """
 
 import os
@@ -11,271 +11,691 @@
 from PIL import Image, ImageDraw
 import logging
 import time
+from typing import Optional, Dict, Any, Tuple
+from pathlib import Path
 
 # Setup logging
 logging.basicConfig(level=logging.INFO)
 logger = logging.getLogger(__name__)
 
-# Professional background templates
+# Professional background templates with enhanced configurations
 PROFESSIONAL_BACKGROUNDS = {
     "office_modern": {
         "name": "Modern Office",
         "type": "gradient", 
         "colors": ["#f8f9fa", "#e9ecef", "#dee2e6"],
         "direction": "diagonal",
-        "description": "Clean, contemporary office environment"
+        "description": "Clean, contemporary office environment",
+        "brightness": 0.95,
+        "contrast": 1.1
     },
     "studio_blue": {
         "name": "Professional Blue",
         "type": "gradient",
         "colors": ["#1e3c72", "#2a5298", "#3498db"],
         "direction": "radial",
-        "description": "Broadcast-quality blue studio"
+        "description": "Broadcast-quality blue studio",
+        "brightness": 0.9,
+        "contrast": 1.2
     },
     "studio_green": {
         "name": "Broadcast Green",
         "type": "color",
         "colors": ["#00b894"],
         "chroma_key": True,
-        "description": "Professional green screen replacement"
+        "description": "Professional green screen replacement",
+        "brightness": 1.0,
+        "contrast": 1.0
     },
     "minimalist": {
         "name": "Minimalist White",
         "type": "gradient",
         "colors": ["#ffffff", "#f1f2f6", "#ddd"],
         "direction": "soft_radial",
-        "description": "Clean, minimal background"
+        "description": "Clean, minimal background",
+        "brightness": 0.98,
+        "contrast": 0.9
     },
     "warm_gradient": {
         "name": "Warm Sunset",
         "type": "gradient",
         "colors": ["#ff7675", "#fd79a8", "#fdcb6e"],
         "direction": "diagonal",
-        "description": "Warm, inviting atmosphere"
+        "description": "Warm, inviting atmosphere",
+        "brightness": 0.85,
+        "contrast": 1.15
     },
     "tech_dark": {
         "name": "Tech Dark",
         "type": "gradient",
         "colors": ["#0c0c0c", "#2d3748", "#4a5568"],
         "direction": "vertical",
-        "description": "Modern tech/gaming setup"
+        "description": "Modern tech/gaming setup",
+        "brightness": 0.7,
+        "contrast": 1.3
+    },
+    "corporate_blue": {
+        "name": "Corporate Blue",
+        "type": "gradient",
+        "colors": ["#667eea", "#764ba2", "#f093fb"],
+        "direction": "diagonal",
+        "description": "Professional corporate background",
+        "brightness": 0.88,
+        "contrast": 1.1
+    },
+    "nature_blur": {
+        "name": "Soft Nature",
+        "type": "gradient",
+        "colors": ["#a8edea", "#fed6e3", "#d299c2"],
+        "direction": "radial",
+        "description": "Soft blurred nature effect",
+        "brightness": 0.92,
+        "contrast": 0.95
     }
 }
 
-def segment_person_hq(image, predictor):
-    """High-quality person segmentation using provided SAM2 predictor"""
+class SegmentationError(Exception):
+    """Custom exception for segmentation failures"""
+    pass
+
+class MaskRefinementError(Exception):
+    """Custom exception for mask refinement failures"""
+    pass
+
+class BackgroundReplacementError(Exception):
+    """Custom exception for background replacement failures"""
+    pass
+
+def segment_person_hq(image: np.ndarray, predictor: Any, fallback_enabled: bool = True) -> np.ndarray:
+    """
+    High-quality person segmentation with enhanced error handling and fallback strategies
+    
+    Args:
+        image: Input image (H, W, 3)
+        predictor: SAM2 predictor instance
+        fallback_enabled: Whether to use fallback segmentation if AI fails
+        
+    Returns:
+        Binary mask (H, W) with values 0-255
+        
+    Raises:
+        SegmentationError: If segmentation fails and fallback is disabled
+    """
+    if image is None or image.size == 0:
+        raise SegmentationError("Invalid input image")
+    
     try:
-        predictor.set_image(image)
+        # Validate predictor
+        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")
+        
+        # Set image for prediction
+        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}")
+        
         h, w = image.shape[:2]
         
-        # Strategic point placement for person detection
+        # Enhanced strategic point placement for better person detection
         points = np.array([
-            [w//2, h//4],    # Top-center (head)
-            [w//2, h//2],    # Center (torso)
-            [w//2, 3*h//4],  # Bottom-center (legs)
-            [w//4, h//2],    # Left-side (arm)
-            [3*w//4, h//2],  # Right-side (arm)
-        ])
-        labels = np.ones(len(points))
-        
-        masks, scores, _ = predictor.predict(
-            point_coords=points,
-            point_labels=labels,
-            multimask_output=True
-        )
-        
-        # Select best mask
-        best_idx = np.argmax(scores)
-        best_mask = masks[best_idx]
-        
-        # CRITICAL FIX: Ensure mask is properly normalized to 0-255
-        if len(best_mask.shape) > 2:
-            best_mask = best_mask.squeeze()
-        
-        # Check if mask is in 0-1 range and convert to 0-255
-        if best_mask.max() <= 1.0:
-            best_mask = (best_mask * 255).astype(np.uint8)
+            [w//2, h//4],      # Head center
+            [w//2, h//2],      # Torso center
+            [w//2, 3*h//4],    # Lower body
+            [w//3, h//2],      # Left side
+            [2*w//3, h//2],    # Right side
+            [w//2, h//6],      # Upper head
+            [w//4, 2*h//3],    # Left leg area
+            [3*w//4, 2*h//3],  # Right leg area
+        ], dtype=np.float32)
+        
+        labels = np.ones(len(points), dtype=np.int32)
+        
+        # Perform prediction with error handling
+        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)
+            else:
+                raise SegmentationError(f"Prediction failed: {e}")
+        
+        # Validate prediction results
+        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")
+        
+        if scores is None or len(scores) == 0:
+            logger.warning("SAM2 returned no scores")
+            best_mask = masks[0]
+        else:
+            # Select best mask based on score
+            best_idx = np.argmax(scores)
+            best_mask = masks[best_idx]
+            logger.debug(f"Selected mask {best_idx} with score {scores[best_idx]:.3f}")
+        
+        # Process mask to ensure correct format
+        mask = _process_mask(best_mask)
+        
+        # Validate mask quality
+        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")
+        
+        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:
-            best_mask = best_mask.astype(np.uint8)
+            raise SegmentationError(f"Unexpected error: {e}")
+
+def _process_mask(mask: np.ndarray) -> np.ndarray:
+    """Process raw mask to ensure correct format and range"""
+    try:
+        # Handle different input formats
+        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)
         
-        # Post-process mask
-        kernel = np.ones((5, 5), np.uint8)
-        best_mask = cv2.morphologyEx(best_mask, cv2.MORPH_CLOSE, kernel)
-        best_mask = cv2.morphologyEx(best_mask, cv2.MORPH_OPEN, kernel, iterations=1)
+        # Ensure proper data type and range
+        if mask.dtype == bool:
+            mask = mask.astype(np.uint8) * 255
+        elif mask.dtype == np.float32 or mask.dtype == np.float64:
+            if mask.max() <= 1.0:
+                mask = (mask * 255).astype(np.uint8)
+            else:
+                mask = np.clip(mask, 0, 255).astype(np.uint8)
+        else:
+            mask = mask.astype(np.uint8)
         
-        # Ensure mask is binary and clean
-        _, best_mask = cv2.threshold(best_mask, 127, 255, cv2.THRESH_BINARY)
+        # Post-process for cleaner edges
+        kernel = np.ones((3, 3), np.uint8)
+        mask = cv2.morphologyEx(mask, cv2.MORPH_CLOSE, kernel)
+        mask = cv2.morphologyEx(mask, cv2.MORPH_OPEN, kernel)
         
-        logger.info(f"Mask after segmentation - shape: {best_mask.shape}, range: {best_mask.min()}-{best_mask.max()}")
+        # Ensure binary threshold
+        _, mask = cv2.threshold(mask, 127, 255, cv2.THRESH_BINARY)
         
-        return best_mask
+        return mask
         
     except Exception as e:
-        logger.error(f"Segmentation error: {e}")
-        # Fallback to simple center mask
+        logger.error(f"Mask processing failed: {e}")
+        # Return a basic fallback mask
+        h, w = mask.shape[:2] if 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:
+    """Validate that the mask meets quality criteria"""
+    try:
+        h, w = image_shape
+        mask_area = np.sum(mask > 127)
+        total_area = h * w
+        
+        # Check if mask area is reasonable (5% to 80% of image)
+        area_ratio = mask_area / total_area
+        if area_ratio < 0.05 or area_ratio > 0.8:
+            logger.warning(f"Suspicious mask area ratio: {area_ratio:.3f}")
+            return False
+        
+        # Check if mask is not just a blob in corner
+        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
+        
+        center_y = np.mean(mask_center_y)
+        center_x = np.mean(mask_center_x)
+        
+        # Person should be roughly centered
+        if center_y < h * 0.2 or center_y > h * 0.9:
+            logger.warning(f"Mask center too far from expected person location: y={center_y/h:.2f}")
+            return False
+        
+        return True
+        
+    except Exception as e:
+        logger.warning(f"Mask validation error: {e}")
+        return True  # Default to accepting mask if validation fails
+
+def _fallback_segmentation(image: np.ndarray) -> np.ndarray:
+    """Fallback segmentation when AI models fail"""
+    try:
+        logger.info("Using fallback segmentation strategy")
         h, w = image.shape[:2]
-        fallback_mask = np.zeros((h, w), dtype=np.uint8)
-        x1, y1 = w//4, h//6
-        x2, y2 = 3*w//4, 5*h//6
-        fallback_mask[y1:y2, x1:x2] = 255
-        logger.warning("Using fallback mask due to segmentation error")
-        return fallback_mask
+        
+        # Try background subtraction approach
+        try:
+            # Simple background subtraction
+            gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
+            
+            # Assume background is around the edges
+            edge_pixels = np.concatenate([
+                gray[0, :], gray[-1, :], gray[:, 0], gray[:, -1]
+            ])
+            bg_color = np.median(edge_pixels)
+            
+            # Create mask based on difference from background
+            diff = np.abs(gray.astype(float) - bg_color)
+            mask = (diff > 30).astype(np.uint8) * 255
+            
+            # Morphological operations to clean up
+            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 mask looks reasonable, use it
+            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}")
+        
+        # Simple geometric fallback
+        mask = np.zeros((h, w), dtype=np.uint8)
+        
+        # Create an elliptical mask in center assuming person location
+        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}")
+        # Last resort: simple center rectangle
+        h, w = image.shape[:2]
+        mask = np.zeros((h, w), dtype=np.uint8)
+        mask[h//6:5*h//6, w//4:3*w//4] = 255
+        return mask
 
-def refine_mask_hq(image, mask, matanyone_processor):
-    """Cinema-quality mask refinement using provided MatAnyone processor"""
+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
+    
+    Args:
+        image: Input image (H, W, 3)
+        mask: Input mask (H, W) with values 0-255
+        matanyone_processor: MatAnyone processor instance
+        fallback_enabled: Whether to use fallback refinement if MatAnyone fails
+        
+    Returns:
+        Refined mask (H, W) with values 0-255
+        
+    Raises:
+        MaskRefinementError: If refinement fails and fallback is disabled
+    """
+    if image is None or mask is None:
+        raise MaskRefinementError("Invalid input image or mask")
+    
     try:
-        # Ensure mask is 0-255 range
-        if mask.max() <= 1.0:
-            mask = (mask * 255).astype(np.uint8)
+        # Ensure mask is in correct format
+        mask = _process_mask(mask)
         
         # Try MatAnyone if available
         if matanyone_processor is not None:
             try:
-                refined_mask = matanyone_processor.infer(image, mask)
-                if refined_mask is not None:
-                    if len(refined_mask.shape) == 3:
-                        refined_mask = cv2.cvtColor(refined_mask, cv2.COLOR_BGR2GRAY)
-                    # Ensure proper range
-                    if refined_mask.max() <= 1.0:
-                        refined_mask = (refined_mask * 255).astype(np.uint8)
+                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
-            except:
-                pass
+                else:
+                    logger.warning("MatAnyone produced poor quality mask")
+                    
+            except Exception as e:
+                logger.warning(f"MatAnyone refinement failed: {e}")
+        
+        # Fallback to enhanced OpenCV refinement
+        if fallback_enabled:
+            logger.debug("Using enhanced OpenCV refinement")
+            return enhance_mask_opencv_advanced(image, mask)
+        else:
+            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}")
+
+def _matanyone_refine(image: np.ndarray, mask: np.ndarray, processor: Any) -> Optional[np.ndarray]:
+    """Attempt MatAnyone mask refinement"""
+    try:
+        # Different possible MatAnyone interfaces
+        if hasattr(processor, 'infer'):
+            refined_mask = processor.infer(image, mask)
+        elif hasattr(processor, 'process'):
+            refined_mask = processor.process(image, mask)
+        elif callable(processor):
+            refined_mask = processor(image, mask)
+        else:
+            logger.warning("Unknown MatAnyone interface")
+            return None
+        
+        if refined_mask is None:
+            return None
         
-        # Fallback to OpenCV refinement
-        logger.warning("Using OpenCV fallback for mask refinement")
-        return enhance_mask_opencv(image, mask)
+        # Process the refined mask
+        refined_mask = _process_mask(refined_mask)
+        
+        return refined_mask
         
     except Exception as e:
-        logger.error(f"Mask refinement error: {e}")
-        return enhance_mask_opencv(image, mask)
+        logger.warning(f"MatAnyone processing error: {e}")
+        return None
 
-def enhance_mask_opencv(image, mask):
-    """Enhanced mask refinement using OpenCV techniques"""
+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)
         
-        # Ensure mask is 0-255
+        # Ensure proper range
         if mask.max() <= 1.0:
             mask = (mask * 255).astype(np.uint8)
         
-        # Bilateral filtering for edge preservation
+        # Multi-stage refinement
+        
+        # 1. Bilateral filtering for edge preservation
         refined_mask = cv2.bilateralFilter(mask, 9, 75, 75)
         
-        # Morphological operations for cleaner edges
-        kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (5, 5))
-        refined_mask = cv2.morphologyEx(refined_mask, cv2.MORPH_CLOSE, kernel)
-        refined_mask = cv2.morphologyEx(refined_mask, cv2.MORPH_OPEN, kernel)
+        # 2. Edge-aware smoothing using guided filter approximation
+        refined_mask = _guided_filter_approx(image, refined_mask, radius=8, eps=0.2)
         
-        # Ensure binary mask
-        _, refined_mask = cv2.threshold(refined_mask, 127, 255, cv2.THRESH_BINARY)
+        # 3. Morphological operations for structure
+        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)
         
-        # Smooth edges
-        refined_mask = cv2.GaussianBlur(refined_mask, (3, 3), 1.0)
+        # 4. Final smoothing
+        refined_mask = cv2.GaussianBlur(refined_mask, (3, 3), 0.8)
+        
+        # 5. Ensure binary output
+        _, refined_mask = cv2.threshold(refined_mask, 127, 255, cv2.THRESH_BINARY)
         
         return refined_mask
         
     except Exception as e:
-        logger.warning(f"Enhanced mask refinement error: {e}")
+        logger.warning(f"Enhanced OpenCV refinement failed: {e}")
+        # Simple fallback
+        return cv2.GaussianBlur(mask, (5, 5), 1.0)
+
+def _guided_filter_approx(guide: np.ndarray, mask: np.ndarray, radius: int = 8, eps: float = 0.2) -> np.ndarray:
+    """Approximation of guided filter for edge-aware smoothing"""
+    try:
+        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
+        
+        # Box filter approximation
+        kernel_size = 2 * radius + 1
+        
+        # Mean filters
+        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))
+        
+        # Covariance
+        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
+        
+        # Coefficients
+        a = cov_guide_mask / (var_guide + eps)
+        b = mean_mask - a * mean_guide
+        
+        # Apply coefficients
+        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
 
-# ============================================================================ #
-# CRITICAL FIX: Fixed transparency issue in background replacement
-# ============================================================================ #
-def replace_background_hq(frame, mask, background):
-    """High-quality background replacement with FIXED transparency handling"""
+def replace_background_hq(frame: np.ndarray, mask: np.ndarray, background: np.ndarray,
+                         fallback_enabled: bool = True) -> np.ndarray:
+    """
+    Enhanced background replacement with comprehensive error handling and quality improvements
+    
+    Args:
+        frame: Input frame (H, W, 3)
+        mask: Binary mask (H, W) with values 0-255
+        background: Background image (H, W, 3)
+        fallback_enabled: Whether to use fallback if main method fails
+        
+    Returns:
+        Composited frame (H, W, 3)
+        
+    Raises:
+        BackgroundReplacementError: If replacement fails and fallback is disabled
+    """
+    if frame is None or mask is None or background is None:
+        raise BackgroundReplacementError("Invalid input frame, mask, or background")
+    
     try:
         # Resize background to match frame
-        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)
         
-        # Ensure mask is single channel
+        # Process mask
         if len(mask.shape) == 3:
             mask = cv2.cvtColor(mask, cv2.COLOR_BGR2GRAY)
         
-        # CRITICAL FIX: Ensure mask is in 0-255 range
         if mask.dtype != np.uint8:
             mask = mask.astype(np.uint8)
         
         if mask.max() <= 1.0:
-            logger.warning("Mask appears to be normalized 0-1, converting to 0-255")
+            logger.debug("Converting normalized mask to 0-255 range")
             mask = (mask * 255).astype(np.uint8)
         
-        # Log mask statistics for debugging
-        logger.info(f"Mask stats before threshold - min: {mask.min()}, max: {mask.max()}, mean: {mask.mean():.2f}")
+        # Enhanced compositing with multiple techniques
+        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}")
         
-        # Create binary mask with adjusted threshold
-        threshold = 100  # Lower threshold to catch more of the person
+    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}")
+
+def _advanced_compositing(frame: np.ndarray, mask: np.ndarray, background: np.ndarray) -> np.ndarray:
+    """Advanced compositing with edge feathering and color correction"""
+    try:
+        # Create high-quality alpha mask
+        threshold = 100  # Lower threshold for better person extraction
         _, mask_binary = cv2.threshold(mask, threshold, 255, cv2.THRESH_BINARY)
         
-        # Clean up mask with morphological operations
+        # Clean up mask
         kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (5, 5))
-        mask_binary = cv2.morphologyEx(mask_binary, cv2.MORPH_CLOSE, kernel)  # Fill holes
-        mask_binary = cv2.morphologyEx(mask_binary, cv2.MORPH_OPEN, kernel)   # Remove noise
+        mask_binary = cv2.morphologyEx(mask_binary, cv2.MORPH_CLOSE, kernel)
+        mask_binary = cv2.morphologyEx(mask_binary, cv2.MORPH_OPEN, kernel)
         
-        # Create smooth edges with minimal feathering
+        # Create smooth alpha channel with edge feathering
         mask_smooth = cv2.GaussianBlur(mask_binary.astype(np.float32), (5, 5), 1.0)
-        mask_smooth = mask_smooth / 255.0  # Normalize to 0-1 for blending
+        mask_smooth = mask_smooth / 255.0
         
-        # Ensure opaque center by applying curve adjustment
-        mask_smooth = np.power(mask_smooth, 0.8)  # Makes transition sharper
+        # Apply gamma correction for better blending
+        mask_smooth = np.power(mask_smooth, 0.8)
         
-        # Apply threshold to ensure solid center
+        # Enhance edges - boost values near 1.0, reduce values near 0.0
         mask_smooth = np.where(mask_smooth > 0.5, 
-                               np.minimum(mask_smooth * 1.1, 1.0),  # Boost high values
-                               mask_smooth * 0.9)  # Slightly reduce low values
+                              np.minimum(mask_smooth * 1.1, 1.0),
+                              mask_smooth * 0.9)
+        
+        # Color matching between foreground and background
+        frame_adjusted = _color_match_edges(frame, background, mask_smooth)
         
-        # Create 3-channel mask for blending
-        mask_3channel = np.stack([mask_smooth] * 3, axis=2)
+        # Create 3-channel alpha mask
+        alpha_3ch = np.stack([mask_smooth] * 3, axis=2)
         
-        # Perform compositing
-        frame_float = frame.astype(np.float32)
+        # Perform high-quality compositing
+        frame_float = frame_adjusted.astype(np.float32)
         background_float = background.astype(np.float32)
         
-        result = frame_float * mask_3channel + background_float * (1 - mask_3channel)
+        # Alpha blending with gamma correction
+        result = frame_float * alpha_3ch + background_float * (1 - alpha_3ch)
         result = np.clip(result, 0, 255).astype(np.uint8)
         
-        # Log final statistics
-        logger.info(f"Final mask stats - min: {mask_smooth.min():.3f}, max: {mask_smooth.max():.3f}, mean: {mask_smooth.mean():.3f}")
-        
         return result
         
     except Exception as e:
-        logger.error(f"Background replacement error: {e}")
-        # Simple fallback
-        try:
-            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, 100, 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:
+        logger.error(f"Advanced compositing error: {e}")
+        raise
+
+def _color_match_edges(frame: np.ndarray, background: np.ndarray, alpha: np.ndarray) -> np.ndarray:
+    """Subtle color matching at edges to reduce halos"""
+    try:
+        # Find edge regions (transition areas)
+        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)
+        
+        # Calculate color difference in edge regions
+        edge_areas = edge_mask > 0
+        if not np.any(edge_areas):
             return frame
+        
+        # Subtle color adjustment
+        frame_adjusted = frame.copy().astype(np.float32)
+        background_float = background.astype(np.float32)
+        
+        # Apply very subtle color shift towards background in edge areas
+        adjustment_strength = 0.1
+        for c in range(3):
+            frame_adjusted[:, :, c] = np.where(
+                edge_areas,
+                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
 
-def create_professional_background(bg_config, width, height):
-    """Create professional background based on configuration"""
+def _simple_compositing(frame: np.ndarray, mask: np.ndarray, background: np.ndarray) -> np.ndarray:
+    """Simple fallback compositing method"""
+    try:
+        logger.info("Using simple compositing fallback")
+        
+        # Resize background
+        background = cv2.resize(background, (frame.shape[1], frame.shape[0]))
+        
+        # Process mask
+        if len(mask.shape) == 3:
+            mask = cv2.cvtColor(mask, cv2.COLOR_BGR2GRAY)
+        if mask.max() <= 1.0:
+            mask = (mask * 255).astype(np.uint8)
+        
+        # Simple binary threshold
+        _, mask_binary = cv2.threshold(mask, 127, 255, cv2.THRESH_BINARY)
+        
+        # Create alpha mask
+        mask_norm = mask_binary.astype(np.float32) / 255.0
+        mask_3ch = np.stack([mask_norm] * 3, axis=2)
+        
+        # Simple alpha blending
+        result = frame * mask_3ch + background * (1 - mask_3ch)
+        return result.astype(np.uint8)
+        
+    except Exception as e:
+        logger.error(f"Simple compositing failed: {e}")
+        # Last resort: return original frame
+        return frame
+
+def create_professional_background(bg_config: Dict[str, Any], width: int, height: int) -> np.ndarray:
+    """Enhanced professional background creation with quality improvements"""
     try:
         if bg_config["type"] == "color":
-            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]
-            background = np.full((height, width, 3), color_bgr, dtype=np.uint8)
+            background = _create_solid_background(bg_config, width, height)
         elif bg_config["type"] == "gradient":
-            background = create_gradient_background(bg_config, width, height)
+            background = _create_gradient_background_enhanced(bg_config, width, height)
         else:
+            # Fallback to neutral gray
             background = np.full((height, width, 3), (128, 128, 128), dtype=np.uint8)
+        
+        # Apply brightness and contrast adjustments
+        background = _apply_background_adjustments(background, bg_config)
+        
         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)
 
-def create_gradient_background(bg_config, width, height):
-    """Create high-quality gradient backgrounds"""
+def _create_solid_background(bg_config: Dict[str, Any], width: int, height: int) -> np.ndarray:
+    """Create solid color background"""
+    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"""
     try:
         colors = bg_config["colors"]
         direction = bg_config.get("direction", "vertical")
@@ -290,106 +710,183 @@ def create_gradient_background(bg_config, width, height):
         if not rgb_colors:
             rgb_colors = [(128, 128, 128)]
         
-        # Create PIL image for gradient
-        pil_img = Image.new('RGB', (width, height))
-        draw = ImageDraw.Draw(pil_img)
-        
-        def interpolate_color(colors, progress):
-            if len(colors) == 1:
-                return colors[0]
-            elif len(colors) == 2:
-                r = int(colors[0][0] + (colors[1][0] - colors[0][0]) * progress)
-                g = int(colors[0][1] + (colors[1][1] - colors[0][1]) * progress)
-                b = int(colors[0][2] + (colors[1][2] - colors[0][2]) * progress)
-                return (r, g, b)
-            else:
-                segment = progress * (len(colors) - 1)
-                idx = int(segment)
-                local_progress = segment - idx
-                if idx >= len(colors) - 1:
-                    return colors[-1]
-                c1, c2 = colors[idx], colors[idx + 1]
-                r = int(c1[0] + (c2[0] - c1[0]) * local_progress)
-                g = int(c1[1] + (c2[1] - c1[1]) * local_progress)
-                b = int(c1[2] + (c2[2] - c1[2]) * local_progress)
-                return (r, g, b)
-        
-        # Generate gradient based on direction
+        # Use NumPy for better performance on large images
         if direction == "vertical":
-            for y in range(height):
-                progress = y / height if height > 0 else 0
-                color = interpolate_color(rgb_colors, progress)
-                draw.line([(0, y), (width, y)], fill=color)
+            background = _create_vertical_gradient(rgb_colors, width, height)
         elif direction == "horizontal":
-            for x in range(width):
-                progress = x / width if width > 0 else 0
-                color = interpolate_color(rgb_colors, progress)
-                draw.line([(x, 0), (x, height)], fill=color)
+            background = _create_horizontal_gradient(rgb_colors, width, height)
         elif direction == "diagonal":
-            max_distance = width + height
-            for y in range(height):
-                for x in range(width):
-                    progress = (x + y) / max_distance if max_distance > 0 else 0
-                    progress = min(1.0, progress)
-                    color = interpolate_color(rgb_colors, progress)
-                    pil_img.putpixel((x, y), color)
+            background = _create_diagonal_gradient(rgb_colors, width, height)
         elif direction in ["radial", "soft_radial"]:
-            center_x, center_y = width // 2, height // 2
-            max_distance = np.sqrt(center_x**2 + center_y**2)
-            for y in range(height):
-                for x in range(width):
-                    distance = np.sqrt((x - center_x)**2 + (y - center_y)**2)
-                    progress = distance / max_distance if max_distance > 0 else 0
-                    progress = min(1.0, progress)
-                    if direction == "soft_radial":
-                        progress = progress**0.7
-                    color = interpolate_color(rgb_colors, progress)
-                    pil_img.putpixel((x, y), color)
-        
-        # Convert to OpenCV format
-        background = cv2.cvtColor(np.array(pil_img), cv2.COLOR_RGB2BGR)
-        return background
+            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}")
-        background = np.full((height, width, 3), (128, 128, 128), dtype=np.uint8)
-        return background
+        return np.full((height, width, 3), (128, 128, 128), dtype=np.uint8)
 
-def create_procedural_background(prompt, style, width, height):
-    """Create procedural background based on text prompt"""
-    # Simplified version - full implementation would be too long
-    color_map = {
-        'blue': ['#1e3c72', '#2a5298', '#3498db'],
-        'green': ['#27ae60', '#2ecc71', '#58d68d'],
-        'red': ['#e74c3c', '#c0392b', '#ff7675'],
-        'purple': ['#6c5ce7', '#a29bfe', '#fd79a8'],
-    }
+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)
     
-    selected_colors = ['#3498db', '#2ecc71', '#e74c3c']  # Default
-    for keyword, colors in color_map.items():
-        if keyword in prompt.lower():
-            selected_colors = colors
-            break
+    for y in range(height):
+        progress = y / height if height > 0 else 0
+        color = _interpolate_color(colors, progress)
+        gradient[y, :] = color
     
-    bg_config = {
-        "type": "gradient",
-        "colors": selected_colors[:2],
-        "direction": "diagonal"
-    }
-    return create_gradient_background(bg_config, width, height)
+    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
+        color = _interpolate_color(colors, progress)
+        gradient[:, x] = color
+    
+    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)
+    
+    # Vectorized color interpolation
+    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]
+    distances = np.sqrt((x_coords - center_x)**2 + (y_coords - center_y)**2)
+    progress = distances / max_distance
+    progress = np.clip(progress, 0, 1)
+    
+    if soft:
+        progress = np.power(progress, 0.7)
+    
+    # Vectorized color interpolation
+    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 validate_video_file(video_path):
-    """Validate video file format and basic properties"""
+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
+    
+    # Get start and end colors for each pixel
+    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:
+        r = int(colors[0][0] + (colors[1][0] - colors[0][0]) * progress)
+        g = int(colors[0][1] + (colors[1][1] - colors[0][1]) * progress)
+        b = int(colors[0][2] + (colors[1][2] - colors[0][2]) * progress)
+        return (r, g, b)
+    else:
+        segment = progress * (len(colors) - 1)
+        idx = int(segment)
+        local_progress = segment - idx
+        if idx >= len(colors) - 1:
+            return colors[-1]
+        c1, c2 = colors[idx], colors[idx + 1]
+        r = int(c1[0] + (c2[0] - c1[0]) * local_progress)
+        g = int(c1[1] + (c2[1] - c1[1]) * local_progress)
+        b = int(c1[2] + (c2[2] - c1[2]) * local_progress)
+        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
+
+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:
+        # Check file size
+        file_size = os.path.getsize(video_path)
+        if file_size == 0:
+            return False, "Video file is empty"
+        
+        if file_size > 2 * 1024 * 1024 * 1024:  # 2GB limit
+            return False, "Video file too large (>2GB)"
+        
+        # Check with OpenCV
         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))
-        if frame_count == 0:
-            return False, "Video appears to be empty"
+        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()
-        return True, "Video file valid"
+        
+        # Validation checks
+        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:  # 5 minutes
+            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)}"