Update utils/utils.py

utils/utils.py

@@ -1,9 +1,9 @@
 """
-Utility classes for BackgroundFX Pro
-Includes FileManager, VideoUtils, and ImageUtils
+Unified Utilities Module for BackgroundFX Pro
+Combines FileManager, VideoUtils, ImageUtils, and CV utilities
 """
 
-# Set OMP_NUM_THREADS at the very beginning of utils module too
+# Set OMP_NUM_THREADS at the very beginning to prevent libgomp errors
 import os
 if 'OMP_NUM_THREADS' not in os.environ:
     os.environ['OMP_NUM_THREADS'] = '4'
@@ -16,29 +16,113 @@
 from typing import Optional, List, Union, Tuple, Dict, Any
 from datetime import datetime
 import subprocess
+import time
+
 import cv2
 import numpy as np
-from PIL import Image, ImageEnhance, ImageFilter
+import torch
+from PIL import Image, ImageEnhance, ImageFilter, ImageDraw
 
 logger = logging.getLogger(__name__)
 
+# ============================================================================
+# CONFIGURATION AND CONSTANTS
+# ============================================================================
+
+# Version control flags for CV functions
+USE_ENHANCED_SEGMENTATION = True
+USE_AUTO_TEMPORAL_CONSISTENCY = True
+USE_INTELLIGENT_PROMPTING = True
+USE_ITERATIVE_REFINEMENT = True
+
+# Professional background templates
+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
+    }
+}
+
+# ============================================================================
+# CUSTOM EXCEPTIONS
+# ============================================================================
+
+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
+
+# ============================================================================
+# FILE MANAGER CLASS
+# ============================================================================
 
 class FileManager:
     """Manages file operations for BackgroundFX Pro"""
     
     def __init__(self, base_dir: Optional[str] = None):
-        """
-        Initialize FileManager
-        
-        Args:
-            base_dir: Base directory for file operations (defaults to temp dir)
-        """
+        """Initialize FileManager"""
         if base_dir:
             self.base_dir = Path(base_dir)
         else:
             self.base_dir = Path(tempfile.gettempdir()) / "backgroundfx_pro"
         
-        # Create base directory if it doesn't exist
         self.base_dir.mkdir(parents=True, exist_ok=True)
         
         # Create subdirectories
@@ -53,49 +137,27 @@ def __init__(self, base_dir: Optional[str] = None):
         logger.info(f"FileManager initialized with base directory: {self.base_dir}")
     
     def save_upload(self, file_path: Union[str, Path], filename: Optional[str] = None) -> Path:
-        """
-        Save an uploaded file to the uploads directory
-        
-        Args:
-            file_path: Path to the uploaded file
-            filename: Optional custom filename
-            
-        Returns:
-            Path to the saved file
-        """
+        """Save an uploaded file to the uploads directory"""
         file_path = Path(file_path)
         
         if filename:
             dest_path = self.uploads_dir / filename
         else:
-            # Generate unique filename with timestamp
             timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
             dest_path = self.uploads_dir / f"{timestamp}_{file_path.name}"
         
-        # Copy file to uploads directory
         shutil.copy2(file_path, dest_path)
         logger.info(f"Saved upload: {dest_path}")
-        
         return dest_path
     
     def create_output_path(self, filename: str, subfolder: Optional[str] = None) -> Path:
-        """
-        Create a path for an output file
-        
-        Args:
-            filename: Name of the output file
-            subfolder: Optional subfolder within outputs
-            
-        Returns:
-            Path for the output file
-        """
+        """Create a path for an output file"""
         if subfolder:
             output_dir = self.outputs_dir / subfolder
             output_dir.mkdir(parents=True, exist_ok=True)
         else:
             output_dir = self.outputs_dir
         
-        # Add timestamp to filename
         timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
         name_parts = filename.rsplit('.', 1)
         if len(name_parts) == 2:
@@ -106,16 +168,7 @@ def create_output_path(self, filename: str, subfolder: Optional[str] = None) ->
         return output_path
     
     def get_temp_path(self, filename: Optional[str] = None, extension: str = ".tmp") -> Path:
-        """
-        Get a temporary file path
-        
-        Args:
-            filename: Optional filename (will be made unique)
-            extension: File extension
-            
-        Returns:
-            Path for temporary file
-        """
+        """Get a temporary file path"""
         if filename:
             temp_path = self.temp_dir / filename
         else:
