utilities.py

#!/usr/bin/env python3
"""
Enhanced utilities.py - Core computer vision functions with improved error handling
Fixed transparency issues, added fallback strategies, and enhanced memory management
"""

import os
import cv2
import numpy as np
import torch
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 with enhanced configurations
PROFESSIONAL_BACKGROUNDS = {
    "office_modern": {
        "name": "Modern Office",
        "type": "gradient", 
        "colors": ["#f8f9fa", "#e9ecef", "#dee2e6"],
        "direction": "diagonal",
        "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",
        "brightness": 0.9,
        "contrast": 1.2
    },
    "studio_green": {
        "name": "Broadcast Green",
        "type": "color",
        "colors": ["#00b894"],
        "chroma_key": True,
        "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",
        "brightness": 0.98,
        "contrast": 0.9
    },
    "warm_gradient": {
        "name": "Warm Sunset",
        "type": "gradient",
        "colors": ["#ff7675", "#fd79a8", "#fdcb6e"],
        "direction": "diagonal",
        "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",
        "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
    }
}

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:
        # 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]
        
        # Enhanced strategic point placement for better person detection
        points = np.array([
            [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:
            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)
        
        # 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)
        
        # 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)
        
        # Ensure binary threshold
        _, mask = cv2.threshold(mask, 127, 255, cv2.THRESH_BINARY)
        
        return mask
        
    except Exception as e:
        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]
        
        # 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: 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 in correct format
        mask = _process_mask(mask)
        
        # Try MatAnyone if available
        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}")
        
        # 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 - Python 3.10 compatible"""
    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
        
        # Process the refined mask
        refined_mask = _process_mask(refined_mask)
        
        logger.debug("MatAnyone refinement successful")
        return refined_mask
        
    except Exception as e:
        logger.warning(f"MatAnyone processing error: {e}")
        return None

def _background_matting_v2_refine(image: np.ndarray, mask: np.ndarray) -> Optional[np.ndarray]:
    """Use BackgroundMattingV2 for mask refinement"""
    try:
        # Import BackgroundMattingV2 if available
        from inference_images import inference_img
        import torch
        
        # Convert inputs to proper format
        image_tensor = torch.from_numpy(image).permute(2, 0, 1).float() / 255.0
        mask_tensor = torch.from_numpy(mask).float() / 255.0
        
        # Create trimap from mask
        trimap = _create_trimap_from_mask(mask)
        trimap_tensor = torch.from_numpy(trimap).float()
        
        # Run inference
        device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
        
        with torch.no_grad():
            alpha = inference_img(
                image_tensor.unsqueeze(0).to(device),
                trimap_tensor.unsqueeze(0).unsqueeze(0).to(device)
            )
        
        # Convert back to numpy
        refined_mask = alpha.cpu().squeeze().numpy()
        refined_mask = (refined_mask * 255).astype(np.uint8)
        
        logger.info("BackgroundMattingV2 refinement successful")
        return refined_mask
        
    except ImportError:
        logger.warning("BackgroundMattingV2 not available")
        return None
    except Exception as e:
        logger.warning(f"BackgroundMattingV2 error: {e}")
        return None

def _rembg_refine(image: np.ndarray, mask: np.ndarray) -> Optional[np.ndarray]:
    """Use rembg for mask refinement"""
    try:
        from rembg import remove, new_session
        
        # Use rembg to get a high-quality mask
        session = new_session('u2net')
        
        # Convert image to PIL
        from PIL import Image
        pil_image = Image.fromarray(cv2.cvtColor(image, cv2.COLOR_BGR2RGB))
        
        # Remove background
        output = remove(pil_image, session=session)
        
        # Extract alpha channel as mask
        if output.mode == 'RGBA':
            alpha = np.array(output)[:, :, 3]
        else:
            # Fallback: convert to grayscale
            alpha = np.array(output.convert('L'))
        
        # Combine with original mask using weighted average
        original_mask_norm = mask.astype(np.float32) / 255.0
        rembg_mask_norm = alpha.astype(np.float32) / 255.0
        
        # Weighted combination: 70% rembg, 30% original
        combined = 0.7 * rembg_mask_norm + 0.3 * original_mask_norm
        combined = np.clip(combined * 255, 0, 255).astype(np.uint8)
        
        logger.info("Rembg refinement successful")
        return combined
        
    except ImportError:
        logger.warning("Rembg not available")
        return None
    except Exception as e:
        logger.warning(f"Rembg error: {e}")
        return None

def _create_trimap_from_mask(mask: np.ndarray, erode_size: int = 10, dilate_size: int = 20) -> np.ndarray:
    """Create trimap from binary mask for BackgroundMattingV2"""
    try:
        # Ensure mask is binary
        _, binary_mask = cv2.threshold(mask, 127, 255, cv2.THRESH_BINARY)
        
        # Create trimap: 0 = background, 128 = unknown, 255 = foreground
        trimap = np.zeros_like(mask, dtype=np.uint8)
        
        # Erode mask to get sure foreground
        kernel_erode = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (erode_size, erode_size))
        sure_fg = cv2.erode(binary_mask, kernel_erode, iterations=1)
        
        # Dilate mask to get unknown region
        kernel_dilate = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (dilate_size, dilate_size))
        unknown_region = cv2.dilate(binary_mask, kernel_dilate, iterations=1)
        
        # Set trimap values
        trimap[sure_fg == 255] = 255  # Sure foreground
        trimap[(unknown_region == 255) & (sure_fg == 0)] = 128  # Unknown
        # Background remains 0
        
        return trimap
        
    except Exception as e:
        logger.warning(f"Trimap creation failed: {e}")
        # Return simple trimap based on original mask
        trimap = np.where(mask > 127, 255, 0).astype(np.uint8)
        return trimap

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 proper range
        if mask.max() <= 1.0:
            mask = (mask * 255).astype(np.uint8)
        
        # Multi-stage refinement
        
        # 1. Bilateral filtering for edge preservation
        refined_mask = cv2.bilateralFilter(mask, 9, 75, 75)
        
        # 2. Edge-aware smoothing using guided filter approximation
        refined_mask = _guided_filter_approx(image, refined_mask, radius=8, eps=0.2)
        
        # 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)
        
        # 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 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

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)
        
        # Process mask
        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)
        
        # 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}")
        
    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
        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)
        
        # 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
        
        # Apply gamma correction for better blending
        mask_smooth = np.power(mask_smooth, 0.8)
        
        # 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),
                              mask_smooth * 0.9)
        
        # Color matching between foreground and background
        frame_adjusted = _color_match_edges(frame, background, mask_smooth)
        
        # Create 3-channel alpha mask
        alpha_3ch = np.stack([mask_smooth] * 3, axis=2)
        
        # Perform high-quality compositing
        frame_float = frame_adjusted.astype(np.float32)
        background_float = background.astype(np.float32)
        
        # Alpha blending with gamma correction
        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

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 _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":
            background = _create_solid_background(bg_config, width, height)
        elif bg_config["type"] == "gradient":
            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_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")
        
        # Convert hex to RGB
        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)]
        
        # Use NumPy for better performance on large images
        if direction == "vertical":
            background = _create_vertical_gradient(rgb_colors, width, height)
        elif direction == "horizontal":
            background = _create_horizontal_gradient(rgb_colors, width, height)
        elif direction == "diagonal":
            background = _create_diagonal_gradient(rgb_colors, width, height)
        elif direction in ["radial", "soft_radial"]:
            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
        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 _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))
        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()
        
        # 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)}"