@@ -125,12 +178,7 @@ def get_temp_path(self, filename: Optional[str] = None, extension: str = ".tmp")
         return temp_path
     
     def cleanup_temp(self, max_age_hours: int = 24):
-        """
-        Clean up old temporary files
-        
-        Args:
-            max_age_hours: Maximum age of temp files in hours
-        """
+        """Clean up old temporary files"""
         try:
             current_time = datetime.now().timestamp()
             max_age_seconds = max_age_hours * 3600
@@ -147,31 +195,12 @@ def cleanup_temp(self, max_age_hours: int = 24):
             logger.warning(f"Error during temp cleanup: {e}")
     
     def get_cache_path(self, key: str, extension: str = ".cache") -> Path:
-        """
-        Get a cache file path based on a key
-        
-        Args:
-            key: Cache key
-            extension: File extension
-            
-        Returns:
-            Path for cache file
-        """
-        # Create a safe filename from the key
+        """Get a cache file path based on a key"""
         safe_key = "".join(c if c.isalnum() or c in '-_' else '_' for c in key)
         return self.cache_dir / f"{safe_key}{extension}"
     
     def list_outputs(self, subfolder: Optional[str] = None, extension: Optional[str] = None) -> List[Path]:
-        """
-        List output files
-        
-        Args:
-            subfolder: Optional subfolder to list from
-            extension: Optional file extension filter
-            
-        Returns:
-            List of output file paths
-        """
+        """List output files"""
         if subfolder:
             search_dir = self.outputs_dir / subfolder
         else:
@@ -188,15 +217,7 @@ def list_outputs(self, subfolder: Optional[str] = None, extension: Optional[str]
         return sorted(search_dir.glob(pattern), key=lambda p: p.stat().st_mtime, reverse=True)
     
     def delete_file(self, file_path: Union[str, Path]) -> bool:
-        """
-        Safely delete a file
-        
-        Args:
-            file_path: Path to file to delete
-            
-        Returns:
-            True if successful, False otherwise
-        """
+        """Safely delete a file"""
         try:
             file_path = Path(file_path)
             if file_path.exists() and file_path.is_file():
@@ -209,15 +230,7 @@ def delete_file(self, file_path: Union[str, Path]) -> bool:
             return False
     
     def get_file_info(self, file_path: Union[str, Path]) -> dict:
-        """
-        Get information about a file
-        
-        Args:
-            file_path: Path to file
-            
-        Returns:
-            Dictionary with file information
-        """
+        """Get information about a file"""
         file_path = Path(file_path)
         
         if not file_path.exists():
@@ -235,21 +248,16 @@ def get_file_info(self, file_path: Union[str, Path]) -> dict:
             "path": str(file_path.absolute())
         }
 
+# ============================================================================
+# VIDEO UTILS CLASS
+# ============================================================================
 
 class VideoUtils:
     """Utilities for video processing"""
     
     @staticmethod
     def get_video_info(video_path: Union[str, Path]) -> Dict[str, Any]:
-        """
-        Get detailed video information
-        
-        Args:
-            video_path: Path to video file
-            
-        Returns:
-            Dictionary with video metadata
-        """
+        """Get detailed video information"""
         video_path = str(video_path)
         cap = cv2.VideoCapture(video_path)
         
@@ -267,7 +275,6 @@ def get_video_info(video_path: Union[str, Path]) -> Dict[str, Any]:
                 "duration": cap.get(cv2.CAP_PROP_FRAME_COUNT) / cap.get(cv2.CAP_PROP_FPS) if cap.get(cv2.CAP_PROP_FPS) > 0 else 0
             }
             
-            # Get file size
             path = Path(video_path)
             if path.exists():
                 info["file_size_mb"] = path.stat().st_size / (1024 * 1024)
@@ -287,18 +294,7 @@ def extract_frames(video_path: Union[str, Path],
                       output_dir: Union[str, Path],
                       frame_interval: int = 1,
                       max_frames: Optional[int] = None) -> List[Path]:
-        """
-        Extract frames from video
-        
-        Args:
-            video_path: Path to video file
-            output_dir: Directory to save frames
-            frame_interval: Extract every nth frame
-            max_frames: Maximum number of frames to extract
-            
-        Returns:
-            List of extracted frame paths
-        """
+        """Extract frames from video"""
         video_path = str(video_path)
         output_dir = Path(output_dir)
         output_dir.mkdir(parents=True, exist_ok=True)
@@ -340,23 +336,11 @@ def create_video_from_frames(frame_paths: List[Union[str, Path]],
                                 output_path: Union[str, Path],
                                 fps: float = 30.0,
                                 codec: str = 'mp4v') -> bool:
-        """
-        Create video from frame images
-        
-        Args:
-            frame_paths: List of frame image paths
-            output_path: Output video path
-            fps: Frames per second
-            codec: Video codec (fourcc)
-            
-        Returns:
-            True if successful
-        """
+        """Create video from frame images"""
         if not frame_paths:
             logger.error("No frames provided")
             return False
         
-        # Read first frame to get dimensions
         first_frame = cv2.imread(str(frame_paths[0]))
         if first_frame is None:
             logger.error(f"Failed to read first frame: {frame_paths[0]}")
@@ -364,7 +348,6 @@ def create_video_from_frames(frame_paths: List[Union[str, Path]],
         
         height, width, layers = first_frame.shape
         
-        # Create video writer
         fourcc = cv2.VideoWriter_fourcc(*codec)
         out = cv2.VideoWriter(str(output_path), fourcc, fps, (width, height))
         
@@ -392,31 +375,17 @@ def resize_video(input_path: Union[str, Path],
                     target_width: Optional[int] = None,
                     target_height: Optional[int] = None,
                     maintain_aspect: bool = True) -> bool:
-        """
-        Resize video to target dimensions
-        
-        Args:
-            input_path: Input video path
-            output_path: Output video path
-            target_width: Target width (None to auto-calculate)
-            target_height: Target height (None to auto-calculate)
-            maintain_aspect: Maintain aspect ratio
-            
-        Returns:
-            True if successful
-        """
+        """Resize video to target dimensions"""
         cap = cv2.VideoCapture(str(input_path))
         if not cap.isOpened():
             logger.error(f"Failed to open video: {input_path}")
             return False
         
-        # Get original dimensions
         orig_width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
         orig_height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
         fps = cap.get(cv2.CAP_PROP_FPS)
         fourcc = int(cap.get(cv2.CAP_PROP_FOURCC))
         
-        # Calculate target dimensions
         if maintain_aspect:
             if target_width and not target_height:
                 aspect = orig_width / orig_height
@@ -430,7 +399,6 @@ def resize_video(input_path: Union[str, Path],
         if not target_height:
             target_height = orig_height
         
-        # Create video writer
         out = cv2.VideoWriter(str(output_path), fourcc, fps, (target_width, target_height))
         
         try:
@@ -456,16 +424,7 @@ def resize_video(input_path: Union[str, Path],
     @staticmethod
     def extract_audio(video_path: Union[str, Path], 
                      audio_path: Union[str, Path]) -> bool:
-        """
-        Extract audio from video using ffmpeg
-        
-        Args:
-            video_path: Input video path
-            audio_path: Output audio path
-            
-        Returns:
-            True if successful
-        """
+        """Extract audio from video using ffmpeg"""
         try:
             cmd = [
                 'ffmpeg', '-i', str(video_path),
@@ -493,17 +452,7 @@ def extract_audio(video_path: Union[str, Path],
     def add_audio_to_video(video_path: Union[str, Path],
                           audio_path: Union[str, Path],
                           output_path: Union[str, Path]) -> bool:
-        """
-        Add audio track to video using ffmpeg
-        
-        Args:
-            video_path: Input video path
-            audio_path: Input audio path
-            output_path: Output video path with audio
-            
-        Returns:
-            True if successful
-        """
+        """Add audio track to video using ffmpeg"""
         try:
             cmd = [
                 'ffmpeg', '-i', str(video_path),
@@ -528,57 +477,1006 @@ def add_audio_to_video(video_path: Union[str, Path],
         except Exception as e:
             logger.error(f"Error adding audio: {e}")
             return False
+
+# ============================================================================
+# IMAGE UTILS CLASS
+# ============================================================================
+
+class ImageUtils:
+    """Utilities for image processing and manipulation"""
     
     @staticmethod
-    def get_frame_at_time(video_path: Union[str, Path], 
-                         time_seconds: float) -> Optional[np.ndarray]:
-        """
-        Get frame at specific time in video
-        
-        Args:
-            video_path: Path to video
-            time_seconds: Time in seconds
-            
-        Returns:
-            Frame as numpy array or None
-        """
-        cap = cv2.VideoCapture(str(video_path))
-        if not cap.isOpened():
-            logger.error(f"Failed to open video: {video_path}")
+    def load_image(image_path: Union[str, Path]) -> Optional[Image.Image]:
+        """Load an image using PIL"""
+        try:
+            return Image.open(str(image_path))
+        except Exception as e:
+            logger.error(f"Failed to load image {image_path}: {e}")
             return None
+    
+    @staticmethod
+    def resize_image(image: Image.Image, 
+                    max_width: Optional[int] = None,
+                    max_height: Optional[int] = None,
+                    maintain_aspect: bool = True) -> Image.Image:
+        """Resize image to fit within max dimensions"""
+        if not max_width and not max_height:
+            return image
+        
+        width, height = image.size
+        
+        if maintain_aspect:
+            scale = 1.0
+            if max_width:
+                scale = min(scale, max_width / width)
+            if max_height:
+                scale = min(scale, max_height / height)
+            
+            new_width = int(width * scale)
+            new_height = int(height * scale)
+        else:
+            new_width = max_width or width
+            new_height = max_height or height
+        
+        return image.resize((new_width, new_height), Image.Resampling.LANCZOS)
+    
+    @staticmethod
+    def convert_to_cv2(pil_image: Image.Image) -> np.ndarray:
+        """Convert PIL Image to OpenCV format"""
+        if pil_image.mode != 'RGB':
+            pil_image = pil_image.convert('RGB')
+        
+        np_image = np.array(pil_image)
+        return cv2.cvtColor(np_image, cv2.COLOR_RGB2BGR)
+    
+    @staticmethod
+    def convert_from_cv2(cv2_image: np.ndarray) -> Image.Image:
+        """Convert OpenCV image to PIL format"""
+        rgb_image = cv2.cvtColor(cv2_image, cv2.COLOR_BGR2RGB)
+        return Image.fromarray(rgb_image)
+    
+    @staticmethod
+    def apply_blur(image: Image.Image, radius: float = 5.0) -> Image.Image:
+        """Apply Gaussian blur to image"""
+        return image.filter(ImageFilter.GaussianBlur(radius=radius))
+    
+    @staticmethod
+    def adjust_brightness(image: Image.Image, factor: float = 1.0) -> Image.Image:
+        """Adjust image brightness"""
+        enhancer = ImageEnhance.Brightness(image)
+        return enhancer.enhance(factor)
+    
+    @staticmethod
+    def adjust_contrast(image: Image.Image, factor: float = 1.0) -> Image.Image:
+        """Adjust image contrast"""
+        enhancer = ImageEnhance.Contrast(image)
+        return enhancer.enhance(factor)
+    
+    @staticmethod
+    def adjust_saturation(image: Image.Image, factor: float = 1.0) -> Image.Image:
+        """Adjust image saturation"""
+        enhancer = ImageEnhance.Color(image)
+        return enhancer.enhance(factor)
+    
+    @staticmethod
+    def crop_center(image: Image.Image, crop_width: int, crop_height: int) -> Image.Image:
+        """Crop image from center"""
+        width, height = image.size
+        
+        left = (width - crop_width) // 2
+        top = (height - crop_height) // 2
+        right = left + crop_width
+        bottom = top + crop_height
+        
+        return image.crop((left, top, right, bottom))
+    
+    @staticmethod
+    def create_thumbnail(image: Image.Image, size: Tuple[int, int] = (128, 128)) -> Image.Image:
+        """Create thumbnail preserving aspect ratio"""
+        img_copy = image.copy()
+        img_copy.thumbnail(size, Image.Resampling.LANCZOS)
+        return img_copy
+    
+    @staticmethod
+    def apply_mask(image: Image.Image, mask: Image.Image, alpha: float = 1.0) -> Image.Image:
+        """Apply mask to image"""
+        if image.mode != 'RGBA':
+            image = image.convert('RGBA')
+        
+        if mask.mode != 'L':
+            mask = mask.convert('L')
         
+        if mask.size != image.size:
+            mask = mask.resize(image.size, Image.Resampling.LANCZOS)
+        
+        if alpha < 1.0:
+            mask = ImageEnhance.Brightness(mask).enhance(alpha)
+        
+        image.putalpha(mask)
+        return image
+    
+    @staticmethod
+    def composite_images(foreground: Image.Image, 
+                        background: Image.Image,
+                        position: Tuple[int, int] = (0, 0),
+                        alpha: float = 1.0) -> Image.Image:
+        """Composite foreground image over background"""
+        if foreground.mode != 'RGBA':
+            foreground = foreground.convert('RGBA')
+        if background.mode != 'RGBA':
+            background = background.convert('RGBA')
+        
+        if alpha < 1.0:
+            foreground = foreground.copy()
+            foreground.putalpha(
+                ImageEnhance.Brightness(foreground.split()[3]).enhance(alpha)
+            )
+        
+        output = background.copy()
+        output.paste(foreground, position, foreground)
+        
+        return output
+    
+    @staticmethod
+    def get_image_info(image_path: Union[str, Path]) -> Dict[str, Any]:
+        """Get image file information"""
         try:
-            fps = cap.get(cv2.CAP_PROP_FPS)
-            frame_number = int(fps * time_seconds)
+            image_path = Path(image_path)
             
-            cap.set(cv2.CAP_PROP_POS_FRAMES, frame_number)
-            ret, frame = cap.read()
+            if not image_path.exists():
+                return {"exists": False}
             
-            if ret:
-                return frame
+            with Image.open(str(image_path)) as img:
+                info = {
+                    "exists": True,
+                    "filename": image_path.name,
+                    "format": img.format,
+                    "mode": img.mode,
+                    "size": img.size,
+                    "width": img.width,
+                    "height": img.height,
+                    "file_size_mb": image_path.stat().st_size / (1024 * 1024)
+                }
+                
+                if hasattr(img, '_getexif') and img._getexif():
+                    info["has_exif"] = True
+                else:
+                    info["has_exif"] = False
+                
+                return info
+                
+        except Exception as e:
+            logger.error(f"Error getting image info for {image_path}: {e}")
+            return {"exists": False, "error": str(e)}
+    
+    @staticmethod
+    def save_image(image: Image.Image, 
+                  output_path: Union[str, Path],
+                  quality: int = 95,
+                  optimize: bool = True) -> bool:
+        """Save image with specified quality"""
+        try:
+            output_path = Path(output_path)
+            output_path.parent.mkdir(parents=True, exist_ok=True)
+            
+            save_kwargs = {}
+            ext = output_path.suffix.lower()
+            
+            if ext in ['.jpg', '.jpeg']:
+                save_kwargs['quality'] = quality
+                save_kwargs['optimize'] = optimize
+            elif ext == '.png':
+                save_kwargs['optimize'] = optimize
+            
+            image.save(str(output_path), **save_kwargs)
+            logger.info(f"Saved image to: {output_path}")
+            return True
+            
+        except Exception as e:
+            logger.error(f"Failed to save image to {output_path}: {e}")
+            return False
+
+# ============================================================================
+# COMPUTER VISION FUNCTIONS (from utilities.py)
+# ============================================================================
+
+def segment_person_hq(image: np.ndarray, predictor: Any, fallback_enabled: bool = True) -> np.ndarray:
+    """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:
+        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")
+        
+        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}")
+        
+        if USE_INTELLIGENT_PROMPTING:
+            mask = _segment_with_intelligent_prompts(image, predictor)
+        else:
+            mask = _segment_with_basic_prompts(image, predictor)
+        
+        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:
-                logger.warning(f"Could not read frame at time {time_seconds}s")
-                return None
+                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}")
+
+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:
+        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")
+        
+        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]
+        
+        points = np.array([
+            [w//2, h//4],
+            [w//2, h//2],
+            [w//2, 3*h//4],
+            [w//3, h//2],
+            [2*w//3, h//2],
+            [w//2, h//6],
+            [w//4, 2*h//3],
+            [3*w//4, 2*h//3],
+        ], dtype=np.float32)
+        
+        labels = np.ones(len(points), dtype=np.int32)
+        
+        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}")
+        
+        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:
+            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")
+        
+        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 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)
                 
-        finally:
-            cap.release()
+                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")
+            
+    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 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)
 
+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"""
+    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)
+        
+        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}")
+        
+    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 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:
+            background = np.full((height, width, 3), (128, 128, 128), dtype=np.uint8)
+        
+        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 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)}"
 
-# Create default instances for convenience
-_default_file_manager = None
+# ============================================================================
+# HELPER FUNCTIONS (from utilities.py)
+# ============================================================================
 
+def _segment_with_intelligent_prompts(image: np.ndarray, predictor: Any) -> np.ndarray:
+    """Intelligent automatic prompt generation for segmentation"""
+    try:
+        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}")
+        raise
 
-def get_file_manager(base_dir: Optional[str] = None) -> FileManager:
-    """
-    Get or create the default FileManager instance
+def _segment_with_basic_prompts(image: np.ndarray, predictor: Any) -> np.ndarray:
+    """Basic prompting method for segmentation"""
+    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]
     
-    Args:
-        base_dir: Optional base directory
+    return _process_mask(best_mask)
+
+def _generate_smart_prompts(image: np.ndarray) -> Tuple[np.ndarray, np.ndarray]:
+    """Generate optimal positive/negative points automatically"""
+    try:
+        h, w = image.shape[:2]
+        
+        try:
+            saliency = cv2.saliency.StaticSaliencySpectralResidual_create()
+            success, saliency_map = saliency.computeSaliency(image)
+            
+            if success:
+                saliency_thresh = cv2.threshold(saliency_map, 0.7, 1, cv2.THRESH_BINARY)[1]
+                contours, _ = cv2.findContours((saliency_thresh * 255).astype(np.uint8), 
+                                               cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+                
+                positive_points = []
+                if contours:
+                    for contour in sorted(contours, key=cv2.contourArea, reverse=True)[:3]:
+                        M = cv2.moments(contour)
+                        if M["m00"] != 0:
+                            cx = int(M["m10"] / M["m00"])
+                            cy = int(M["m01"] / M["m00"])
+                            if 0 < cx < w and 0 < cy < h:
+                                positive_points.append([cx, cy])
+                
+                if positive_points:
+                    logger.debug(f"Generated {len(positive_points)} saliency-based points")
+                    positive_points = np.array(positive_points, dtype=np.float32)
+                else:
+                    raise Exception("No valid saliency points found")
+                    
+        except Exception as e:
+            logger.debug(f"Saliency method failed: {e}, using fallback")
+            positive_points = np.array([
+                [w//2, h//3],
+                [w//2, h//2],
+                [w//2, 2*h//3],
+            ], dtype=np.float32)
         
-    Returns:
-        FileManager instance
-    """
-    global _default_file_manager
-    if _default_file_manager is None or base_dir is not None:
-        _default_file_manager = FileManager(base_dir)
-    return _default_file_manager
+        negative_points = np.array([
+            [10, 10],
+            [w-10, 10],
+            [10, h-10],
+            [w-10, h-10],
+            [w//2, 5],
+            [w//2, h-5],
+        ], dtype=np.float32)
+        
+        return positive_points, negative_points
+        
+    except Exception as e:
+        logger.warning(f"Smart prompt generation failed: {e}")
+        h, w = image.shape[:2]
+        positive_points = np.array([[w//2, h//2]], dtype=np.float32)
+        negative_points = np.array([[10, 10], [w-10, 10]], dtype=np.float32)
+        return positive_points, negative_points
+
+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"""
+    try:
+        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():
+                            masks, scores, _ = predictor.predict(
+                                point_coords=corrective_points,
+                                point_labels=corrective_labels,
+                                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
+
+def _assess_mask_quality(mask: np.ndarray, image: np.ndarray) -> float:
+    """Assess mask quality automatically"""
+    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:
+            area_score = area_ratio / 0.05
+        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
+
+def _find_mask_errors(mask: np.ndarray, image: np.ndarray) -> np.ndarray:
+    """Identify problematic areas in mask"""
+    try:
+        gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
+        edges = cv2.Canny(gray, 50, 150)
+        mask_edges = cv2.Canny(mask, 50, 150)
+        edge_discrepancy = cv2.bitwise_xor(edges, mask_edges)
+        kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (5, 5))
+        error_regions = cv2.dilate(edge_discrepancy, kernel, iterations=1)
+        return error_regions > 0
+    except Exception as e:
+        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]:
+    """Generate corrective prompts based on problem areas"""
+    try:
+        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)
+
+def _process_mask(mask: np.ndarray) -> np.ndarray:
+    """Process raw mask to ensure correct format and range"""
+    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:
+            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)
+        
+        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)
+        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
+        
+        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
+        
+        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)
+        
+        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
+
+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:
+            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]
+        mask = np.zeros((h, w), dtype=np.uint8)
+        mask[h//6:5*h//6, w//4:3*w//4] = 255
+        return mask
+
+def _matanyone_refine(image: np.ndarray, mask: np.ndarray, processor: Any) -> Optional[np.ndarray]:
+    """Attempt MatAnyone mask refinement"""
+    try:
+        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
+        
+        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 _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
+        
+        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
+
+def _advanced_compositing(frame: np.ndarray, mask: np.ndarray, background: np.ndarray) -> np.ndarray:
+    """Advanced compositing with edge feathering and color correction"""
+    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)
+        
+        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
+
+def _color_match_edges(frame: np.ndarray, background: np.ndarray, alpha: np.ndarray) -> np.ndarray:
+    """