Upload 10 files

app.py

@@ -0,0 +1,82 @@
+import sys
+import warnings
+warnings.filterwarnings("ignore")
+
+from ui_manager import UIManager
+
+def launch_final_blend_sceneweaver(share: bool = True, debug: bool = False):
+    """Launch SceneWeaver Application"""
+
+    print("🎨 Starting SceneWeaver...")
+    print("✨ AI-Powered Image Background Generation")
+
+    try:
+        # Test imports first
+        print("🔍 Testing imports...")
+        try:
+            # Test creating UIManager
+            print("🔍 Creating UIManager instance...")
+            ui = UIManager()
+            print("✅ UIManager instance created successfully")
+
+            # Launch UI
+            print("🚀 Launching interface...")
+            interface = ui.launch(share=share, debug=debug)
+            print("✅ Interface launched successfully")
+            return interface
+
+        except ImportError as import_error:
+            import traceback
+            print(f"❌ Import failed: {import_error}")
+            print(f"Traceback: {traceback.format_exc()}")
+            raise
+
+    except Exception as e:
+        import traceback
+        print(f"❌ Failed to launch: {e}")
+        print(f"Full traceback: {traceback.format_exc()}")
+        raise
+
+def launch_ui(share: bool = True, debug: bool = False):
+    """Convenience function for Jupyter notebooks"""
+    return launch_final_blend_sceneweaver(share=share, debug=debug)
+
+def main():
+    """Main entry point"""
+
+    # Check if running in Jupyter/Colab
+    try:
+        get_ipython()
+        is_jupyter = True
+    except NameError:
+        is_jupyter = False
+
+    if not is_jupyter and len(sys.argv) > 1 and not any('-f' in arg for arg in sys.argv):
+        # Command line mode with arguments
+        share = '--no-share' not in sys.argv
+        debug = '--debug' in sys.argv
+    else:
+        # Default mode
+        share = True
+        debug = False
+
+    try:
+        interface = launch_final_blend_sceneweaver(share=share, debug=debug)
+
+        if not is_jupyter:
+            print("🛑 Press Ctrl+C to stop")
+            try:
+                interface.block_thread()
+            except KeyboardInterrupt:
+                print("👋 Stopped")
+
+        return interface
+
+    except Exception as e:
+        print(f"❌ Error: {e}")
+        if not is_jupyter:
+            sys.exit(1)
+        raise
+
+if __name__ == "__main__":
+    main()

css_styles.py

@@ -0,0 +1,513 @@
+class CSSStyles:
+    """
+    CSS styling configuration for the SceneWeaver application.
+    Professional design system with clean typography and modern aesthetics.
+    """
+
+    @staticmethod
+    def get_main_css() -> str:
+        """
+        Get the main CSS styling for the application.
+
+        Returns:
+            Complete CSS string for Gradio interface styling
+        """
+        return """
+        /* Import professional fonts */
+        @import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap');
+
+        /* CSS Variables - Professional color system */
+        :root {
+            /* Primary brand colors */
+            --primary-color: #1e3a5f;
+            --primary-hover: #2d5a8a;
+            --primary-light: #e8f4fd;
+
+            /* Accent colors */
+            --accent-color: #3b82f6;
+            --accent-hover: #2563eb;
+            --accent-light: #dbeafe;
+
+            /* Status colors */
+            --success-color: #10b981;
+            --warning-color: #f59e0b;
+            --error-color: #ef4444;
+
+            /* Neutral colors */
+            --bg-primary: #ffffff;
+            --bg-secondary: #f8fafc;
+            --bg-tertiary: #f1f5f9;
+            --text-primary: #1e293b;
+            --text-secondary: #475569;
+            --text-muted: #94a3b8;
+            --border-color: #e2e8f0;
+            --border-light: #f1f5f9;
+
+            /* Shadows */
+            --shadow-sm: 0 1px 2px 0 rgba(0, 0, 0, 0.05);
+            --shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -2px rgba(0, 0, 0, 0.1);
+            --shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -4px rgba(0, 0, 0, 0.1);
+            --shadow-xl: 0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 8px 10px -6px rgba(0, 0, 0, 0.1);
+
+            /* Border radius */
+            --radius-sm: 6px;
+            --radius-md: 8px;
+            --radius-lg: 12px;
+            --radius-xl: 16px;
+
+            /* Transitions */
+            --transition-fast: 150ms ease;
+            --transition-normal: 250ms ease;
+            --transition-slow: 350ms ease;
+        }
+
+        /* Global styles */
+        * {
+            font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif !important;
+            -webkit-font-smoothing: antialiased !important;
+            -moz-osx-font-smoothing: grayscale !important;
+        }
+
+        /* Main container */
+        .gradio-container {
+            background: linear-gradient(180deg, #f8fafc 0%, #f1f5f9 100%) !important;
+            min-height: 100vh !important;
+            padding: 24px !important;
+        }
+
+        /* ===== HEADER SECTION ===== */
+        .main-header {
+            text-align: center !important;
+            padding: 48px 32px 40px !important;
+            margin-bottom: 32px !important;
+            background: linear-gradient(135deg, var(--bg-primary) 0%, var(--bg-secondary) 100%) !important;
+            border-radius: var(--radius-xl) !important;
+            box-shadow: var(--shadow-md) !important;
+            border: 1px solid var(--border-light) !important;
+        }
+
+        .main-title {
+            font-size: 2.75rem !important;
+            font-weight: 700 !important;
+            color: var(--primary-color) !important;
+            margin: 0 0 12px 0 !important;
+            letter-spacing: -0.03em !important;
+            display: flex !important;
+            align-items: center !important;
+            justify-content: center !important;
+            gap: 14px !important;
+            line-height: 1.2 !important;
+        }
+
+        .title-emoji {
+            font-size: 2.5rem !important;
+            filter: drop-shadow(0 2px 4px rgba(0,0,0,0.15)) !important;
+            transition: transform var(--transition-normal) !important;
+        }
+
+        .title-emoji:hover {
+            transform: scale(1.1) rotate(-5deg) !important;
+        }
+
+        .main-subtitle {
+            font-size: 1.1rem !important;
+            color: var(--text-secondary) !important;
+            font-weight: 400 !important;
+            margin: 0 !important;
+            line-height: 1.5 !important;
+            max-width: 700px !important;
+            margin: 0 auto !important;
+        }
+
+        /* ===== CARD SYSTEM ===== */
+        .feature-card {
+            background: var(--bg-primary) !important;
+            border: 1px solid var(--border-color) !important;
+            border-radius: var(--radius-lg) !important;
+            padding: 24px !important;
+            margin-bottom: 20px !important;
+            box-shadow: var(--shadow-sm) !important;
+            transition: all var(--transition-normal) !important;
+            position: relative !important;
+        }
+
+        .feature-card:hover {
+            border-color: var(--accent-color) !important;
+            box-shadow: var(--shadow-lg) !important;
+            transform: translateY(-2px) !important;
+        }
+
+        .card-title {
+            font-size: 1.25rem !important;
+            font-weight: 600 !important;
+            color: var(--text-primary) !important;
+            margin-bottom: 16px !important;
+            display: flex !important;
+            align-items: center !important;
+            gap: 10px !important;
+        }
+
+        .section-emoji {
+            font-size: 1.2rem !important;
+            filter: drop-shadow(0 1px 2px rgba(0,0,0,0.1)) !important;
+        }
+
+        /* ===== INPUT COMPONENTS ===== */
+        .input-field {
+            border: 1px solid var(--border-color) !important;
+            border-radius: var(--radius-md) !important;
+            background: var(--bg-primary) !important;
+            transition: all var(--transition-fast) !important;
+        }
+
+        .input-field:focus-within {
+            border-color: var(--accent-color) !important;
+            box-shadow: 0 0 0 3px var(--accent-light) !important;
+        }
+
+        /* ===== BUTTONS ===== */
+        .primary-button {
+            background: linear-gradient(135deg, var(--accent-color) 0%, var(--accent-hover) 100%) !important;
+            color: white !important;
+            border: none !important;
+            border-radius: var(--radius-md) !important;
+            padding: 14px 28px !important;
+            font-size: 1rem !important;
+            font-weight: 600 !important;
+            cursor: pointer !important;
+            transition: all var(--transition-normal) !important;
+            box-shadow: var(--shadow-md) !important;
+        }
+
+        .primary-button:hover {
+            transform: translateY(-2px) !important;
+            box-shadow: var(--shadow-lg) !important;
+            filter: brightness(1.05) !important;
+        }
+
+        .secondary-button {
+            background: var(--bg-primary) !important;
+            color: var(--accent-color) !important;
+            border: 1.5px solid var(--accent-color) !important;
+            border-radius: var(--radius-md) !important;
+            padding: 12px 20px !important;
+            font-size: 0.95rem !important;
+            font-weight: 500 !important;
+            cursor: pointer !important;
+            transition: all var(--transition-fast) !important;
+        }
+
+        .secondary-button:hover {
+            background: var(--accent-light) !important;
+            transform: translateY(-1px) !important;
+        }
+
+        /* ===== RESULTS GALLERY ===== */
+        #results-gallery-centered {
+            display: flex !important;
+            flex-direction: column !important;
+            align-items: center !important;
+        }
+
+        #results-gallery-centered .gradio-tabs {
+            width: 100% !important;
+        }
+
+        .result-gallery {
+            border-radius: var(--radius-lg) !important;
+            overflow: hidden !important;
+            border: 1px solid var(--border-color) !important;
+            box-shadow: var(--shadow-md) !important;
+        }
+
+        .result-gallery img {
+            width: 100% !important;
+            height: auto !important;
+            object-fit: contain !important;
+        }
+
+        /* ===== STATUS PANEL ===== */
+        .status-panel {
+            background: var(--bg-secondary) !important;
+            border: 1px solid var(--border-color) !important;
+            border-radius: var(--radius-md) !important;
+            padding: 12px 16px !important;
+            margin: 16px 0 !important;
+        }
+
+        .status-ready {
+            color: var(--success-color) !important;
+            font-weight: 500 !important;
+        }
+
+        /* ===== LOADING NOTICE ===== */
+        .loading-notice {
+            background: linear-gradient(135deg, #fef3c7 0%, #fde68a 100%) !important;
+            border: 1px solid #f59e0b !important;
+            border-radius: var(--radius-md) !important;
+            padding: 14px 18px !important;
+            margin: 16px 0 !important;
+            display: flex !important;
+            align-items: center !important;
+            gap: 12px !important;
+        }
+
+        .loading-notice-icon {
+            font-size: 1.3rem !important;
+            flex-shrink: 0 !important;
+        }
+
+        .loading-notice-text {
+            color: #92400e !important;
+            font-size: 0.9rem !important;
+            font-weight: 500 !important;
+            line-height: 1.5 !important;
+        }
+
+        /* ===== QUICK START GUIDE ===== */
+        .user-guidance-panel {
+            background: var(--bg-secondary) !important;
+            border: 1px solid var(--border-color) !important;
+            border-radius: var(--radius-md) !important;
+            margin: 16px 0 !important;
+            overflow: hidden !important;
+        }
+
+        .guidance-summary {
+            background: var(--bg-primary) !important;
+            padding: 12px 16px !important;
+            cursor: pointer !important;
+            font-weight: 500 !important;
+            color: var(--text-primary) !important;
+            transition: background var(--transition-fast) !important;
+            list-style: none !important;
+            display: flex !important;
+            align-items: center !important;
+            gap: 8px !important;
+            border-bottom: 1px solid var(--border-color) !important;
+        }
+
+        .guidance-summary:hover {
+            background: var(--accent-light) !important;
+        }
+
+        .guidance-summary::-webkit-details-marker {
+            display: none !important;
+        }
+
+        .guidance-content {
+            padding: 16px !important;
+            color: var(--text-secondary) !important;
+            line-height: 1.6 !important;
+        }
+
+        .guidance-content p {
+            margin: 8px 0 !important;
+            font-size: 0.9rem !important;
+        }
+
+        .guidance-content strong {
+            color: var(--primary-color) !important;
+            font-weight: 600 !important;
+        }
+
+        /* ===== FOOTER ===== */
+        .app-footer {
+            background: var(--bg-primary) !important;
+            border: 1px solid var(--border-color) !important;
+            border-radius: var(--radius-lg) !important;
+            padding: 32px !important;
+            margin-top: 32px !important;
+            text-align: center !important;
+        }
+
+        .footer-powered {
+            margin-bottom: 20px !important;
+        }
+
+        .footer-powered-title {
+            font-size: 0.85rem !important;
+            font-weight: 500 !important;
+            color: var(--text-muted) !important;
+            text-transform: uppercase !important;
+            letter-spacing: 0.1em !important;
+            margin-bottom: 16px !important;
+        }
+
+        .footer-tech-grid {
+            display: flex !important;
+            flex-wrap: wrap !important;
+            justify-content: center !important;
+            gap: 12px !important;
+            margin-bottom: 24px !important;
+        }
+
+        .footer-tech-item {
+            background: var(--bg-secondary) !important;
+            border: 1px solid var(--border-color) !important;
+            border-radius: var(--radius-sm) !important;
+            padding: 8px 16px !important;
+            font-size: 0.85rem !important;
+            font-weight: 500 !important;
+            color: var(--text-secondary) !important;
+            transition: all var(--transition-fast) !important;
+        }
+
+        .footer-tech-item:hover {
+            background: var(--accent-light) !important;
+            border-color: var(--accent-color) !important;
+            color: var(--accent-color) !important;
+        }
+
+        .footer-divider {
+            height: 1px !important;
+            background: var(--border-color) !important;
+            margin: 20px auto !important;
+            max-width: 400px !important;
+        }
+
+        .footer-copyright {
+            font-size: 0.85rem !important;
+            color: var(--text-muted) !important;
+            font-weight: 400 !important;
+        }
+
+        .footer-copyright a {
+            color: var(--accent-color) !important;
+            text-decoration: none !important;
+            font-weight: 500 !important;
+        }
+
+        .footer-copyright a:hover {
+            text-decoration: underline !important;
+        }
+
+        /* ===== TABS STYLING ===== */
+        .gradio-tabs {
+            border: none !important;
+        }
+
+        .gradio-tabs > .tab-nav {
+            background: var(--bg-secondary) !important;
+            border-radius: var(--radius-md) !important;
+            padding: 4px !important;
+            gap: 4px !important;
+            border: 1px solid var(--border-color) !important;
+            margin-bottom: 16px !important;
+        }
+
+        .gradio-tabs > .tab-nav > button {
+            border-radius: var(--radius-sm) !important;
+            padding: 10px 20px !important;
+            font-weight: 500 !important;
+            font-size: 0.9rem !important;
+            transition: all var(--transition-fast) !important;
+            border: none !important;
+            background: transparent !important;
+            color: var(--text-secondary) !important;
+        }
+
+        .gradio-tabs > .tab-nav > button.selected {
+            background: var(--bg-primary) !important;
+            color: var(--accent-color) !important;
+            box-shadow: var(--shadow-sm) !important;
+        }
+
+        .gradio-tabs > .tab-nav > button:hover:not(.selected) {
+            background: var(--bg-primary) !important;
+            color: var(--text-primary) !important;
+        }
+
+        /* ===== ACCORDION ===== */
+        .gradio-accordion {
+            border: 1px solid var(--border-color) !important;
+            border-radius: var(--radius-md) !important;
+            overflow: hidden !important;
+            margin-top: 12px !important;
+        }
+
+        .gradio-accordion > .label-wrap {
+            background: var(--bg-secondary) !important;
+            padding: 12px 16px !important;
+            font-weight: 500 !important;
+        }
+
+        .gradio-accordion > .label-wrap:hover {
+            background: var(--bg-tertiary) !important;
+        }
+
+        /* ===== RESPONSIVE ===== */
+        @media (max-width: 768px) {
+            .main-title {
+                font-size: 2rem !important;
+            }
+
+            .main-subtitle {
+                font-size: 1rem !important;
+            }
+
+            .footer-tech-grid {
+                gap: 8px !important;
+            }
+
+            .footer-tech-item {
+                padding: 6px 12px !important;
+                font-size: 0.8rem !important;
+            }
+        }
+
+        /* ===== EMOJI ENHANCEMENT ===== */
+        .emoji-enhanced {
+            display: inline-block !important;
+            font-style: normal !important;
+            filter: drop-shadow(0 1px 2px rgba(0,0,0,0.1)) !important;
+            transition: transform var(--transition-fast) !important;
+        }
+
+        .emoji-enhanced:hover {
+            transform: scale(1.1) !important;
+        }
+
+        /* ===== IMAGE DISPLAY FIX ===== */
+        .gradio-image {
+            min-height: 200px !important;
+        }
+
+        .gradio-image img {
+            max-height: 500px !important;
+            object-fit: contain !important;
+        }
+
+        /* ===== SCENE TEMPLATE DROPDOWN ===== */
+        .template-dropdown {
+            margin: 8px 0 !important;
+        }
+
+        .template-dropdown select,
+        .template-dropdown input {
+            font-size: 0.95rem !important;
+            padding: 10px 14px !important;
+            border-radius: var(--radius-md) !important;
+            border: 1px solid var(--border-color) !important;
+            background: var(--bg-primary) !important;
+            transition: all var(--transition-fast) !important;
+        }
+
+        .template-dropdown select:hover,
+        .template-dropdown input:hover {
+            border-color: var(--accent-color) !important;
+        }
+
+        .template-dropdown select:focus,
+        .template-dropdown input:focus {
+            border-color: var(--accent-color) !important;
+            box-shadow: 0 0 0 3px var(--accent-light) !important;
+            outline: none !important;
+        }
+
+        /* Dropdown option styling */
+        .template-dropdown option {
+            padding: 8px 12px !important;
+            font-size: 0.95rem !important;
+        }
+        """

image_blender.py

@@ -0,0 +1,802 @@
+import cv2
+import numpy as np
+from PIL import Image
+import logging
+from typing import Dict, Any, Optional, Tuple
+
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.INFO)
+
+class ImageBlender:
+    """
+    Advanced image blending with aggressive spill suppression and color replacement
+    Completely eliminates yellow edge residue while maintaining sharp edges
+    """
+
+    EDGE_EROSION_PIXELS = 1          # Pixels to erode from mask edge (reduced to protect more foreground)
+    ALPHA_BINARIZE_THRESHOLD = 0.5   # Alpha threshold for binarization (increased to keep more foreground)
+    DARK_LUMINANCE_THRESHOLD = 60    # Luminance threshold for dark foreground detection
+    FOREGROUND_PROTECTION_THRESHOLD = 140  # Mask value above which pixels are strongly protected
+    BACKGROUND_COLOR_TOLERANCE = 30  # DeltaE tolerance for background color detection
+
+    def __init__(self, enable_multi_scale: bool = True):
+        """
+        Initialize ImageBlender.
+
+        Args:
+            enable_multi_scale: Whether to enable multi-scale edge refinement (default True)
+        """
+        self.enable_multi_scale = enable_multi_scale
+        self._debug_info = {}
+        self._adaptive_strength_map = None
+
+    def _erode_mask_edges(
+        self,
+        mask_array: np.ndarray,
+        erosion_pixels: int = 2
+    ) -> np.ndarray:
+        """
+        Erode mask edges to remove contaminated boundary pixels.
+
+        This removes the outermost pixels of the foreground mask where
+        color contamination from the original background is most likely.
+
+        Args:
+            mask_array: Input mask as numpy array (uint8, 0-255)
+            erosion_pixels: Number of pixels to erode (default 2)
+
+        Returns:
+            Eroded mask array (uint8)
+        """
+        if erosion_pixels <= 0:
+            return mask_array
+
+        # Use elliptical kernel for natural-looking erosion
+        kernel_size = max(2, erosion_pixels)
+        kernel = cv2.getStructuringElement(
+            cv2.MORPH_ELLIPSE,
+            (kernel_size, kernel_size)
+        )
+
+        # Apply erosion
+        eroded = cv2.erode(mask_array, kernel, iterations=1)
+
+        # Slight blur to smooth the eroded edges
+        eroded = cv2.GaussianBlur(eroded, (3, 3), 0)
+
+        logger.debug(f"Mask erosion applied: {erosion_pixels}px, kernel size: {kernel_size}")
+        return eroded
+
+    def _binarize_edge_alpha(
+        self,
+        alpha: np.ndarray,
+        mask_array: np.ndarray,
+        orig_array: np.ndarray,
+        threshold: float = 0.45
+    ) -> np.ndarray:
+        """
+        Binarize semi-transparent edge pixels to eliminate color bleeding.
+
+        Semi-transparent pixels at edges cause visible contamination because
+        they blend the original (potentially dark) foreground with the new
+        background. This method forces edge pixels to be either fully opaque
+        or fully transparent.
+
+        Args:
+            alpha: Current alpha channel (float32, 0.0-1.0)
+            mask_array: Original mask array (uint8, 0-255)
+            orig_array: Original foreground image array (uint8, RGB)
+            threshold: Alpha threshold for binarization decision (default 0.45)
+
+        Returns:
+            Modified alpha array with binarized edges (float32)
+        """
+        # Identify semi-transparent edge zone (not fully opaque, not fully transparent)
+        edge_zone = (alpha > 0.05) & (alpha < 0.95)
+
+        if not np.any(edge_zone):
+            return alpha
+
+        # Calculate local foreground luminance for adaptive thresholding
+        gray = np.mean(orig_array, axis=2)
+
+        # For dark foreground pixels, use slightly higher threshold
+        # to preserve more of the dark subject
+        is_dark = gray < self.DARK_LUMINANCE_THRESHOLD
+
+        # Create adaptive threshold map
+        adaptive_threshold = np.full_like(alpha, threshold)
+        adaptive_threshold[is_dark] = threshold + 0.1  # Keep more dark pixels
+
+        # Binarize: above threshold -> opaque, below -> transparent
+        alpha_binarized = alpha.copy()
+
+        # Pixels above threshold become fully opaque
+        make_opaque = edge_zone & (alpha > adaptive_threshold)
+        alpha_binarized[make_opaque] = 1.0
+
+        # Pixels below threshold become fully transparent
+        make_transparent = edge_zone & (alpha <= adaptive_threshold)
+        alpha_binarized[make_transparent] = 0.0
+
+        # Log statistics
+        num_opaque = np.sum(make_opaque)
+        num_transparent = np.sum(make_transparent)
+        logger.info(f"Edge binarization: {num_opaque} pixels -> opaque, {num_transparent} pixels -> transparent")
+
+        return alpha_binarized
+
+    def _apply_edge_cleanup(
+        self,
+        result_array: np.ndarray,
+        bg_array: np.ndarray,
+        alpha: np.ndarray,
+        cleanup_width: int = 2
+    ) -> np.ndarray:
+        """
+        Final cleanup pass to remove any remaining edge artifacts.
+
+        Detects remaining semi-transparent edges and replaces them with
+        either pure foreground or pure background colors.
+
+        Args:
+            result_array: Current blended result (uint8, RGB)
+            bg_array: Background image array (uint8, RGB)
+            alpha: Final alpha channel (float32, 0.0-1.0)
+            cleanup_width: Width of edge zone to clean (default 2)
+
+        Returns:
+            Cleaned result array (uint8)
+        """
+        # Find edge pixels that might still have artifacts
+        # These are pixels with alpha close to but not exactly 0 or 1
+        residual_edge = (alpha > 0.01) & (alpha < 0.99) & (alpha != 0.0) & (alpha != 1.0)
+
+        if not np.any(residual_edge):
+            return result_array
+
+        result_cleaned = result_array.copy()
+
+        # For residual edge pixels, snap to nearest pure state
+        snap_to_bg = residual_edge & (alpha < 0.5)
+        snap_to_fg = residual_edge & (alpha >= 0.5)
+
+        # Replace with background
+        result_cleaned[snap_to_bg] = bg_array[snap_to_bg]
+
+        # For foreground, keep original but ensure no blending artifacts
+        # (already handled by the blend, so no action needed for snap_to_fg)
+
+        num_cleaned = np.sum(residual_edge)
+        if num_cleaned > 0:
+            logger.debug(f"Edge cleanup: {num_cleaned} residual pixels cleaned")
+
+        return result_cleaned
+
+    def _remove_background_color_contamination(
+        self,
+        image_array: np.ndarray,
+        mask_array: np.ndarray,
+        orig_bg_color_lab: np.ndarray,
+        tolerance: float = 30.0
+    ) -> np.ndarray:
+        """
+        Remove original background color contamination from foreground pixels.
+
+        Scans the foreground area for pixels that match the original background
+        color and replaces them with nearby clean foreground colors.
+
+        Args:
+            image_array: Foreground image array (uint8, RGB)
+            mask_array: Mask array (uint8, 0-255)
+            orig_bg_color_lab: Original background color in Lab space
+            tolerance: DeltaE tolerance for detecting contaminated pixels
+
+        Returns:
+            Cleaned image array (uint8)
+        """
+        # Convert to Lab for color comparison
+        image_lab = cv2.cvtColor(image_array, cv2.COLOR_RGB2LAB).astype(np.float32)
+
+        # Only process foreground pixels (mask > 50)
+        foreground_mask = mask_array > 50
+
+        if not np.any(foreground_mask):
+            return image_array
+
+        # Calculate deltaE from original background color for all pixels
+        delta_l = image_lab[:, :, 0] - orig_bg_color_lab[0]
+        delta_a = image_lab[:, :, 1] - orig_bg_color_lab[1]
+        delta_b = image_lab[:, :, 2] - orig_bg_color_lab[2]
+        delta_e = np.sqrt(delta_l**2 + delta_a**2 + delta_b**2)
+
+        # Find contaminated pixels: in foreground but color similar to original background
+        contaminated = foreground_mask & (delta_e < tolerance)
+
+        if not np.any(contaminated):
+            logger.debug("No background color contamination detected in foreground")
+            return image_array
+
+        num_contaminated = np.sum(contaminated)
+        logger.info(f"Found {num_contaminated} pixels with background color contamination")
+
+        # Create output array
+        result = image_array.copy()
+
+        # For contaminated pixels, use inpainting to replace with surrounding colors
+        inpaint_mask = contaminated.astype(np.uint8) * 255
+
+        try:
+            # Use inpainting to fill contaminated areas with surrounding foreground colors
+            result = cv2.inpaint(result, inpaint_mask, inpaintRadius=3, flags=cv2.INPAINT_TELEA)
+            logger.info(f"Inpainted {num_contaminated} contaminated pixels")
+        except Exception as e:
+            logger.warning(f"Inpainting failed: {e}, using median filter fallback")
+            # Fallback: apply median filter to contaminated areas
+            median_filtered = cv2.medianBlur(image_array, 5)
+            result[contaminated] = median_filtered[contaminated]
+
+        return result
+
+    def _protect_foreground_core(
+        self,
+        result_array: np.ndarray,
+        orig_array: np.ndarray,
+        mask_array: np.ndarray,
+        protection_threshold: int = 140
+    ) -> np.ndarray:
+        """
+        Strongly protect core foreground pixels from any background influence.
+
+        For pixels with high mask confidence, directly use the original foreground
+        color without any blending, ensuring faces and bodies are not affected.
+
+        Args:
+            result_array: Current blended result (uint8, RGB)
+            orig_array: Original foreground image (uint8, RGB)
+            mask_array: Mask array (uint8, 0-255)
+            protection_threshold: Mask value above which pixels are fully protected
+
+        Returns:
+            Protected result array (uint8)
+        """
+        # Identify strongly protected foreground pixels
+        strong_foreground = mask_array >= protection_threshold
+
+        if not np.any(strong_foreground):
+            return result_array
+
+        # For these pixels, use original foreground color directly
+        result_protected = result_array.copy()
+        result_protected[strong_foreground] = orig_array[strong_foreground]
+
+        num_protected = np.sum(strong_foreground)
+        logger.info(f"Protected {num_protected} core foreground pixels from background influence")
+
+        return result_protected
+
+    def multi_scale_edge_refinement(
+        self,
+        original_image: Image.Image,
+        background_image: Image.Image,
+        mask: Image.Image
+    ) -> Image.Image:
+        """
+        Multi-scale edge refinement for better edge quality.
+        Uses image pyramid to handle edges at different scales.
+
+        Args:
+            original_image: Foreground PIL Image
+            background_image: Background PIL Image
+            mask: Current mask PIL Image
+
+        Returns:
+            Refined mask PIL Image
+        """
+        logger.info("🔍 Starting multi-scale edge refinement...")
+
+        try:
+            # Convert to numpy arrays
+            orig_array = np.array(original_image.convert('RGB'))
+            mask_array = np.array(mask).astype(np.float32)
+            height, width = mask_array.shape
+
+            # Define scales for pyramid
+            scales = [1.0, 0.5, 0.25]  # Original, half, quarter
+            scale_masks = []
+            scale_complexities = []
+
+            # Convert to grayscale for edge detection
+            gray = cv2.cvtColor(orig_array, cv2.COLOR_RGB2GRAY)
+
+            for scale in scales:
+                if scale == 1.0:
+                    scaled_gray = gray
+                    scaled_mask = mask_array
+                else:
+                    new_h = int(height * scale)
+                    new_w = int(width * scale)
+                    scaled_gray = cv2.resize(gray, (new_w, new_h), interpolation=cv2.INTER_LANCZOS4)
+                    scaled_mask = cv2.resize(mask_array, (new_w, new_h), interpolation=cv2.INTER_LANCZOS4)
+
+                # Compute local complexity using gradient standard deviation
+                sobel_x = cv2.Sobel(scaled_gray, cv2.CV_64F, 1, 0, ksize=3)
+                sobel_y = cv2.Sobel(scaled_gray, cv2.CV_64F, 0, 1, ksize=3)
+                gradient_mag = np.sqrt(sobel_x**2 + sobel_y**2)
+
+                # Calculate local complexity in 5x5 regions
+                kernel_size = 5
+                complexity = cv2.blur(gradient_mag, (kernel_size, kernel_size))
+
+                # Resize back to original size
+                if scale != 1.0:
+                    scaled_mask = cv2.resize(scaled_mask, (width, height), interpolation=cv2.INTER_LANCZOS4)
+                    complexity = cv2.resize(complexity, (width, height), interpolation=cv2.INTER_LANCZOS4)
+
+                scale_masks.append(scaled_mask)
+                scale_complexities.append(complexity)
+
+            # Compute weights based on complexity
+            # High complexity -> use high resolution mask
+            # Low complexity -> use low resolution mask (smoother)
+            weights = np.zeros((len(scales), height, width), dtype=np.float32)
+
+            # Normalize complexities
+            max_complexity = max(c.max() for c in scale_complexities) + 1e-6
+            normalized_complexities = [c / max_complexity for c in scale_complexities]
+
+            # Weight assignment: higher complexity at each scale means that scale is more reliable
+            for i, complexity in enumerate(normalized_complexities):
+                if i == 0:  # High resolution - prefer for high complexity regions
+                    weights[i] = complexity
+                elif i == 1:  # Medium resolution - moderate complexity
+                    weights[i] = 0.5 * (1 - complexity) + 0.5 * complexity * 0.5
+                else:  # Low resolution - prefer for low complexity regions
+                    weights[i] = 1 - complexity
+
+            # Normalize weights so they sum to 1 at each pixel
+            weight_sum = weights.sum(axis=0, keepdims=True) + 1e-6
+            weights = weights / weight_sum
+
+            # Weighted blend of masks from different scales
+            refined_mask = np.zeros((height, width), dtype=np.float32)
+            for i, mask_i in enumerate(scale_masks):
+                refined_mask += weights[i] * mask_i
+
+            # Clip and convert to uint8
+            refined_mask = np.clip(refined_mask, 0, 255).astype(np.uint8)
+
+            logger.info("✅ Multi-scale edge refinement completed")
+            return Image.fromarray(refined_mask, mode='L')
+
+        except Exception as e:
+            logger.error(f"❌ Multi-scale refinement failed: {e}, using original mask")
+            return mask
+
+    def simple_blend_images(
+        self,
+        original_image: Image.Image,
+        background_image: Image.Image,
+        combination_mask: Image.Image,
+        use_multi_scale: Optional[bool] = None
+    ) -> Image.Image:
+        """
+        Aggressive spill suppression + color replacement: completely eliminate yellow edge residue, maintain sharp edges
+
+        Args:
+            original_image: Foreground PIL Image
+            background_image: Background PIL Image
+            combination_mask: Mask PIL Image (L mode)
+            use_multi_scale: Override for multi-scale refinement (None = use class default)
+
+        Returns:
+            Blended PIL Image
+        """
+        logger.info("🎨 Starting advanced image blending process...")
+
+        # Apply multi-scale edge refinement if enabled
+        should_use_multi_scale = use_multi_scale if use_multi_scale is not None else self.enable_multi_scale
+        if should_use_multi_scale:
+            combination_mask = self.multi_scale_edge_refinement(
+                original_image, background_image, combination_mask
+            )
+
+        # Convert to numpy arrays
+        orig_array = np.array(original_image, dtype=np.uint8)
+        bg_array = np.array(background_image, dtype=np.uint8)
+        mask_array = np.array(combination_mask, dtype=np.uint8)
+
+        logger.info(f"📊 Image dimensions - Original: {orig_array.shape}, Background: {bg_array.shape}, Mask: {mask_array.shape}")
+        logger.info(f"📊 Mask statistics (before erosion) - Mean: {mask_array.mean():.1f}, Min: {mask_array.min()}, Max: {mask_array.max()}")
+
+        # === NEW: Apply mask erosion to remove contaminated edge pixels ===
+        mask_array = self._erode_mask_edges(mask_array, self.EDGE_EROSION_PIXELS)
+        logger.info(f"📊 Mask statistics (after erosion) - Mean: {mask_array.mean():.1f}, Min: {mask_array.min()}, Max: {mask_array.max()}")
+
+        # Enhanced parameters for better spill suppression
+        RING_WIDTH_PX = 4           # Increased ring width for better coverage
+        SPILL_STRENGTH = 0.85       # Stronger spill suppression
+        L_MATCH_STRENGTH = 0.65     # Stronger luminance matching
+        DELTAE_THRESHOLD = 18       # More aggressive contamination detection
+        HARD_EDGE_PROTECT = True    # Black edge protection
+        INPAINT_FALLBACK = True     # inpaint fallback repair
+        MULTI_PASS_CORRECTION = True # Enable multi-pass correction
+
+        # Estimate original background color and foreground representative color ===
+        height, width = orig_array.shape[:2]
+
+        # Take 15px from each side to estimate original background color
+        edge_width = 15
+        border_pixels = []
+
+        # Collect border pixels (excluding foreground areas)
+        border_mask = np.zeros((height, width), dtype=bool)
+        border_mask[:edge_width, :] = True  # Top edge
+        border_mask[-edge_width:, :] = True  # Bottom edge
+        border_mask[:, :edge_width] = True  # Left edge
+        border_mask[:, -edge_width:] = True  # Right edge
+
+        # Exclude foreground areas
+        fg_binary = mask_array > 50
+        border_mask = border_mask & (~fg_binary)
+
+        if np.any(border_mask):
+            border_pixels = orig_array[border_mask].reshape(-1, 3)
+
+            # Simplified background color estimation (no sklearn dependency)
+            try:
+                if len(border_pixels) > 100:
+                    # Use histogram to find mode colors
+                    # Quantize RGB to coarser grid to find main colors
+                    quantized = (border_pixels // 32) * 32  # 8-level quantization
+
+                    # Find most frequent color
+                    unique_colors, counts = np.unique(quantized.reshape(-1, quantized.shape[-1]),
+                                                    axis=0, return_counts=True)
+                    most_common_idx = np.argmax(counts)
+                    orig_bg_color_rgb = unique_colors[most_common_idx].astype(np.uint8)
+                else:
+                    orig_bg_color_rgb = np.median(border_pixels, axis=0).astype(np.uint8)
+            except:
+                # Fallback: use four corners average
+                corners = np.array([orig_array[0,0], orig_array[0,-1],
+                                  orig_array[-1,0], orig_array[-1,-1]])
+                orig_bg_color_rgb = np.mean(corners, axis=0).astype(np.uint8)
+        else:
+            orig_bg_color_rgb = np.array([200, 180, 120], dtype=np.uint8)  # Default yellow
+
+        # Convert to Lab space
+        orig_bg_color_lab = cv2.cvtColor(orig_bg_color_rgb.reshape(1,1,3), cv2.COLOR_RGB2LAB)[0,0].astype(np.float32)
+        logger.info(f"🎨 Detected original background color: RGB{tuple(orig_bg_color_rgb)}")
+
+        # Remove original background color contamination from foreground 
+        orig_array = self._remove_background_color_contamination(
+            orig_array,
+            mask_array,
+            orig_bg_color_lab,
+            tolerance=self.BACKGROUND_COLOR_TOLERANCE
+        )
+
+        # Redefine trimap, optimized for cartoon characters 
+        try:
+            kernel_3x3 = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (3, 3))
+
+            # FG_CORE: Reduce erosion iterations from 2 to 1 to avoid losing thin limbs
+            mask_eroded_once = cv2.erode(mask_array, kernel_3x3, iterations=1)
+            fg_core = mask_eroded_once > 127  # Adjustable parameter: erosion iterations
+
+            # RING: Use morphological gradient to redefine, ensuring only thin edge band
+            mask_dilated = cv2.dilate(mask_array, kernel_3x3, iterations=1)
+            mask_eroded = cv2.erode(mask_array, kernel_3x3, iterations=1)
+
+            # Ensure consistent data types to avoid overflow
+            morphological_gradient = cv2.subtract(mask_dilated, mask_eroded)
+            ring_zone = morphological_gradient > 0  # Areas with morphological gradient > 0 are edge bands
+
+            # BG: background area
+            bg_zone = mask_array < 30
+
+            logger.info(f"🔍 Trimap regions - FG_CORE: {fg_core.sum()}, RING: {ring_zone.sum()}, BG: {bg_zone.sum()}")
+
+        except Exception as e:
+            import traceback
+            logger.error(f"❌ Trimap definition failed: {e}")
+            logger.error(f"📍 Traceback: {traceback.format_exc()}")
+            print(f"❌ TRIMAP ERROR: {e}")
+            print(f"Traceback: {traceback.format_exc()}")
+            # Fallback to simple definition
+            fg_core = mask_array > 200
+            ring_zone = (mask_array > 50) & (mask_array <= 200)
+            bg_zone = mask_array <= 50
+
+        # Foreground representative color: estimated from FG_CORE
+        if np.any(fg_core):
+            fg_pixels = orig_array[fg_core].reshape(-1, 3)
+            fg_rep_color_rgb = np.median(fg_pixels, axis=0).astype(np.uint8)
+        else:
+            fg_rep_color_rgb = np.array([80, 60, 40], dtype=np.uint8)  # Default dark
+
+        fg_rep_color_lab = cv2.cvtColor(fg_rep_color_rgb.reshape(1,1,3), cv2.COLOR_RGB2LAB)[0,0].astype(np.float32)
+
+        # Edge band spill suppression and repair 
+        if np.any(ring_zone):
+            # Convert to Lab space
+            orig_lab = cv2.cvtColor(orig_array, cv2.COLOR_RGB2LAB).astype(np.float32)
+            orig_array_working = orig_array.copy().astype(np.float32)
+
+            # ΔE detect contaminated pixels
+            ring_pixels_lab = orig_lab[ring_zone]
+
+            # Calculate ΔE with original background color (simplified version)
+            delta_l = ring_pixels_lab[:, 0] - orig_bg_color_lab[0]
+            delta_a = ring_pixels_lab[:, 1] - orig_bg_color_lab[1]
+            delta_b = ring_pixels_lab[:, 2] - orig_bg_color_lab[2]
+            delta_e = np.sqrt(delta_l**2 + delta_a**2 + delta_b**2)
+
+            # Contaminated pixel mask
+            contaminated_mask = delta_e < DELTAE_THRESHOLD
+
+            if np.any(contaminated_mask):
+                # Calculate adaptive strength based on delta_e for each pixel
+                # Pixels closer to background color get stronger correction
+                contaminated_delta_e = delta_e[contaminated_mask]
+
+                # Adaptive strength formula: inverse relationship with delta_e
+                # Pixels very close to bg color (low delta_e) -> strong correction
+                # Pixels further from bg color (high delta_e) -> lighter correction
+                adaptive_strength = SPILL_STRENGTH * np.maximum(
+                    0.0,
+                    1.0 - (contaminated_delta_e / DELTAE_THRESHOLD)
+                )
+
+                # Clamp adaptive strength to reasonable range (30% - 100% of base strength)
+                min_strength = SPILL_STRENGTH * 0.3
+                adaptive_strength = np.clip(adaptive_strength, min_strength, SPILL_STRENGTH)
+
+                # Store for debug visualization
+                self._adaptive_strength_map = np.zeros_like(delta_e)
+                self._adaptive_strength_map[contaminated_mask] = adaptive_strength
+
+                logger.info(f"📊 Adaptive strength stats - Mean: {adaptive_strength.mean():.3f}, Min: {adaptive_strength.min():.3f}, Max: {adaptive_strength.max():.3f}")
+
+                # Chroma vector deprojection
+                bg_chroma = np.array([orig_bg_color_lab[1], orig_bg_color_lab[2]])
+                bg_chroma_norm = bg_chroma / (np.linalg.norm(bg_chroma) + 1e-6)
+
+                # Color correction for contaminated pixels
+                contaminated_pixels = ring_pixels_lab[contaminated_mask]
+
+                # Remove background chroma component with adaptive strength (per-pixel)
+                pixel_chroma = contaminated_pixels[:, 1:3]  # a, b channels
+                projection = np.dot(pixel_chroma, bg_chroma_norm)[:, np.newaxis] * bg_chroma_norm
+
+                # Apply adaptive strength per pixel
+                adaptive_strength_2d = adaptive_strength[:, np.newaxis]
+                corrected_chroma = pixel_chroma - projection * adaptive_strength_2d
+
+                # Converge toward foreground representative color with adaptive strength
+                convergence_factor = adaptive_strength_2d * 0.6
+                corrected_chroma = (corrected_chroma * (1 - convergence_factor) +
+                                  fg_rep_color_lab[1:3] * convergence_factor)
+
+                # Adaptive luminance matching
+                adaptive_l_strength = adaptive_strength * (L_MATCH_STRENGTH / SPILL_STRENGTH)
+                corrected_l = (contaminated_pixels[:, 0] * (1 - adaptive_l_strength) +
+                             fg_rep_color_lab[0] * adaptive_l_strength)
+
+                # Update Lab values
+                ring_pixels_lab[contaminated_mask, 0] = corrected_l
+                ring_pixels_lab[contaminated_mask, 1:3] = corrected_chroma
+
+                # Write back to original image
+                orig_lab[ring_zone] = ring_pixels_lab
+
+            # Dark edge protection
+            if HARD_EDGE_PROTECT:
+                gray = np.mean(orig_array, axis=2)
+                # Detect dark and high gradient areas
+                sobel_x = cv2.Sobel(gray, cv2.CV_64F, 1, 0, ksize=3)
+                sobel_y = cv2.Sobel(gray, cv2.CV_64F, 0, 1, ksize=3)
+                gradient_mag = np.sqrt(sobel_x**2 + sobel_y**2)
+
+                dark_edge_zone = ring_zone & (gray < 60) & (gradient_mag > 20)
+                # Protect these areas from excessive modification, copy directly from original
+                if np.any(dark_edge_zone):
+                    orig_lab[dark_edge_zone] = cv2.cvtColor(orig_array, cv2.COLOR_RGB2LAB)[dark_edge_zone]
+
+            # Multi-pass correction for stubborn spill
+            if MULTI_PASS_CORRECTION:
+                # Second pass for remaining contamination
+                ring_pixels_lab_pass2 = orig_lab[ring_zone]
+                delta_l_pass2 = ring_pixels_lab_pass2[:, 0] - orig_bg_color_lab[0]
+                delta_a_pass2 = ring_pixels_lab_pass2[:, 1] - orig_bg_color_lab[1]
+                delta_b_pass2 = ring_pixels_lab_pass2[:, 2] - orig_bg_color_lab[2]
+                delta_e_pass2 = np.sqrt(delta_l_pass2**2 + delta_a_pass2**2 + delta_b_pass2**2)
+                
+                still_contaminated = delta_e_pass2 < (DELTAE_THRESHOLD * 0.8)
+                
+                if np.any(still_contaminated):
+                    # Apply stronger correction to remaining contaminated pixels
+                    remaining_pixels = ring_pixels_lab_pass2[still_contaminated]
+                    
+                    # More aggressive chroma neutralization
+                    remaining_chroma = remaining_pixels[:, 1:3]
+                    neutralized_chroma = remaining_chroma * 0.3 + fg_rep_color_lab[1:3] * 0.7
+                    
+                    # Stronger luminance matching
+                    neutralized_l = remaining_pixels[:, 0] * 0.4 + fg_rep_color_lab[0] * 0.6
+                    
+                    ring_pixels_lab_pass2[still_contaminated, 0] = neutralized_l
+                    ring_pixels_lab_pass2[still_contaminated, 1:3] = neutralized_chroma
+                    orig_lab[ring_zone] = ring_pixels_lab_pass2
+
+            # Convert back to RGB
+            orig_lab_clipped = np.clip(orig_lab, 0, 255).astype(np.uint8)
+            orig_array_corrected = cv2.cvtColor(orig_lab_clipped, cv2.COLOR_LAB2RGB)
+
+            # inpaint fallback repair
+            if INPAINT_FALLBACK:
+                # inpaint still contaminated outermost pixels
+                final_contaminated = ring_zone.copy()
+
+                # Check if there's still contamination after repair
+                final_lab = cv2.cvtColor(orig_array_corrected, cv2.COLOR_RGB2LAB).astype(np.float32)
+                final_ring_lab = final_lab[ring_zone]
+                final_delta_l = final_ring_lab[:, 0] - orig_bg_color_lab[0]
+                final_delta_a = final_ring_lab[:, 1] - orig_bg_color_lab[1]
+                final_delta_b = final_ring_lab[:, 2] - orig_bg_color_lab[2]
+                final_delta_e = np.sqrt(final_delta_l**2 + final_delta_a**2 + final_delta_b**2)
+
+                still_contaminated = final_delta_e < (DELTAE_THRESHOLD * 0.5)
+                if np.any(still_contaminated):
+                    # Create inpaint mask
+                    inpaint_mask = np.zeros((height, width), dtype=np.uint8)
+                    ring_coords = np.where(ring_zone)
+                    inpaint_coords = (ring_coords[0][still_contaminated], ring_coords[1][still_contaminated])
+                    inpaint_mask[inpaint_coords] = 255
+
+                    # Execute inpaint
+                    try:
+                        orig_array_corrected = cv2.inpaint(orig_array_corrected, inpaint_mask, 3, cv2.INPAINT_TELEA)
+                    except:
+                        # Fallback: directly cover with foreground representative color
+                        orig_array_corrected[inpaint_coords] = fg_rep_color_rgb
+
+            orig_array = orig_array_corrected
+
+        # === Linear space blending (keep original logic) ===
+        def srgb_to_linear(img):
+            img_f = img.astype(np.float32) / 255.0
+            return np.where(img_f <= 0.04045, img_f / 12.92, np.power((img_f + 0.055) / 1.055, 2.4))
+
+        def linear_to_srgb(img):
+            img_clipped = np.clip(img, 0, 1)
+            return np.where(img_clipped <= 0.0031308,
+                           12.92 * img_clipped,
+                           1.055 * np.power(img_clipped, 1/2.4) - 0.055)
+
+        orig_linear = srgb_to_linear(orig_array)
+        bg_linear = srgb_to_linear(bg_array)
+
+        # === Cartoon-optimized Alpha calculation ===
+        alpha = mask_array.astype(np.float32) / 255.0
+
+        # Core foreground region - fully opaque
+        alpha[fg_core] = 1.0
+
+        # Background region - fully transparent
+        alpha[bg_zone] = 0.0
+
+        # [Key Fix] Force pixels with mask≥160 to α=1.0, avoiding white fill areas being limited to 0.9
+        high_confidence_pixels = mask_array >= 160  
+        alpha[high_confidence_pixels] = 1.0
+        logger.info(f"💯 High confidence pixels set to full opacity: {high_confidence_pixels.sum()}")
+
+        # Ring area can be dehaloed, but doesn't affect already set high confidence pixels
+        ring_without_high_conf = ring_zone & (~high_confidence_pixels)
+        alpha[ring_without_high_conf] = np.clip(alpha[ring_without_high_conf], 0.2, 0.9)  
+
+        # Retain existing black outline/strong edge protection
+        orig_gray = np.mean(orig_array, axis=2)
+
+        # Detect strong edge areas
+        sobel_x = cv2.Sobel(orig_gray, cv2.CV_64F, 1, 0, ksize=3)
+        sobel_y = cv2.Sobel(orig_gray, cv2.CV_64F, 0, 1, ksize=3)
+        gradient_mag = np.sqrt(sobel_x**2 + sobel_y**2)
+
+        # Black outline/strong edge protection: nearly fully opaque
+        black_edge_threshold = 60  # black edge threshold
+        gradient_threshold = 25    # gradient threshold
+        strong_edges = (orig_gray < black_edge_threshold) & (gradient_mag > gradient_threshold) & (mask_array > 10)
+        alpha[strong_edges] = np.maximum(alpha[strong_edges], 0.995)  # black edge alpha
+
+        logger.info(f"🛡️ Protection applied - High conf: {high_confidence_pixels.sum()}, Strong edges: {strong_edges.sum()}")
+
+        # Apply edge alpha binarization to eliminate semi-transparent artifacts
+        alpha = self._binarize_edge_alpha(
+            alpha,
+            mask_array,
+            orig_array,
+            threshold=self.ALPHA_BINARIZE_THRESHOLD
+        )
+
+        # Final blending
+        alpha_3d = alpha[:, :, np.newaxis]
+        result_linear = orig_linear * alpha_3d + bg_linear * (1 - alpha_3d)
+        result_srgb = linear_to_srgb(result_linear)
+        result_array = (result_srgb * 255).astype(np.uint8)
+
+        # Final edge cleanup pass 
+        result_array = self._apply_edge_cleanup(result_array, bg_array, alpha)
+
+        # Protect core foreground from any background influence 
+        # This ensures faces and bodies retain original colors
+        result_array = self._protect_foreground_core(
+            result_array,
+            np.array(original_image, dtype=np.uint8),  # Use original unprocessed image
+            mask_array,
+            protection_threshold=self.FOREGROUND_PROTECTION_THRESHOLD
+        )
+
+        # Store debug information (for debug output)
+        self._debug_info = {
+            'orig_bg_color_rgb': orig_bg_color_rgb,
+            'fg_rep_color_rgb': fg_rep_color_rgb,
+            'orig_bg_color_lab': orig_bg_color_lab,
+            'fg_rep_color_lab': fg_rep_color_lab,
+            'ring_zone': ring_zone,
+            'fg_core': fg_core,
+            'alpha_final': alpha
+        }
+
+        return Image.fromarray(result_array)
+
+    def create_debug_images(
+        self,
+        original_image: Image.Image,
+        generated_background: Image.Image,
+        combination_mask: Image.Image,
+        combined_image: Image.Image
+    ) -> Dict[str, Image.Image]:
+        """
+        Generate debug images: (a) Final mask grayscale (b) Alpha heatmap (c) Ring visualization overlay
+        """
+        debug_images = {}
+
+        # Final Mask grayscale
+        debug_images["mask_gray"] = combination_mask.convert('L')
+
+        # Alpha Heatmap
+        mask_array = np.array(combination_mask.convert('L'))
+        heatmap_colored = cv2.applyColorMap(mask_array, cv2.COLORMAP_JET)
+        heatmap_rgb = cv2.cvtColor(heatmap_colored, cv2.COLOR_BGR2RGB)
+        debug_images["alpha_heatmap"] = Image.fromarray(heatmap_rgb)
+
+        # Ring visualization overlay - show ring areas on original image
+        if hasattr(self, '_debug_info') and 'ring_zone' in self._debug_info:
+            ring_zone = self._debug_info['ring_zone']
+            orig_array = np.array(original_image)
+            ring_overlay = orig_array.copy()
+
+            # Mark ring areas with red semi-transparent overlay
+            ring_overlay[ring_zone] = ring_overlay[ring_zone] * 0.7 + np.array([255, 0, 0]) * 0.3
+            debug_images["ring_visualization"] = Image.fromarray(ring_overlay.astype(np.uint8))
+        else:
+            # If no ring information, use original image
+            debug_images["ring_visualization"] = original_image
+
+        # Adaptive strength heatmap - visualize per-pixel correction strength
+        if hasattr(self, '_adaptive_strength_map') and self._adaptive_strength_map is not None:
+            # Normalize adaptive strength to 0-255 for visualization
+            strength_map = self._adaptive_strength_map
+            if strength_map.max() > 0:
+                normalized_strength = (strength_map / strength_map.max() * 255).astype(np.uint8)
+            else:
+                normalized_strength = np.zeros_like(strength_map, dtype=np.uint8)
+
+            # Apply colormap
+            strength_heatmap = cv2.applyColorMap(normalized_strength, cv2.COLORMAP_VIRIDIS)
+            strength_heatmap_rgb = cv2.cvtColor(strength_heatmap, cv2.COLOR_BGR2RGB)
+            debug_images["adaptive_strength_heatmap"] = Image.fromarray(strength_heatmap_rgb)
+
+        return debug_images

mask_generator.py

@@ -0,0 +1,650 @@
+import cv2
+import numpy as np
+from PIL import Image, ImageFilter, ImageDraw
+import logging
+from typing import Optional, Tuple
+from scipy.ndimage import binary_erosion, binary_dilation
+import io
+import gc
+import torch
+from transformers import AutoModelForImageSegmentation
+from torchvision import transforms
+from rembg import remove, new_session
+
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.INFO)
+
+class MaskGenerator:
+    """
+    Intelligent mask generation using deep learning models with traditional fallback.
+    Priority: BiRefNet > U²-Net (rembg) > Traditional gradient-based methods
+    """
+
+    def __init__(self, max_image_size: int = 1024, device: str = "auto"):
+        self.max_image_size = max_image_size
+        self.device = self._setup_device(device)
+
+        # BiRefNet model (lazy loading)
+        self._birefnet_model = None
+        self._birefnet_transform = None
+
+        # Log initialization
+        logger.info(f"🎭 MaskGenerator initialized on {self.device}")
+
+    def _setup_device(self, device: str) -> str:
+        """Setup computation device"""
+        if device == "auto":
+            if torch.cuda.is_available():
+                return "cuda"
+            elif hasattr(torch.backends, 'mps') and torch.backends.mps.is_available():
+                return "mps"
+            return "cpu"
+        return device
+
+    def _load_birefnet_model(self) -> bool:
+        """
+        Lazy load BiRefNet model for memory efficiency.
+        Returns True if model loaded successfully, False otherwise.
+        """
+        if self._birefnet_model is not None:
+            return True
+
+        try:
+            logger.info("📥 Loading BiRefNet model (ZhengPeng7/BiRefNet)...")
+
+            # Load model with fp16 for memory efficiency on GPU
+            dtype = torch.float16 if self.device == "cuda" else torch.float32
+
+            self._birefnet_model = AutoModelForImageSegmentation.from_pretrained(
+                "ZhengPeng7/BiRefNet",
+                trust_remote_code=True,
+                torch_dtype=dtype
+            )
+            self._birefnet_model.to(self.device)
+            self._birefnet_model.eval()
+
+            # Define preprocessing transform
+            self._birefnet_transform = transforms.Compose([
+                transforms.Resize((1024, 1024)),
+                transforms.ToTensor(),
+                transforms.Normalize([0.485, 0.456, 0.406], [0.229, 0.224, 0.225])
+            ])
+
+            logger.info("✅ BiRefNet model loaded successfully")
+            return True
+
+        except Exception as e:
+            logger.error(f"❌ Failed to load BiRefNet: {e}")
+            self._birefnet_model = None
+            self._birefnet_transform = None
+            return False
+
+    def _unload_birefnet_model(self):
+        """Unload BiRefNet model to free memory"""
+        if self._birefnet_model is not None:
+            del self._birefnet_model
+            self._birefnet_model = None
+            self._birefnet_transform = None
+
+            if torch.cuda.is_available():
+                torch.cuda.empty_cache()
+            gc.collect()
+            logger.info("🧹 BiRefNet model unloaded")
+
+    def apply_guided_filter(
+        self,
+        mask: np.ndarray,
+        guide_image: Image.Image,
+        radius: int = 8,
+        eps: float = 0.01
+    ) -> np.ndarray:
+        """
+        Apply guided filter to mask for edge-preserving smoothing.
+        Falls back to Gaussian blur if guided filter is not available.
+
+        Args:
+            mask: Input mask as numpy array (0-255)
+            guide_image: Original image to use as guide
+            radius: Filter radius (larger = more smoothing)
+            eps: Regularization parameter (smaller = more edge-preserving)
+
+        Returns:
+            Filtered mask as numpy array (0-255)
+        """
+        try:
+            # Convert guide image to grayscale
+            guide_gray = np.array(guide_image.convert('L')).astype(np.float32) / 255.0
+            mask_float = mask.astype(np.float32) / 255.0
+
+            logger.info(f"🔧 Applying guided filter (radius={radius}, eps={eps})")
+
+            # Apply guided filter
+            filtered = cv2.ximgproc.guidedFilter(
+                guide=guide_gray,
+                src=mask_float,
+                radius=radius,
+                eps=eps
+            )
+
+            # Convert back to 0-255 range
+            result = (np.clip(filtered, 0, 1) * 255).astype(np.uint8)
+            logger.info("✅ Guided filter applied successfully")
+            return result
+
+        except Exception as e:
+            logger.error(f"❌ Guided filter failed: {e}, using original mask")
+            return mask
+
+    def try_birefnet_mask(self, original_image: Image.Image) -> Optional[Image.Image]:
+        """
+        Generate foreground mask using BiRefNet model.
+        BiRefNet provides high-quality segmentation with clean edges.
+
+        Args:
+            original_image: Input PIL Image
+
+        Returns:
+            PIL Image (L mode) mask or None if failed
+        """
+        try:
+            # Lazy load model
+            if not self._load_birefnet_model():
+                return None
+
+            logger.info("🤖 Starting BiRefNet foreground extraction...")
+            original_size = original_image.size
+
+            # Convert to RGB if needed
+            if original_image.mode != 'RGB':
+                image_rgb = original_image.convert('RGB')
+            else:
+                image_rgb = original_image
+
+            # Preprocess image
+            input_tensor = self._birefnet_transform(image_rgb).unsqueeze(0)
+
+            # Move to device with appropriate dtype
+            if self.device == "cuda":
+                input_tensor = input_tensor.to(self.device, dtype=torch.float16)
+            else:
+                input_tensor = input_tensor.to(self.device)
+
+            # Run inference
+            with torch.no_grad():
+                outputs = self._birefnet_model(input_tensor)
+
+                # BiRefNet outputs a list, get the final prediction
+                if isinstance(outputs, (list, tuple)):
+                    pred = outputs[-1]
+                else:
+                    pred = outputs
+
+                # Sigmoid to get probability map
+                pred = torch.sigmoid(pred)
+
+                # Convert to numpy
+                pred_np = pred.squeeze().cpu().numpy()
+
+            # Convert to 0-255 range
+            mask_array = (pred_np * 255).astype(np.uint8)
+
+            # Resize back to original size
+            mask_pil = Image.fromarray(mask_array, mode='L')
+            mask_pil = mask_pil.resize(original_size, Image.LANCZOS)
+            mask_array = np.array(mask_pil)
+
+            # Quality check
+            mean_val = mask_array.mean()
+            nonzero_ratio = np.count_nonzero(mask_array > 50) / mask_array.size
+
+            logger.info(f"📊 BiRefNet mask stats - Mean: {mean_val:.1f}, Coverage: {nonzero_ratio:.1%}")
+
+            if mean_val < 10:
+                logger.warning("⚠️ BiRefNet mask too weak, falling back")
+                return None
+
+            if nonzero_ratio < 0.03:
+                logger.warning("⚠️ BiRefNet foreground coverage too low, falling back")
+                return None
+
+            # Light post-processing for edge refinement
+            # Use morphological operations to clean up
+            kernel_small = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (3, 3))
+            mask_array = cv2.morphologyEx(mask_array, cv2.MORPH_CLOSE, kernel_small)
+
+            logger.info("✅ BiRefNet mask generation successful!")
+            return Image.fromarray(mask_array, mode='L')
+
+        except torch.cuda.OutOfMemoryError:
+            logger.error("❌ BiRefNet: GPU memory exhausted")
+            self._unload_birefnet_model()
+            return None
+
+        except Exception as e:
+            logger.error(f"❌ BiRefNet mask generation failed: {e}")
+            import traceback
+            logger.error(f"📍 Traceback: {traceback.format_exc()}")
+            return None
+
+    def try_deep_learning_mask(self, original_image: Image.Image) -> Optional[Image.Image]:
+        """
+        Intelligent foreground extraction with model priority:
+        1. BiRefNet (best quality, clean edges)
+        2. U²-Net via rembg (good fallback)
+        3. Return None to trigger traditional methods
+
+        Args:
+            original_image: Input PIL Image
+
+        Returns:
+            PIL Image (L mode) mask or None if all methods failed
+        """
+        # Priority 1: Try BiRefNet first
+        logger.info("🤖 Attempting BiRefNet mask generation...")
+        birefnet_mask = self.try_birefnet_mask(original_image)
+        if birefnet_mask is not None:
+            logger.info("✅ Using BiRefNet generated mask")
+            return birefnet_mask
+
+        # Priority 2: Fallback to rembg (U²-Net)
+        logger.info("🔄 BiRefNet unavailable/failed, trying rembg...")
+        try:
+            logger.info("🤖 Starting rembg foreground extraction")
+
+            # Try u2net first (better for cartoons/objects like Snoopy)
+            try:
+                session = new_session('u2net')
+                logger.info("✅ Using u2net model")
+            except Exception as e:
+                logger.warning(f"u2net failed ({e}), trying u2net_human_seg")
+                try:
+                    session = new_session('u2net_human_seg')
+                    logger.info("✅ Using u2net_human_seg model")
+                except Exception as e2:
+                    logger.error(f"All rembg models failed: {e2}")
+                    return None
+
+            # Convert image to bytes for rembg
+            img_byte_arr = io.BytesIO()
+            original_image.save(img_byte_arr, format='PNG')
+            img_byte_arr = img_byte_arr.getvalue()
+            logger.info(f"📷 Image size: {len(img_byte_arr)} bytes")
+
+            # Perform background removal
+            result = remove(img_byte_arr, session=session)
+            result_img = Image.open(io.BytesIO(result)).convert('RGBA')
+            alpha_channel = result_img.split()[-1]
+            alpha_array = np.array(alpha_channel)
+
+            logger.info(f"📊 Raw alpha stats - Mean: {alpha_array.mean():.1f}, Min: {alpha_array.min()}, Max: {alpha_array.max()}")
+
+            # Step 1: Light smoothing to reduce noise but preserve edges
+            alpha_smoothed = cv2.GaussianBlur(alpha_array, (3, 3), 0.8)
+
+            # Step 2: Contrast stretching to utilize full range
+            alpha_stretched = cv2.normalize(alpha_smoothed, None, 0, 255, cv2.NORM_MINMAX)
+
+            # Step 3: CRITICAL FIX - More aggressive foreground preservation
+            # Instead of hard threshold, use adaptive approach
+
+            # Find the main subject area (high confidence regions)
+            high_confidence = alpha_stretched > 180
+            medium_confidence = (alpha_stretched > 60) & (alpha_stretched <= 180)
+            low_confidence = (alpha_stretched > 15) & (alpha_stretched <= 60)
+
+            # Create final mask with better extremity handling
+            final_alpha = np.zeros_like(alpha_stretched)
+
+            # High confidence areas - keep at full opacity
+            final_alpha[high_confidence] = 255
+
+            # Medium confidence - boost significantly 
+            final_alpha[medium_confidence] = np.clip(alpha_stretched[medium_confidence] * 1.8, 200, 255)
+
+            # Low confidence - moderate boost (catches faint extremities)
+            final_alpha[low_confidence] = np.clip(alpha_stretched[low_confidence] * 2.5, 120, 199)
+
+            # Morphological operations to connect disconnected parts (hands, feet, tail)
+            kernel_small = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (3, 3))
+            kernel_medium = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (5, 5))
+
+            # Close small gaps (helps connect separated body parts)
+            final_alpha = cv2.morphologyEx(final_alpha, cv2.MORPH_CLOSE, kernel_small, iterations=1)
+
+            # Light dilation to ensure nothing gets cut off
+            final_alpha = cv2.dilate(final_alpha, kernel_small, iterations=1)
+
+            logger.info(f"📊 Final alpha stats - Mean: {final_alpha.mean():.1f}, Min: {final_alpha.min()}, Max: {final_alpha.max()}")
+
+            # Quality check - but be more lenient for cartoon characters
+            if final_alpha.mean() < 10:
+                logger.warning("⚠️ Alpha still too weak, falling back to traditional method")
+                return None
+
+            # Enhanced post-processing for cartoon characters
+            is_cartoon = self._detect_cartoon_character(original_image, final_alpha)
+
+            if is_cartoon:
+                logger.info("🎭 Detected cartoon/character image, applying specialized processing")
+                final_alpha = self._enhance_cartoon_mask(original_image, final_alpha)
+
+            # Count non-zero pixels to ensure we have substantial foreground
+            foreground_pixels = np.count_nonzero(final_alpha > 50)
+            total_pixels = final_alpha.size
+            foreground_ratio = foreground_pixels / total_pixels
+            logger.info(f"📊 Foreground coverage: {foreground_ratio:.1%} of image")
+
+            if foreground_ratio < 0.05:  # Less than 5% is probably too little
+                logger.warning("⚠️ Very low foreground coverage, falling back to traditional method")
+                return None
+
+            mask = Image.fromarray(final_alpha.astype(np.uint8), mode='L')
+            logger.info("✅ Enhanced rembg mask generation successful!")
+            return mask
+
+        except Exception as e:
+            logger.error(f"❌ Deep learning mask extraction failed: {e}")
+            return None
+
+    def _detect_cartoon_character(self, original_image: Image.Image, alpha_mask: np.ndarray) -> bool:
+        """
+        Detect if image is cartoon/line art (heuristic approach)
+        """
+        try:
+            img_array = np.array(original_image.convert('RGB'))
+            gray = cv2.cvtColor(img_array, cv2.COLOR_RGB2GRAY)
+
+            # Calculate edge density (cartoons usually have more clear edges)
+            edges = cv2.Canny(gray, 50, 150)
+            edge_density = np.count_nonzero(edges) / max(edges.size, 1)  # Avoid division by zero
+
+            # Calculate color complexity (cartoons usually have fewer colors) - optimize memory usage
+            h, w, c = img_array.shape
+            if h * w > 100000:  # If image is too large, resize for processing
+                small_img = cv2.resize(img_array, (200, 200))
+            else:
+                small_img = img_array
+
+            unique_colors = len(np.unique(small_img.reshape(-1, 3), axis=0))
+            total_pixels = small_img.shape[0] * small_img.shape[1]
+            color_simplicity = unique_colors < (total_pixels * 0.1)
+
+            # Check for obvious black outlines
+            dark_pixels_ratio = np.count_nonzero(gray < 50) / max(gray.size, 1)  # Avoid division by zero
+            has_black_outline = dark_pixels_ratio > 0.05
+
+            # Comprehensive judgment: high edge density + color simplicity + black outline = likely cartoon
+            is_cartoon = (edge_density > 0.05) and (color_simplicity or has_black_outline)
+
+            logger.info(f"🔍 Cartoon detection - Edge density: {edge_density:.3f}, Color simplicity: {color_simplicity}, Black outline: {has_black_outline} -> Cartoon: {is_cartoon}")
+            return is_cartoon
+
+        except Exception as e:
+            import traceback
+            logger.error(f"❌ Cartoon detection failed: {e}")
+            logger.error(f"📍 Traceback: {traceback.format_exc()}")
+            print(f"❌ CARTOON DETECTION ERROR: {e}")
+            print(f"Traceback: {traceback.format_exc()}")
+            return False
+
+    def _enhance_cartoon_mask(self, original_image: Image.Image, alpha_mask: np.ndarray) -> np.ndarray:
+        """
+        Enhanced mask processing for cartoon characters
+        """
+        try:
+            img_array = np.array(original_image.convert('RGB'))
+            gray = cv2.cvtColor(img_array, cv2.COLOR_RGB2GRAY)
+            enhanced_alpha = alpha_mask.copy()
+
+            # Step 1: Black outline enhancement - find black outlines and enhance their alpha
+            th_dark = 80  # Adjustable parameter: black threshold
+            black_outline = gray < th_dark
+
+            # Dilate black outline region by 1px
+            kernel_dilate = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (3, 3))  # Adjustable parameter: dilation kernel size
+            black_outline_dilated = cv2.dilate(black_outline.astype(np.uint8), kernel_dilate, iterations=1)
+
+            # Set black outline region alpha directly to 255
+            enhanced_alpha[black_outline_dilated > 0] = 255
+            logger.info(f"🖤 Black outline enhanced: {np.count_nonzero(black_outline_dilated)} pixels")
+
+            # Step 2: Simplified internal enhancement - process white fill areas within outlines
+            # Find high confidence regions (alpha ≥ 160)
+            high_confidence = enhanced_alpha >= 160
+
+            # Apply close operation on high confidence regions to connect separated parts
+            kernel_close = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (5, 5))  # Adjustable parameter: close kernel size
+            high_confidence_closed = cv2.morphologyEx(high_confidence.astype(np.uint8), cv2.MORPH_CLOSE, kernel_close, iterations=1)
+
+            # Simplified approach: directly enhance medium confidence regions without complex flood fill
+            # Find medium/low confidence regions surrounded by high confidence regions
+            medium_confidence = (enhanced_alpha >= 80) & (enhanced_alpha < 160)
+
+            # Dilate high confidence region to include more internal areas
+            kernel_dilate_internal = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (7, 7))
+            high_confidence_expanded = cv2.dilate(high_confidence_closed, kernel_dilate_internal, iterations=1)
+
+            # Medium confidence pixels within expanded high confidence areas are considered internal fill
+            internal_fill_regions = medium_confidence & (high_confidence_expanded > 0)
+
+            # Enhance alpha of these internal fill regions to at least 220
+            min_alpha_for_fill = 220  # Adjustable parameter: minimum alpha for internal fill
+            enhanced_alpha[internal_fill_regions] = np.maximum(enhanced_alpha[internal_fill_regions], min_alpha_for_fill)
+
+            logger.info(f"🤍 Internal fill regions enhanced: {np.count_nonzero(internal_fill_regions)} pixels")
+            logger.info(f"📊 Enhanced alpha stats - Mean: {enhanced_alpha.mean():.1f}, Min: {enhanced_alpha.min()}, Max: {enhanced_alpha.max()}")
+
+            return enhanced_alpha
+
+        except Exception as e:
+            import traceback
+            logger.error(f"❌ Cartoon mask enhancement failed: {e}")
+            logger.error(f"📍 Traceback: {traceback.format_exc()}")
+            print(f"❌ CARTOON MASK ENHANCEMENT ERROR: {e}")
+            print(f"Traceback: {traceback.format_exc()}")
+            return alpha_mask
+
+    def _adjust_mask_for_scene_focus(self, mask: Image.Image, original_image: Image.Image) -> Image.Image:
+        """
+        Adjust mask for scene focus mode to include nearby objects like chairs, furniture
+        """
+        try:
+            logger.info("🏠 Adjusting mask for scene focus mode...")
+
+            mask_array = np.array(mask)
+            img_array = np.array(original_image.convert('RGB'))
+
+            # Expand mask to include nearby objects
+            # Use larger dilation kernel to include furniture/objects
+            kernel_large = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (15, 15))
+            expanded_mask = cv2.dilate(mask_array, kernel_large, iterations=2)
+
+            # Find contours in the expanded area to detect objects
+            gray = cv2.cvtColor(img_array, cv2.COLOR_RGB2GRAY)
+            edges = cv2.Canny(gray, 30, 100)
+
+            # Apply edge detection only in the expanded region
+            expanded_region = (expanded_mask > 0) & (mask_array == 0)
+            object_edges = np.zeros_like(edges)
+            object_edges[expanded_region] = edges[expanded_region]
+
+            # Close gaps to form complete objects
+            kernel_close = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (7, 7))
+            object_mask = cv2.morphologyEx(object_edges, cv2.MORPH_CLOSE, kernel_close)
+            object_mask = cv2.dilate(object_mask, kernel_close, iterations=1)
+
+            # Combine with original mask
+            final_mask = np.maximum(mask_array, object_mask)
+
+            logger.info("✅ Scene focus adjustment completed")
+            return Image.fromarray(final_mask)
+
+        except Exception as e:
+            logger.error(f"❌ Scene focus adjustment failed: {e}")
+            return mask
+
+    def create_gradient_based_mask(self, original_image: Image.Image, mode: str = "center", focus_mode: str = "person") -> Image.Image:
+        """
+        Intelligent foreground extraction: prioritize deep learning models, fallback to traditional methods
+        Focus mode: 'person' for tight crop around person, 'scene' for including nearby objects
+        """
+        width, height = original_image.size
+        logger.info(f"🎯 Creating mask for {width}x{height} image, mode: {mode}, focus: {focus_mode}")
+
+        if mode == "center":
+            # Try using deep learning models for intelligent foreground extraction
+            logger.info("🤖 Attempting deep learning mask generation...")
+            dl_mask = self.try_deep_learning_mask(original_image)
+            if dl_mask is not None:
+                logger.info("✅ Using deep learning generated mask")
+                # Apply focus mode adjustments to deep learning mask
+                if focus_mode == "scene":
+                    dl_mask = self._adjust_mask_for_scene_focus(dl_mask, original_image)
+                return dl_mask
+
+            # Fallback to traditional method
+            logger.info("🔄 Deep learning failed, using traditional gradient-based method")
+            img_array = np.array(original_image.convert('RGB'))
+            gray = cv2.cvtColor(img_array, cv2.COLOR_RGB2GRAY)
+
+            # First-order derivatives: use Sobel operator for edge detection
+            grad_x = cv2.Sobel(gray, cv2.CV_64F, 1, 0, ksize=3)
+            grad_y = cv2.Sobel(gray, cv2.CV_64F, 0, 1, ksize=3)
+            gradient_magnitude = np.sqrt(grad_x**2 + grad_y**2)
+
+            # Second-order derivatives: use Laplacian operator for texture change detection
+            laplacian = cv2.Laplacian(gray, cv2.CV_64F, ksize=3)
+            laplacian_abs = np.abs(laplacian)
+
+            # Combine first and second order derivatives
+            combined_edges = gradient_magnitude * 0.7 + laplacian_abs * 0.3
+            combined_edges = (combined_edges / np.max(combined_edges)) * 255
+
+            # Threshold processing to find strong edges
+            _, edge_binary = cv2.threshold(combined_edges.astype(np.uint8), 20, 255, cv2.THRESH_BINARY)
+
+            # Morphological operations to connect edges
+            kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (5, 5))
+            edge_binary = cv2.morphologyEx(edge_binary, cv2.MORPH_CLOSE, kernel)
+
+            # Find contours and create mask
+            contours, _ = cv2.findContours(edge_binary, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+
+            if contours:
+                # Find largest contour (main subject)
+                largest_contour = max(contours, key=cv2.contourArea)
+                contour_mask = np.zeros((height, width), dtype=np.uint8)
+                cv2.fillPoly(contour_mask, [largest_contour], 255)
+
+                # Create foreground enhancement mask: specially protect dark regions
+                dark_mask = (gray < 90).astype(np.uint8) * 255
+                morph_kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (7, 7))
+                dark_mask = cv2.morphologyEx(dark_mask, cv2.MORPH_CLOSE, morph_kernel, iterations=1)
+                dark_mask = cv2.dilate(dark_mask, morph_kernel, iterations=2)
+                contour_mask = cv2.bitwise_or(contour_mask, dark_mask)
+
+                # Get core foreground: clean holes and fill gaps
+                close_kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (7, 7))
+                core_mask = cv2.morphologyEx(contour_mask, cv2.MORPH_CLOSE, close_kernel, iterations=1)
+
+                open_kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (3, 3))
+                core_mask = cv2.morphologyEx(core_mask, cv2.MORPH_OPEN, open_kernel, iterations=1)
+
+                # Convert to binary core (0/255)
+                _, core_binary = cv2.threshold(core_mask, 127, 255, cv2.THRESH_BINARY)
+
+                # Keep only slight dilation to avoid foreground being eaten
+                dilate_kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (3, 3))
+                core_binary = cv2.dilate(core_binary, dilate_kernel, iterations=1)
+
+                # Distance transform feathering: shrink feathering range for sharp edges
+                FEATHER_PX = 4
+
+                # Calculate distance transform
+                core_float = core_binary.astype(np.float32) / 255.0
+                distances = cv2.distanceTransform((1 - core_float).astype(np.uint8), cv2.DIST_L2, 5)
+
+                # Create feathering mask: 0→FEATHER_PX linear mapping to 1→0
+                feather_mask = np.ones_like(distances)
+                edge_region = (distances > 0) & (distances <= FEATHER_PX)
+                feather_mask[edge_region] = 1.0 - (distances[edge_region] / FEATHER_PX)
+                feather_mask[distances > FEATHER_PX] = 0.0
+
+                # Apply double-smoothstep curve: make transition steeper, reduce semi-transparent halos
+                def double_smoothstep(t):
+                    t = np.clip(t, 0, 1)
+                    s1 = t * t * (3 - 2 * t)
+                    return s1 * s1 * (3 - 2 * s1)  # Equivalent to t^3 (10 - 15t + 6t^2)
+
+                # Combine core with feathering: core area keeps 255, edges use double_smoothstep feathering
+                final_alpha = np.zeros_like(distances)
+                final_alpha[core_binary > 127] = 1.0  # Core area
+                final_alpha[edge_region] = double_smoothstep(feather_mask[edge_region])  # Feathering area
+
+                # Convert to 0-255 range
+                final_mask = (final_alpha * 255).astype(np.uint8)
+
+                # Apply guided filter for edge-preserving smoothing
+                final_mask = self.apply_guided_filter(final_mask, original_image, radius=8, eps=0.01)
+
+                mask = Image.fromarray(final_mask)
+            else:
+                # Backup plan: use large ellipse
+                mask = Image.new('L', (width, height), 0)
+                draw = ImageDraw.Draw(mask)
+                center_x, center_y = width // 2, height // 2
+                width_radius = int(width * 0.45)
+                height_radius = int(width * 0.48)
+                draw.ellipse([
+                    center_x - width_radius, center_y - height_radius,
+                    center_x + width_radius, center_y + height_radius
+                ], fill=255)
+                # Apply guided filter instead of Gaussian blur
+                mask_array = np.array(mask)
+                mask_array = self.apply_guided_filter(mask_array, original_image, radius=10, eps=0.02)
+                mask = Image.fromarray(mask_array)
+
+        elif mode == "left_half":
+            # Keep original logic unchanged - ensure Snoopy and other functions work normally
+            mask = Image.new('L', (width, height), 0)
+            mask_array = np.array(mask)
+            mask_array[:, :width//2] = 255
+
+            transition_zone = width // 10
+            for i in range(transition_zone):
+                x_pos = width//2 + i
+                if x_pos < width:
+                    alpha = 255 * (1 - i / transition_zone)
+                    mask_array[:, x_pos] = int(alpha)
+
+            mask = Image.fromarray(mask_array)
+
+        elif mode == "right_half":
+            # Keep original logic unchanged - ensure Snoopy and other functions work normally
+            mask = Image.new('L', (width, height), 0)
+            mask_array = np.array(mask)
+            mask_array[:, width//2:] = 255
+
+            transition_zone = width // 10
+            for i in range(transition_zone):
+                x_pos = width//2 - i - 1
+                if x_pos >= 0:
+                    alpha = 255 * (1 - i / transition_zone)
+                    mask_array[:, x_pos] = int(alpha)
+
+            mask = Image.fromarray(mask_array)
+
+        elif mode == "full":
+            mask = Image.new('L', (width, height), 0)
+            draw = ImageDraw.Draw(mask)
+            center_x, center_y = width // 2, height // 2
+            radius = min(width, height) // 8
+
+            draw.ellipse([
+                center_x - radius, center_y - radius,
+                center_x + radius, center_y + radius
+            ], fill=255)
+
+            mask = mask.filter(ImageFilter.GaussianBlur(radius=5))
+
+        return mask

model_manager.py

@@ -0,0 +1,293 @@
+import logging
+import gc
+import time
+from typing import Dict, Any, Optional, Callable
+from dataclasses import dataclass, field
+from threading import Lock
+import torch
+
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.INFO)
+
+
+@dataclass
+class ModelInfo:
+    """Information about a registered model."""
+    name: str
+    loader: Callable[[], Any]
+    is_critical: bool = False  # Critical models are not unloaded under memory pressure
+    estimated_memory_gb: float = 0.0
+    is_loaded: bool = False
+    last_used: float = 0.0
+    model_instance: Any = None
+
+
+class ModelManager:
+    """
+    Singleton model manager for unified model lifecycle management.
+    Handles lazy loading, caching, and intelligent memory management.
+    """
+
+    _instance = None
+    _lock = Lock()
+
+    def __new__(cls):
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = super().__new__(cls)
+                    cls._instance._initialized = False
+        return cls._instance
+
+    def __init__(self):
+        if self._initialized:
+            return
+
+        self._models: Dict[str, ModelInfo] = {}
+        self._memory_threshold = 0.80  # Trigger cleanup at 80% GPU memory usage
+        self._device = self._detect_device()
+
+        logger.info(f"🔧 ModelManager initialized on {self._device}")
+        self._initialized = True
+
+    def _detect_device(self) -> str:
+        """Detect best available device."""
+        if torch.cuda.is_available():
+            return "cuda"
+        elif hasattr(torch.backends, 'mps') and torch.backends.mps.is_available():
+            return "mps"
+        return "cpu"
+
+    def register_model(
+        self,
+        name: str,
+        loader: Callable[[], Any],
+        is_critical: bool = False,
+        estimated_memory_gb: float = 0.0
+    ):
+        """
+        Register a model for managed loading.
+
+        Args:
+            name: Unique model identifier
+            loader: Callable that returns the loaded model
+            is_critical: If True, model won't be unloaded under memory pressure
+            estimated_memory_gb: Estimated GPU memory usage in GB
+        """
+        if name in self._models:
+            logger.warning(f"⚠️ Model '{name}' already registered, updating")
+
+        self._models[name] = ModelInfo(
+            name=name,
+            loader=loader,
+            is_critical=is_critical,
+            estimated_memory_gb=estimated_memory_gb,
+            is_loaded=False,
+            last_used=0.0,
+            model_instance=None
+        )
+        logger.info(f"📝 Registered model: {name} (critical={is_critical}, ~{estimated_memory_gb:.1f}GB)")
+
+    def load_model(self, name: str) -> Any:
+        """
+        Load a model by name. Returns cached instance if already loaded.
+
+        Args:
+            name: Model identifier
+
+        Returns:
+            Loaded model instance
+
+        Raises:
+            KeyError: If model not registered
+            RuntimeError: If loading fails
+        """
+        if name not in self._models:
+            raise KeyError(f"Model '{name}' not registered")
+
+        model_info = self._models[name]
+
+        # Return cached instance
+        if model_info.is_loaded and model_info.model_instance is not None:
+            model_info.last_used = time.time()
+            logger.debug(f"📦 Using cached model: {name}")
+            return model_info.model_instance
+
+        # Check memory pressure before loading
+        self.check_memory_pressure()
+
+        # Load the model
+        try:
+            logger.info(f"📥 Loading model: {name}")
+            start_time = time.time()
+
+            model_instance = model_info.loader()
+
+            model_info.model_instance = model_instance
+            model_info.is_loaded = True
+            model_info.last_used = time.time()
+
+            load_time = time.time() - start_time
+            logger.info(f"✅ Model '{name}' loaded in {load_time:.1f}s")
+
+            return model_instance
+
+        except Exception as e:
+            logger.error(f"❌ Failed to load model '{name}': {e}")
+            raise RuntimeError(f"Model loading failed: {e}")
+
+    def unload_model(self, name: str):
+        """
+        Unload a specific model to free memory.
+
+        Args:
+            name: Model identifier
+        """
+        if name not in self._models:
+            return
+
+        model_info = self._models[name]
+
+        if not model_info.is_loaded:
+            return
+
+        try:
+            logger.info(f"🗑️ Unloading model: {name}")
+
+            # Delete model instance
+            if model_info.model_instance is not None:
+                del model_info.model_instance
+
+            model_info.model_instance = None
+            model_info.is_loaded = False
+
+            # Cleanup
+            gc.collect()
+            if torch.cuda.is_available():
+                torch.cuda.empty_cache()
+
+            logger.info(f"✅ Model '{name}' unloaded")
+
+        except Exception as e:
+            logger.error(f"❌ Error unloading model '{name}': {e}")
+
+    def check_memory_pressure(self) -> bool:
+        """
+        Check GPU memory usage and unload least-used non-critical models if needed.
+
+        Returns:
+            True if cleanup was performed
+        """
+        if not torch.cuda.is_available():
+            return False
+
+        allocated = torch.cuda.memory_allocated() / 1024**3
+        total = torch.cuda.get_device_properties(0).total_memory / 1024**3
+        usage_ratio = allocated / total
+
+        if usage_ratio < self._memory_threshold:
+            return False
+
+        logger.warning(f"⚠️ Memory pressure detected: {usage_ratio:.1%} used")
+
+        # Find non-critical models sorted by last used time
+        unloadable = [
+            (name, info) for name, info in self._models.items()
+            if info.is_loaded and not info.is_critical
+        ]
+        unloadable.sort(key=lambda x: x[1].last_used)
+
+        # Unload oldest non-critical models
+        cleaned = False
+        for name, info in unloadable:
+            self.unload_model(name)
+            cleaned = True
+
+            # Re-check memory
+            new_ratio = torch.cuda.memory_allocated() / torch.cuda.get_device_properties(0).total_memory
+            if new_ratio < self._memory_threshold * 0.7:  # Target 70% of threshold
+                break
+
+        return cleaned
+
+    def force_cleanup(self):
+        """Force cleanup all non-critical models and clear caches."""
+        logger.info("🧹 Force cleanup initiated")
+
+        # Unload all non-critical models
+        for name, info in self._models.items():
+            if info.is_loaded and not info.is_critical:
+                self.unload_model(name)
+
+        # Aggressive garbage collection
+        for _ in range(5):
+            gc.collect()
+
+        if torch.cuda.is_available():
+            torch.cuda.empty_cache()
+            torch.cuda.ipc_collect()
+            torch.cuda.synchronize()
+
+        logger.info("✅ Force cleanup completed")
+
+    def get_memory_status(self) -> Dict[str, Any]:
+        """
+        Get detailed memory status.
+
+        Returns:
+            Dictionary with memory statistics
+        """
+        status = {
+            "device": self._device,
+            "models": {},
+            "total_estimated_gb": 0.0
+        }
+
+        # Model status
+        for name, info in self._models.items():
+            status["models"][name] = {
+                "loaded": info.is_loaded,
+                "critical": info.is_critical,
+                "estimated_gb": info.estimated_memory_gb,
+                "last_used": info.last_used
+            }
+            if info.is_loaded:
+                status["total_estimated_gb"] += info.estimated_memory_gb
+
+        # GPU memory
+        if torch.cuda.is_available():
+            allocated = torch.cuda.memory_allocated() / 1024**3
+            total = torch.cuda.get_device_properties(0).total_memory / 1024**3
+            cached = torch.cuda.memory_reserved() / 1024**3
+
+            status["gpu"] = {
+                "allocated_gb": round(allocated, 2),
+                "total_gb": round(total, 2),
+                "cached_gb": round(cached, 2),
+                "free_gb": round(total - allocated, 2),
+                "usage_percent": round((allocated / total) * 100, 1)
+            }
+
+        return status
+
+    def get_loaded_models(self) -> list:
+        """Get list of currently loaded model names."""
+        return [name for name, info in self._models.items() if info.is_loaded]
+
+    def is_model_loaded(self, name: str) -> bool:
+        """Check if a specific model is loaded."""
+        if name not in self._models:
+            return False
+        return self._models[name].is_loaded
+
+
+# Global singleton instance
+_model_manager = None
+
+
+def get_model_manager() -> ModelManager:
+    """Get the global ModelManager singleton instance."""
+    global _model_manager
+    if _model_manager is None:
+        _model_manager = ModelManager()
+    return _model_manager

quality_checker.py

@@ -0,0 +1,409 @@
+import logging
+import numpy as np
+import cv2
+from PIL import Image
+from typing import Dict, Any, Tuple, Optional
+from dataclasses import dataclass
+
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.INFO)
+
+
+@dataclass
+class QualityResult:
+    """Result of a quality check."""
+    score: float  # 0-100
+    passed: bool
+    issue: str
+    details: Dict[str, Any]
+
+
+class QualityChecker:
+    """
+    Automated quality validation system for generated images.
+    Provides checks for mask coverage, edge continuity, and color harmony.
+    """
+
+    # Quality thresholds
+    THRESHOLD_PASS = 70
+    THRESHOLD_WARNING = 50
+
+    def __init__(self, strictness: str = "standard"):
+        """
+        Initialize QualityChecker.
+
+        Args:
+            strictness: Quality check strictness level
+                       "lenient" - Only check fatal issues
+                       "standard" - All checks with moderate thresholds
+                       "strict" - High standards required
+        """
+        self.strictness = strictness
+        self._set_thresholds()
+
+    def _set_thresholds(self):
+        """Set quality thresholds based on strictness level."""
+        if self.strictness == "lenient":
+            self.min_coverage = 0.03  # 3%
+            self.min_edge_score = 40
+            self.min_harmony_score = 40
+        elif self.strictness == "strict":
+            self.min_coverage = 0.10  # 10%
+            self.min_edge_score = 75
+            self.min_harmony_score = 75
+        else:  # standard
+            self.min_coverage = 0.05  # 5%
+            self.min_edge_score = 60
+            self.min_harmony_score = 60
+
+    def check_mask_coverage(self, mask: Image.Image) -> QualityResult:
+        """
+        Verify mask coverage is adequate.
+
+        Args:
+            mask: Grayscale mask image (L mode)
+
+        Returns:
+            QualityResult with coverage analysis
+        """
+        try:
+            mask_array = np.array(mask.convert('L'))
+            height, width = mask_array.shape
+            total_pixels = height * width
+
+            # Count foreground pixels
+            fg_pixels = np.count_nonzero(mask_array > 127)
+            coverage_ratio = fg_pixels / total_pixels
+
+            # Check for isolated small regions (noise)
+            _, binary = cv2.threshold(mask_array, 127, 255, cv2.THRESH_BINARY)
+            num_labels, labels, stats, _ = cv2.connectedComponentsWithStats(binary, connectivity=8)
+
+            # Count significant regions (> 1% of image)
+            min_region_size = total_pixels * 0.01
+            significant_regions = sum(1 for i in range(1, num_labels)
+                                     if stats[i, cv2.CC_STAT_AREA] > min_region_size)
+
+            # Calculate fragmentation (many small regions = bad)
+            fragmentation_penalty = max(0, (num_labels - 1 - significant_regions) * 2)
+
+            # Score calculation
+            coverage_score = min(100, coverage_ratio * 200)  # 50% coverage = 100 score
+            final_score = max(0, coverage_score - fragmentation_penalty)
+
+            # Determine pass/fail
+            passed = coverage_ratio >= self.min_coverage and significant_regions >= 1
+            issue = ""
+
+            if coverage_ratio < self.min_coverage:
+                issue = f"Low foreground coverage ({coverage_ratio:.1%})"
+            elif significant_regions == 0:
+                issue = "No significant foreground regions detected"
+            elif fragmentation_penalty > 20:
+                issue = f"Fragmented mask with {num_labels - 1} isolated regions"
+
+            return QualityResult(
+                score=final_score,
+                passed=passed,
+                issue=issue,
+                details={
+                    "coverage_ratio": coverage_ratio,
+                    "foreground_pixels": fg_pixels,
+                    "total_regions": num_labels - 1,
+                    "significant_regions": significant_regions
+                }
+            )
+
+        except Exception as e:
+            logger.error(f"❌ Mask coverage check failed: {e}")
+            return QualityResult(score=0, passed=False, issue=str(e), details={})
+
+    def check_edge_continuity(self, mask: Image.Image) -> QualityResult:
+        """
+        Check if mask edges are continuous and smooth.
+
+        Args:
+            mask: Grayscale mask image
+
+        Returns:
+            QualityResult with edge analysis
+        """
+        try:
+            mask_array = np.array(mask.convert('L'))
+
+            # Find edges using morphological gradient
+            kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (3, 3))
+            gradient = cv2.morphologyEx(mask_array, cv2.MORPH_GRADIENT, kernel)
+
+            # Get edge pixels
+            edge_pixels = gradient > 20
+            edge_count = np.count_nonzero(edge_pixels)
+
+            if edge_count == 0:
+                return QualityResult(
+                    score=50,
+                    passed=False,
+                    issue="No edges detected in mask",
+                    details={"edge_count": 0}
+                )
+
+            # Check edge smoothness using Laplacian
+            laplacian = cv2.Laplacian(mask_array, cv2.CV_64F)
+            edge_laplacian = np.abs(laplacian[edge_pixels])
+
+            # High Laplacian values indicate jagged edges
+            smoothness = 100 - min(100, np.std(edge_laplacian) * 0.5)
+
+            # Check for gaps in edges
+            # Dilate and erode to find disconnections
+            dilated = cv2.dilate(gradient, kernel, iterations=1)
+            eroded = cv2.erode(dilated, kernel, iterations=1)
+            gaps = cv2.subtract(dilated, eroded)
+            gap_ratio = np.count_nonzero(gaps) / max(edge_count, 1)
+
+            # Calculate final score
+            gap_penalty = min(40, gap_ratio * 100)
+            final_score = max(0, smoothness - gap_penalty)
+
+            passed = final_score >= self.min_edge_score
+            issue = ""
+
+            if final_score < self.min_edge_score:
+                if smoothness < 60:
+                    issue = "Jagged or rough edges detected"
+                elif gap_ratio > 0.3:
+                    issue = "Discontinuous edges with gaps"
+                else:
+                    issue = "Poor edge quality"
+
+            return QualityResult(
+                score=final_score,
+                passed=passed,
+                issue=issue,
+                details={
+                    "edge_count": edge_count,
+                    "smoothness": smoothness,
+                    "gap_ratio": gap_ratio
+                }
+            )
+
+        except Exception as e:
+            logger.error(f"❌ Edge continuity check failed: {e}")
+            return QualityResult(score=0, passed=False, issue=str(e), details={})
+
+    def check_color_harmony(
+        self,
+        foreground: Image.Image,
+        background: Image.Image,
+        mask: Image.Image
+    ) -> QualityResult:
+        """
+        Evaluate color harmony between foreground and background.
+
+        Args:
+            foreground: Original foreground image
+            background: Generated background image
+            mask: Combination mask
+
+        Returns:
+            QualityResult with harmony analysis
+        """
+        try:
+            fg_array = np.array(foreground.convert('RGB'))
+            bg_array = np.array(background.convert('RGB'))
+            mask_array = np.array(mask.convert('L'))
+
+            # Get foreground and background regions
+            fg_region = mask_array > 127
+            bg_region = mask_array <= 127
+
+            if not np.any(fg_region) or not np.any(bg_region):
+                return QualityResult(
+                    score=50,
+                    passed=True,
+                    issue="Cannot analyze harmony - insufficient regions",
+                    details={}
+                )
+
+            # Convert to LAB for perceptual analysis
+            fg_lab = cv2.cvtColor(fg_array, cv2.COLOR_RGB2LAB).astype(np.float32)
+            bg_lab = cv2.cvtColor(bg_array, cv2.COLOR_RGB2LAB).astype(np.float32)
+
+            # Calculate average colors
+            fg_avg_l = np.mean(fg_lab[fg_region, 0])
+            fg_avg_a = np.mean(fg_lab[fg_region, 1])
+            fg_avg_b = np.mean(fg_lab[fg_region, 2])
+
+            bg_avg_l = np.mean(bg_lab[bg_region, 0])
+            bg_avg_a = np.mean(bg_lab[bg_region, 1])
+            bg_avg_b = np.mean(bg_lab[bg_region, 2])
+
+            # Calculate color differences
+            delta_l = abs(fg_avg_l - bg_avg_l)
+            delta_a = abs(fg_avg_a - bg_avg_a)
+            delta_b = abs(fg_avg_b - bg_avg_b)
+
+            # Overall color difference (Delta E approximation)
+            delta_e = np.sqrt(delta_l**2 + delta_a**2 + delta_b**2)
+
+            # Score calculation
+            # Moderate difference is good (20-60 Delta E)
+            # Too similar or too different is problematic
+            if delta_e < 10:
+                harmony_score = 60  # Too similar, foreground may get lost
+                issue = "Foreground and background colors too similar"
+            elif delta_e > 80:
+                harmony_score = 50  # Too different, may look unnatural
+                issue = "High color contrast may look unnatural"
+            elif 20 <= delta_e <= 60:
+                harmony_score = 100  # Ideal range
+                issue = ""
+            else:
+                harmony_score = 80
+                issue = ""
+
+            # Check for extreme contrast (very dark fg on very bright bg or vice versa)
+            brightness_contrast = abs(fg_avg_l - bg_avg_l)
+            if brightness_contrast > 100:
+                harmony_score = max(40, harmony_score - 30)
+                issue = "Extreme brightness contrast between foreground and background"
+
+            passed = harmony_score >= self.min_harmony_score
+
+            return QualityResult(
+                score=harmony_score,
+                passed=passed,
+                issue=issue,
+                details={
+                    "delta_e": delta_e,
+                    "delta_l": delta_l,
+                    "delta_a": delta_a,
+                    "delta_b": delta_b,
+                    "fg_luminance": fg_avg_l,
+                    "bg_luminance": bg_avg_l
+                }
+            )
+
+        except Exception as e:
+            logger.error(f"❌ Color harmony check failed: {e}")
+            return QualityResult(score=0, passed=False, issue=str(e), details={})
+
+    def run_all_checks(
+        self,
+        foreground: Image.Image,
+        background: Image.Image,
+        mask: Image.Image,
+        combined: Optional[Image.Image] = None
+    ) -> Dict[str, Any]:
+        """
+        Run all quality checks and return comprehensive results.
+
+        Args:
+            foreground: Original foreground image
+            background: Generated background
+            mask: Combination mask
+            combined: Final combined image (optional)
+
+        Returns:
+            Dictionary with all check results and overall score
+        """
+        logger.info("🔍 Running quality checks...")
+
+        results = {
+            "checks": {},
+            "overall_score": 0,
+            "passed": True,
+            "warnings": [],
+            "errors": []
+        }
+
+        # Run individual checks
+        coverage_result = self.check_mask_coverage(mask)
+        results["checks"]["mask_coverage"] = {
+            "score": coverage_result.score,
+            "passed": coverage_result.passed,
+            "issue": coverage_result.issue,
+            "details": coverage_result.details
+        }
+
+        edge_result = self.check_edge_continuity(mask)
+        results["checks"]["edge_continuity"] = {
+            "score": edge_result.score,
+            "passed": edge_result.passed,
+            "issue": edge_result.issue,
+            "details": edge_result.details
+        }
+
+        harmony_result = self.check_color_harmony(foreground, background, mask)
+        results["checks"]["color_harmony"] = {
+            "score": harmony_result.score,
+            "passed": harmony_result.passed,
+            "issue": harmony_result.issue,
+            "details": harmony_result.details
+        }
+
+        # Calculate overall score (weighted average)
+        weights = {
+            "mask_coverage": 0.4,
+            "edge_continuity": 0.3,
+            "color_harmony": 0.3
+        }
+
+        total_score = (
+            coverage_result.score * weights["mask_coverage"] +
+            edge_result.score * weights["edge_continuity"] +
+            harmony_result.score * weights["color_harmony"]
+        )
+        results["overall_score"] = round(total_score, 1)
+
+        # Determine overall pass/fail
+        results["passed"] = all([
+            coverage_result.passed,
+            edge_result.passed,
+            harmony_result.passed
+        ])
+
+        # Collect warnings and errors
+        for check_name, check_data in results["checks"].items():
+            if check_data["issue"]:
+                if check_data["passed"]:
+                    results["warnings"].append(f"{check_name}: {check_data['issue']}")
+                else:
+                    results["errors"].append(f"{check_name}: {check_data['issue']}")
+
+        logger.info(f"📊 Quality check complete - Score: {results['overall_score']}, Passed: {results['passed']}")
+
+        return results
+
+    def get_quality_summary(self, results: Dict[str, Any]) -> str:
+        """
+        Generate human-readable quality summary.
+
+        Args:
+            results: Results from run_all_checks
+
+        Returns:
+            Summary string
+        """
+        score = results["overall_score"]
+        passed = results["passed"]
+
+        if score >= 90:
+            grade = "Excellent"
+        elif score >= 75:
+            grade = "Good"
+        elif score >= 60:
+            grade = "Acceptable"
+        elif score >= 40:
+            grade = "Needs Improvement"
+        else:
+            grade = "Poor"
+
+        summary = f"Quality: {grade} ({score:.0f}/100)"
+
+        if results["errors"]:
+            summary += f"\nIssues: {'; '.join(results['errors'])}"
+        elif results["warnings"]:
+            summary += f"\nNotes: {'; '.join(results['warnings'])}"
+
+        return summary

requirements.txt

@@ -0,0 +1,81 @@
+# SceneWeaver Hugging Face Spaces Deployment Requirements
+# Optimized for ZeroGPU environment with safe version ranges
+
+# ============================================
+# Core Deep Learning Framework
+# ============================================
+# PyTorch 2.x series - compatible with SDXL and xformers
+torch>=2.0.0,<2.5.0
+torchvision>=0.15.0,<0.20.0
+torchaudio>=2.0.0,<2.5.0
+
+# ============================================
+# Diffusion Models and Transformers
+# ============================================
+# Diffusers 0.25+ has better SDXL support, <0.32 for stability
+diffusers>=0.25.0,<0.32.0
+# Transformers compatible with diffusers and open_clip
+transformers>=4.35.0,<4.46.0
+# Accelerate for model loading optimizations
+accelerate>=0.24.0,<0.35.0
+# xformers for memory efficient attention (optional, may fail on some systems)
+# xformers>=0.0.22,<0.0.29
+
+# ============================================
+# Computer Vision and Image Processing
+# ============================================
+# OpenCV for image processing
+opencv-python>=4.8.0,<4.11.0
+# opencv-contrib-python for guided filter (cv2.ximgproc)
+opencv-contrib-python>=4.8.0,<4.11.0
+# Pillow for image I/O
+Pillow>=9.5.0,<11.0.0
+# SciPy for scientific computing
+scipy>=1.10.0,<1.15.0
+
+# ============================================
+# Background Removal
+# ============================================
+# rembg for foreground extraction (CPU version for compatibility)
+rembg>=2.0.50,<2.1.0
+
+# ============================================
+# Multi-modal Understanding (CLIP)
+# ============================================
+# OpenCLIP for image analysis
+open_clip_torch>=2.20.0,<2.27.0
+# Sentence transformers (dependency)
+sentence-transformers>=2.2.0,<3.1.0
+
+# ============================================
+# Web Interface
+# ============================================
+# Gradio 4.x for modern UI
+gradio>=4.0.0,<5.0.0
+
+# ============================================
+# Core Scientific Computing
+# ============================================
+# NumPy 1.x for compatibility
+numpy>=1.24.0,<2.0.0
+
+# ============================================
+# Hugging Face Integration
+# ============================================
+# HuggingFace Hub for model downloads
+huggingface_hub>=0.19.0,<0.27.0
+# Safetensors for efficient model loading
+safetensors>=0.4.0,<0.5.0
+
+# ============================================
+# System Utilities
+# ============================================
+# psutil for memory monitoring
+psutil>=5.9.0,<6.1.0
+# requests for HTTP operations
+requests>=2.28.0,<2.33.0
+
+# ============================================
+# Hugging Face Spaces (auto-installed on Spaces)
+# ============================================
+# spaces  # ZeroGPU support - auto-available on HF Spaces

scene_templates.py

@@ -0,0 +1,429 @@
+import logging
+from typing import Dict, List, Optional
+from dataclasses import dataclass
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class SceneTemplate:
+    """Data class representing a scene template"""
+    key: str
+    name: str
+    prompt: str
+    negative_extra: str
+    category: str
+    icon: str
+    guidance_scale: float = 7.5
+
+
+class SceneTemplateManager:
+    """
+    Manages curated scene templates for background generation.
+    Provides categorized presets that users can select with one click.
+    """
+
+    # Scene template definitions
+    TEMPLATES: Dict[str, SceneTemplate] = {
+        # === Professional Category ===
+        "office_modern": SceneTemplate(
+            key="office_modern",
+            name="Modern Office",
+            prompt="modern minimalist office interior, clean white desk, large floor-to-ceiling windows, natural daylight, professional corporate environment, soft shadows, contemporary furniture",
+            negative_extra="messy, cluttered, dark, old",
+            category="Professional",
+            icon="🏢",
+            guidance_scale=7.5
+        ),
+        "office_executive": SceneTemplate(
+            key="office_executive",
+            name="Executive Suite",
+            prompt="luxurious executive office, mahogany desk, leather chair, city skyline view through windows, warm ambient lighting, bookshelf, elegant professional setting",
+            negative_extra="cheap, cramped, messy",
+            category="Professional",
+            icon="👔",
+            guidance_scale=7.5
+        ),
+        "studio_white": SceneTemplate(
+            key="studio_white",
+            name="White Studio",
+            prompt="clean white photography studio background, professional lighting setup, seamless white backdrop, soft diffused light, minimal shadows",
+            negative_extra="colored, textured, dirty",
+            category="Professional",
+            icon="📷",
+            guidance_scale=8.0
+        ),
+        "coworking": SceneTemplate(
+            key="coworking",
+            name="Coworking Space",
+            prompt="modern coworking space, open plan office, plants, exposed brick, industrial chic design, natural light, collaborative environment",
+            negative_extra="empty, dark, boring",
+            category="Professional",
+            icon="💼",
+            guidance_scale=7.0
+        ),
+        "conference": SceneTemplate(
+            key="conference",
+            name="Conference Room",
+            prompt="modern conference room, large meeting table, glass walls, professional presentation screen, bright corporate lighting, clean minimal design",
+            negative_extra="small, cramped, outdated",
+            category="Professional",
+            icon="🤝",
+            guidance_scale=7.5
+        ),
+
+        # === Nature Category ===
+        "beach_sunset": SceneTemplate(
+            key="beach_sunset",
+            name="Sunset Beach",
+            prompt="beautiful tropical beach at golden hour sunset, palm trees silhouette, calm turquoise ocean waves, warm orange and pink sky, soft sand, paradise vacation vibes",
+            negative_extra="storm, rain, crowded, trash",
+            category="Nature",
+            icon="🏖️",
+            guidance_scale=7.0
+        ),
+        "forest_enchanted": SceneTemplate(
+            key="forest_enchanted",
+            name="Enchanted Forest",
+            prompt="magical enchanted forest, sunlight streaming through tall trees, lush green foliage, mystical atmosphere, morning mist, fairy tale woodland",
+            negative_extra="dead trees, dark, scary, barren",
+            category="Nature",
+            icon="🌲",
+            guidance_scale=7.0
+        ),
+        "mountain_scenic": SceneTemplate(
+            key="mountain_scenic",
+            name="Mountain Vista",
+            prompt="breathtaking mountain landscape, snow-capped peaks, alpine meadow, clear blue sky, majestic scenic view, pristine nature, peaceful atmosphere",
+            negative_extra="industrial, polluted, crowded",
+            category="Nature",
+            icon="🏔️",
+            guidance_scale=7.5
+        ),
+        "garden_spring": SceneTemplate(
+            key="garden_spring",
+            name="Spring Garden",
+            prompt="beautiful spring flower garden, colorful blooming flowers, roses and tulips, manicured hedges, sunny day, botanical paradise, fresh and vibrant",
+            negative_extra="dead, winter, wilted, dry",
+            category="Nature",
+            icon="🌸",
+            guidance_scale=7.0
+        ),
+        "lake_serene": SceneTemplate(
+            key="lake_serene",
+            name="Serene Lake",
+            prompt="peaceful serene lake at dawn, mirror-like water reflection, surrounding mountains, soft morning light, tranquil atmosphere, pristine natural beauty",
+            negative_extra="stormy, polluted, industrial",
+            category="Nature",
+            icon="🏞️",
+            guidance_scale=7.0
+        ),
+        "cherry_blossom": SceneTemplate(
+            key="cherry_blossom",
+            name="Cherry Blossom",
+            prompt="stunning cherry blossom trees in full bloom, pink sakura petals falling gently, Japanese garden aesthetic, soft spring sunlight, romantic atmosphere",
+            negative_extra="winter, dead, brown, wilted",
+            category="Nature",
+            icon="🌸",
+            guidance_scale=7.0
+        ),
+
+        # === Urban Category ===
+        "city_skyline": SceneTemplate(
+            key="city_skyline",
+            name="City Skyline",
+            prompt="modern city skyline at blue hour, impressive skyscrapers, glass buildings reflecting sunset, urban metropolitan view, cinematic atmosphere",
+            negative_extra="slums, dirty, abandoned, ruins",
+            category="Urban",
+            icon="🌆",
+            guidance_scale=7.5
+        ),
+        "cafe_cozy": SceneTemplate(
+            key="cafe_cozy",
+            name="Cozy Cafe",
+            prompt="warm cozy coffee shop interior, wooden furniture, ambient lighting, exposed brick walls, plants, comfortable atmosphere, artisan cafe vibes",
+            negative_extra="fast food, plastic, harsh lighting",
+            category="Urban",
+            icon="☕",
+            guidance_scale=7.0
+        ),
+        "street_european": SceneTemplate(
+            key="street_european",
+            name="European Street",
+            prompt="charming European cobblestone street, historic buildings, outdoor cafe, flowers on balconies, warm afternoon light, romantic Paris or Rome vibes",
+            negative_extra="modern, industrial, ugly, dirty",
+            category="Urban",
+            icon="🏛️",
+            guidance_scale=7.0
+        ),
+        "night_neon": SceneTemplate(
+            key="night_neon",
+            name="Neon Nightlife",
+            prompt="vibrant city nightlife scene, neon lights and signs, urban night atmosphere, colorful reflections on wet street, cyberpunk aesthetic, electric energy",
+            negative_extra="daytime, boring, plain",
+            category="Urban",
+            icon="🌃",
+            guidance_scale=6.5
+        ),
+        "rooftop_view": SceneTemplate(
+            key="rooftop_view",
+            name="Rooftop Terrace",
+            prompt="luxury rooftop terrace, city panoramic view, modern outdoor furniture, string lights, sunset golden hour, sophisticated urban oasis",
+            negative_extra="cheap, dirty, crowded",
+            category="Urban",
+            icon="🏙️",
+            guidance_scale=7.5
+        ),
+
+        # === Artistic Category ===
+        "gradient_soft": SceneTemplate(
+            key="gradient_soft",
+            name="Soft Gradient",
+            prompt="smooth soft gradient background, pastel colors blending beautifully, pink to blue to purple transition, dreamy aesthetic, professional portrait backdrop",
+            negative_extra="harsh, noisy, textured, busy",
+            category="Artistic",
+            icon="🎨",
+            guidance_scale=8.0
+        ),
+        "abstract_modern": SceneTemplate(
+            key="abstract_modern",
+            name="Modern Abstract",
+            prompt="modern abstract art background, geometric shapes, bold colors, contemporary design, artistic composition, museum gallery aesthetic",
+            negative_extra="realistic, plain, boring",
+            category="Artistic",
+            icon="🖼️",
+            guidance_scale=6.5
+        ),
+        "vintage_retro": SceneTemplate(
+            key="vintage_retro",
+            name="Vintage Retro",
+            prompt="vintage retro aesthetic background, warm sepia tones, nostalgic 70s vibes, film grain texture, classic photography style, timeless elegance",
+            negative_extra="modern, digital, cold, harsh",
+            category="Artistic",
+            icon="📻",
+            guidance_scale=7.0
+        ),
+        "watercolor_dream": SceneTemplate(
+            key="watercolor_dream",
+            name="Watercolor Dream",
+            prompt="beautiful watercolor painting background, soft flowing colors, artistic brush strokes, dreamy ethereal atmosphere, delicate artistic aesthetic",
+            negative_extra="digital, sharp, photorealistic",
+            category="Artistic",
+            icon="🖌️",
+            guidance_scale=6.5
+        ),
+
+        # === Seasonal Category ===
+        "autumn_foliage": SceneTemplate(
+            key="autumn_foliage",
+            name="Autumn Foliage",
+            prompt="beautiful autumn scenery, vibrant fall foliage, orange red and golden leaves, maple trees, warm sunlight filtering through, cozy seasonal atmosphere",
+            negative_extra="spring, summer, green, snow",
+            category="Seasonal",
+            icon="🍂",
+            guidance_scale=7.0
+        ),
+        "winter_snow": SceneTemplate(
+            key="winter_snow",
+            name="Winter Wonderland",
+            prompt="magical winter wonderland, fresh white snow covering everything, snow-laden pine trees, soft snowfall, peaceful cold atmosphere, holiday season vibes",
+            negative_extra="summer, green, rain, mud",
+            category="Seasonal",
+            icon="❄️",
+            guidance_scale=7.0
+        ),
+        "summer_tropical": SceneTemplate(
+            key="summer_tropical",
+            name="Tropical Summer",
+            prompt="vibrant tropical summer scene, lush palm trees, bright sunny day, exotic flowers, paradise vacation destination, warm and inviting atmosphere",
+            negative_extra="winter, cold, snow, gray",
+            category="Seasonal",
+            icon="🌴",
+            guidance_scale=7.0
+        ),
+        "spring_meadow": SceneTemplate(
+            key="spring_meadow",
+            name="Spring Meadow",
+            prompt="beautiful spring meadow, wildflowers blooming, fresh green grass, butterflies, soft warm sunlight, renewal and new beginnings, pastoral beauty",
+            negative_extra="winter, autumn, dead, dry",
+            category="Seasonal",
+            icon="🌷",
+            guidance_scale=7.0
+        ),
+    }
+
+    # Category display order
+    CATEGORIES = ["Professional", "Nature", "Urban", "Artistic", "Seasonal"]
+
+    def __init__(self):
+        """Initialize the scene template manager"""
+        logger.info(f"SceneTemplateManager initialized with {len(self.TEMPLATES)} templates")
+
+    def get_all_templates(self) -> Dict[str, SceneTemplate]:
+        """Get all available templates"""
+        return self.TEMPLATES
+
+    def get_template(self, key: str) -> Optional[SceneTemplate]:
+        """Get a specific template by key"""
+        return self.TEMPLATES.get(key)
+
+    def get_templates_by_category(self, category: str) -> List[SceneTemplate]:
+        """Get all templates in a specific category"""
+        return [t for t in self.TEMPLATES.values() if t.category == category]
+
+    def get_categories(self) -> List[str]:
+        """Get list of all categories in display order"""
+        return self.CATEGORIES
+
+    def get_template_choices_sorted(self) -> List[str]:
+        """
+        Get template choices formatted for Gradio dropdown.
+        Returns list of display strings sorted A-Z: "🏢 Modern Office"
+        """
+        display_list = []
+        for key, template in self.TEMPLATES.items():
+            display_name = f"{template.icon} {template.name}"
+            display_list.append(display_name)
+
+        # Sort alphabetically by name (ignoring emoji)
+        display_list.sort(key=lambda x: x.split(' ', 1)[1] if ' ' in x else x)
+        return display_list
+
+    def get_template_key_from_display(self, display_name: str) -> Optional[str]:
+        """
+        Get template key from display name.
+        Example: "🏢 Modern Office" -> "office_modern"
+        """
+        if not display_name:
+            return None
+
+        for key, template in self.TEMPLATES.items():
+            if f"{template.icon} {template.name}" == display_name:
+                return key
+        return None
+
+    def get_prompt_for_template(self, key: str) -> Optional[str]:
+        """Get the prompt string for a template"""
+        template = self.get_template(key)
+        return template.prompt if template else None
+
+    def get_negative_prompt_for_template(
+        self,
+        key: str,
+        base_negative: str = "blurry, low quality, distorted, people, characters"
+    ) -> str:
+        """Get combined negative prompt for a template"""
+        template = self.get_template(key)
+        if template and template.negative_extra:
+            return f"{base_negative}, {template.negative_extra}"
+        return base_negative
+
+    def get_guidance_scale_for_template(self, key: str) -> float:
+        """Get the recommended guidance scale for a template"""
+        template = self.get_template(key)
+        return template.guidance_scale if template else 7.5
+
+    def build_gallery_html(self) -> str:
+        """
+        Build HTML for the scene template gallery.
+        Returns HTML string for display in Gradio.
+        """
+        html_parts = ['<div class="scene-gallery">']
+
+        for category in self.CATEGORIES:
+            templates = self.get_templates_by_category(category)
+            if not templates:
+                continue
+
+            html_parts.append(f'''
+            <div class="scene-category">
+                <h4 class="scene-category-title">{category}</h4>
+                <div class="scene-grid">
+            ''')
+
+            for template in templates:
+                html_parts.append(f'''
+                <button class="scene-card" data-template="{template.key}" onclick="selectTemplate('{template.key}')">
+                    <span class="scene-icon">{template.icon}</span>
+                    <span class="scene-name">{template.name}</span>
+                </button>
+                ''')
+
+            html_parts.append('</div></div>')
+
+        html_parts.append('</div>')
+        return ''.join(html_parts)
+
+    def get_gallery_css(self) -> str:
+        """Get CSS styles for the scene gallery"""
+        return """
+        /* Scene Gallery Styles */
+        .scene-gallery {
+            margin: 16px 0;
+        }
+
+        .scene-category {
+            margin-bottom: 20px;
+        }
+
+        .scene-category-title {
+            font-size: 0.9rem;
+            font-weight: 600;
+            color: #475569;
+            margin-bottom: 12px;
+            padding-bottom: 8px;
+            border-bottom: 1px solid #e2e8f0;
+        }
+
+        .scene-grid {
+            display: grid;
+            grid-template-columns: repeat(auto-fill, minmax(100px, 1fr));
+            gap: 8px;
+        }
+
+        .scene-card {
+            display: flex;
+            flex-direction: column;
+            align-items: center;
+            justify-content: center;
+            padding: 12px 8px;
+            background: #f8fafc;
+            border: 1px solid #e2e8f0;
+            border-radius: 8px;
+            cursor: pointer;
+            transition: all 0.2s ease;
+            min-height: 70px;
+        }
+
+        .scene-card:hover {
+            background: #dbeafe;
+            border-color: #3b82f6;
+            transform: translateY(-2px);
+            box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
+        }
+
+        .scene-card.selected {
+            background: #dbeafe;
+            border-color: #3b82f6;
+            box-shadow: 0 0 0 2px rgba(59, 130, 246, 0.3);
+        }
+
+        .scene-icon {
+            font-size: 1.5rem;
+            margin-bottom: 4px;
+        }
+
+        .scene-name {
+            font-size: 0.75rem;
+            font-weight: 500;
+            color: #1e293b;
+            text-align: center;
+            line-height: 1.2;
+        }
+
+        @media (max-width: 768px) {
+            .scene-grid {
+                grid-template-columns: repeat(3, 1fr);
+            }
+        }
+        """

scene_weaver_core.py

@@ -0,0 +1,808 @@
+import torch
+import numpy as np
+import cv2
+from PIL import Image
+import logging
+import gc
+import time
+from typing import Optional, Dict, Any, Tuple, List
+from pathlib import Path
+import warnings
+warnings.filterwarnings("ignore")
+
+from diffusers import StableDiffusionXLPipeline, DPMSolverMultistepScheduler
+import open_clip
+from mask_generator import MaskGenerator
+from image_blender import ImageBlender
+from quality_checker import QualityChecker
+
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.INFO)
+
+class SceneWeaverCore:
+    """
+    SceneWeaver with perfect background generation + fixed blending + memory optimization
+    """
+
+    # Style presets for diversity generation mode
+    STYLE_PRESETS = {
+        "professional": {
+            "name": "Professional Business",
+            "modifier": "professional office environment, clean background, corporate setting, bright even lighting",
+            "negative_extra": "casual, messy, cluttered",
+            "guidance_scale": 8.0
+        },
+        "casual": {
+            "name": "Casual Lifestyle",
+            "modifier": "casual outdoor setting, natural environment, relaxed atmosphere, warm natural lighting",
+            "negative_extra": "formal, studio",
+            "guidance_scale": 7.5
+        },
+        "artistic": {
+            "name": "Artistic Creative",
+            "modifier": "artistic background, creative composition, vibrant colors, interesting lighting",
+            "negative_extra": "boring, plain",
+            "guidance_scale": 6.5
+        },
+        "nature": {
+            "name": "Natural Scenery",
+            "modifier": "beautiful natural scenery, outdoor landscape, scenic view, natural lighting",
+            "negative_extra": "urban, indoor",
+            "guidance_scale": 7.5
+        }
+    }
+
+    def __init__(self, device: str = "auto"):
+        self.device = self._setup_device(device)
+
+        # Model configurations - KEEP SAME FOR PERFECT GENERATION
+        self.base_model_id = "stabilityai/stable-diffusion-xl-base-1.0"
+        self.clip_model_name = "ViT-B-32"
+        self.clip_pretrained = "openai"
+
+        # Pipeline objects
+        self.pipeline = None
+        self.clip_model = None
+        self.clip_preprocess = None
+        self.clip_tokenizer = None
+        self.is_initialized = False
+
+        # Generation settings - KEEP SAME
+        self.max_image_size = 1024
+        self.default_steps = 25
+        self.use_fp16 = True
+
+        # Enhanced memory management
+        self.generation_count = 0
+        self.cleanup_frequency = 1  # More frequent cleanup
+        self.max_history = 3  # Limit generation history
+
+        # Initialize helper classes
+        self.mask_generator = MaskGenerator(self.max_image_size)
+        self.image_blender = ImageBlender()
+        self.quality_checker = QualityChecker()
+
+        logger.info(f"OptimizedSceneWeaver initialized on {self.device}")
+
+    def _setup_device(self, device: str) -> str:
+        """Setup computation device"""
+        if device == "auto":
+            if torch.cuda.is_available():
+                return "cuda"
+            elif hasattr(torch.backends, 'mps') and torch.backends.mps.is_available():
+                return "mps"
+            else:
+                return "cpu"
+        return device
+
+    def _ultra_memory_cleanup(self):
+        """Ultra aggressive memory cleanup for Colab stability"""
+        logger.debug("🧹 Ultra memory cleanup...")
+
+        # Multiple rounds of garbage collection
+        for i in range(5):
+            gc.collect()
+
+        if torch.cuda.is_available():
+            # Clear all cached memory
+            torch.cuda.empty_cache()
+            torch.cuda.ipc_collect()
+
+            # Force synchronization
+            torch.cuda.synchronize()
+
+            # Clear any remaining memory fragments
+            try:
+                torch.cuda.memory.empty_cache()
+            except:
+                pass
+
+        logger.debug("✅ Ultra cleanup completed")
+
+    def load_models(self, progress_callback: Optional[callable] = None):
+        """Load AI models - KEEP SAME FOR PERFECT GENERATION"""
+        if self.is_initialized:
+            logger.info("Models already loaded")
+            return
+
+        logger.info("📥 Loading AI models...")
+
+        try:
+            self._ultra_memory_cleanup()
+
+            if progress_callback:
+                progress_callback("Loading OpenCLIP for image understanding...", 20)
+
+            # Load OpenCLIP - KEEP SAME
+            self.clip_model, _, self.clip_preprocess = open_clip.create_model_and_transforms(
+                self.clip_model_name,
+                pretrained=self.clip_pretrained,
+                device=self.device
+            )
+            self.clip_tokenizer = open_clip.get_tokenizer(self.clip_model_name)
+            self.clip_model.eval()
+
+            logger.info("✅ OpenCLIP loaded")
+
+            if progress_callback:
+                progress_callback("Loading SDXL text-to-image pipeline...", 60)
+
+            # Load standard SDXL text-to-image pipeline - KEEP SAME
+            self.pipeline = StableDiffusionXLPipeline.from_pretrained(
+                self.base_model_id,
+                torch_dtype=torch.float16 if self.use_fp16 else torch.float32,
+                use_safetensors=True,
+                variant="fp16" if self.use_fp16 else None
+            )
+
+            # Use DPM solver for faster generation - KEEP SAME
+            self.pipeline.scheduler = DPMSolverMultistepScheduler.from_config(
+                self.pipeline.scheduler.config
+            )
+
+            # Move to device
+            self.pipeline = self.pipeline.to(self.device)
+
+            if progress_callback:
+                progress_callback("Applying optimizations...", 90)
+
+            # Memory optimizations - ENHANCED
+            try:
+                self.pipeline.enable_xformers_memory_efficient_attention()
+                logger.info("✅ xformers enabled")
+            except Exception:
+                try:
+                    self.pipeline.enable_attention_slicing()
+                    logger.info("✅ Attention slicing enabled")
+                except Exception:
+                    logger.warning("⚠️ No memory optimizations available")
+
+            # Additional memory optimizations
+            if hasattr(self.pipeline, 'enable_vae_tiling'):
+                self.pipeline.enable_vae_tiling()
+
+            if hasattr(self.pipeline, 'enable_vae_slicing'):
+                self.pipeline.enable_vae_slicing()
+
+            # Set to eval mode
+            self.pipeline.unet.eval()
+            if hasattr(self.pipeline, 'vae'):
+                self.pipeline.vae.eval()
+
+            # Enable sequential CPU offload if very low on memory
+            try:
+                if torch.cuda.is_available():
+                    free_memory = torch.cuda.get_device_properties(0).total_memory - torch.cuda.memory_allocated()
+                    if free_memory < 4 * 1024**3:  # Less than 4GB free
+                        self.pipeline.enable_sequential_cpu_offload()
+                        logger.info("✅ Sequential CPU offload enabled for low memory")
+            except:
+                pass
+
+            self.is_initialized = True
+
+            if progress_callback:
+                progress_callback("Models loaded successfully!", 100)
+
+            # Memory status
+            if torch.cuda.is_available():
+                memory_used = torch.cuda.memory_allocated() / 1024**3
+                memory_total = torch.cuda.get_device_properties(0).total_memory / 1024**3
+                logger.info(f"📊 GPU Memory: {memory_used:.1f}GB / {memory_total:.1f}GB")
+
+        except Exception as e:
+            logger.error(f"❌ Model loading failed: {e}")
+            raise RuntimeError(f"Failed to load models: {str(e)}")
+
+    def analyze_image_with_clip(self, image: Image.Image) -> str:
+        """Analyze uploaded image using OpenCLIP - KEEP SAME"""
+        if not self.clip_model:
+            return "Image analysis not available"
+
+        try:
+            image_input = self.clip_preprocess(image).unsqueeze(0).to(self.device)
+
+            categories = [
+                "a photo of a person",
+                "a photo of an animal",
+                "a photo of an object",
+                "a photo of a character",
+                "a photo of a cartoon",
+                "a photo of nature",
+                "a photo of a building",
+                "a photo of a landscape"
+            ]
+
+            text_inputs = self.clip_tokenizer(categories).to(self.device)
+
+            with torch.no_grad():
+                image_features = self.clip_model.encode_image(image_input)
+                text_features = self.clip_model.encode_text(text_inputs)
+
+                image_features /= image_features.norm(dim=-1, keepdim=True)
+                text_features /= text_features.norm(dim=-1, keepdim=True)
+
+                similarity = (100.0 * image_features @ text_features.T).softmax(dim=-1)
+
+                best_match_idx = similarity.argmax().item()
+                confidence = similarity[0, best_match_idx].item()
+
+                category = categories[best_match_idx].replace("a photo of ", "")
+
+                return f"Detected: {category} (confidence: {confidence:.1%})"
+
+        except Exception as e:
+            logger.error(f"CLIP analysis failed: {e}")
+            return "Image analysis failed"
+
+    def enhance_prompt(
+        self,
+        user_prompt: str,
+        foreground_image: Image.Image
+    ) -> str:
+        """
+        Smart prompt enhancement based on image analysis.
+        Adds appropriate lighting, atmosphere, and quality descriptors.
+
+        Args:
+            user_prompt: Original user-provided prompt
+            foreground_image: Foreground image for analysis
+
+        Returns:
+            Enhanced prompt string
+        """
+        logger.info("✨ Enhancing prompt based on image analysis...")
+
+        try:
+            # Analyze image characteristics
+            img_array = np.array(foreground_image.convert('RGB'))
+
+            # === Analyze color temperature ===
+            # Convert to LAB to analyze color temperature
+            lab = cv2.cvtColor(img_array, cv2.COLOR_RGB2LAB)
+            avg_a = np.mean(lab[:, :, 1])  # a channel: green(-) to red(+)
+            avg_b = np.mean(lab[:, :, 2])  # b channel: blue(-) to yellow(+)
+
+            # Determine warm/cool tone
+            is_warm = avg_b > 128  # b > 128 means more yellow/warm
+
+            # === Analyze brightness ===
+            gray = cv2.cvtColor(img_array, cv2.COLOR_RGB2GRAY)
+            avg_brightness = np.mean(gray)
+            is_bright = avg_brightness > 127
+
+            # === Get subject type from CLIP ===
+            clip_analysis = self.analyze_image_with_clip(foreground_image)
+            subject_type = "unknown"
+
+            if "person" in clip_analysis.lower():
+                subject_type = "person"
+            elif "animal" in clip_analysis.lower():
+                subject_type = "animal"
+            elif "object" in clip_analysis.lower():
+                subject_type = "object"
+            elif "character" in clip_analysis.lower() or "cartoon" in clip_analysis.lower():
+                subject_type = "character"
+            elif "nature" in clip_analysis.lower() or "landscape" in clip_analysis.lower():
+                subject_type = "nature"
+
+            # === Build prompt fragments library ===
+            lighting_options = {
+                "warm_bright": "warm golden hour lighting, soft natural light",
+                "warm_dark": "warm ambient lighting, cozy atmosphere",
+                "cool_bright": "bright daylight, clear sky lighting",
+                "cool_dark": "soft diffused light, gentle shadows"
+            }
+
+            atmosphere_options = {
+                "person": "professional, elegant composition",
+                "animal": "natural, harmonious setting",
+                "object": "clean product photography style",
+                "character": "artistic, vibrant, imaginative",
+                "nature": "scenic, peaceful atmosphere",
+                "unknown": "balanced composition"
+            }
+
+            quality_modifiers = "high quality, detailed, sharp focus, photorealistic"
+
+            # === Select appropriate fragments ===
+            # Lighting based on color temperature and brightness
+            if is_warm and is_bright:
+                lighting = lighting_options["warm_bright"]
+            elif is_warm and not is_bright:
+                lighting = lighting_options["warm_dark"]
+            elif not is_warm and is_bright:
+                lighting = lighting_options["cool_bright"]
+            else:
+                lighting = lighting_options["cool_dark"]
+
+            # Atmosphere based on subject type
+            atmosphere = atmosphere_options.get(subject_type, atmosphere_options["unknown"])
+
+            # === Check for conflicts in user prompt ===
+            user_prompt_lower = user_prompt.lower()
+
+            # Avoid adding conflicting descriptions
+            if "sunset" in user_prompt_lower or "golden" in user_prompt_lower:
+                lighting = ""  # User already specified lighting
+            if "dark" in user_prompt_lower or "night" in user_prompt_lower:
+                lighting = lighting.replace("bright", "").replace("daylight", "")
+
+            # === Combine enhanced prompt ===
+            fragments = [user_prompt]
+
+            if lighting:
+                fragments.append(lighting)
+            if atmosphere:
+                fragments.append(atmosphere)
+            fragments.append(quality_modifiers)
+
+            enhanced_prompt = ", ".join(filter(None, fragments))
+
+            logger.info(f"📝 Original prompt: {user_prompt[:50]}...")
+            logger.info(f"📝 Enhanced prompt: {enhanced_prompt[:80]}...")
+
+            return enhanced_prompt
+
+        except Exception as e:
+            logger.warning(f"⚠️ Prompt enhancement failed: {e}, using original prompt")
+            return user_prompt
+
+    def _prepare_image(self, image: Image.Image) -> Image.Image:
+        """Prepare image for processing - KEEP SAME"""
+        # Convert to RGB
+        if image.mode != 'RGB':
+            image = image.convert('RGB')
+
+        # Resize if too large
+        width, height = image.size
+        max_size = self.max_image_size
+
+        if width > max_size or height > max_size:
+            ratio = min(max_size/width, max_size/height)
+            new_width = int(width * ratio)
+            new_height = int(height * ratio)
+            image = image.resize((new_width, new_height), Image.LANCZOS)
+
+        # Ensure dimensions are multiple of 8
+        width, height = image.size
+        new_width = (width // 8) * 8
+        new_height = (height // 8) * 8
+
+        if new_width != width or new_height != height:
+            image = image.resize((new_width, new_height), Image.LANCZOS)
+
+        return image
+
+    def generate_background(
+        self,
+        prompt: str,
+        width: int,
+        height: int,
+        negative_prompt: str = "blurry, low quality, distorted",
+        num_inference_steps: int = 25,
+        guidance_scale: float = 7.5,
+        progress_callback: Optional[callable] = None
+    ) -> Image.Image:
+        """Generate complete background using standard text-to-image - KEEP SAME"""
+
+        if not self.is_initialized:
+            raise RuntimeError("Models not loaded. Call load_models() first.")
+
+        logger.info(f"🎨 Generating background: {prompt[:50]}...")
+
+        try:
+            with torch.inference_mode():
+                if progress_callback:
+                    progress_callback("Generating background with SDXL...", 50)
+
+                # Standard text-to-image generation - KEEP SAME
+                result = self.pipeline(
+                    prompt=prompt,
+                    negative_prompt=negative_prompt,
+                    width=width,
+                    height=height,
+                    num_inference_steps=num_inference_steps,
+                    guidance_scale=guidance_scale,
+                    generator=torch.Generator(device=self.device).manual_seed(42)
+                )
+
+                generated_image = result.images[0]
+
+                if progress_callback:
+                    progress_callback("Background generated successfully!", 100)
+
+                logger.info("✅ Background generation completed!")
+                return generated_image
+
+        except torch.cuda.OutOfMemoryError:
+            logger.error("❌ GPU memory exhausted")
+            self._ultra_memory_cleanup()
+            raise RuntimeError("GPU memory insufficient")
+
+        except Exception as e:
+            logger.error(f"❌ Background generation failed: {e}")
+            raise RuntimeError(f"Generation failed: {str(e)}")
+
+    def generate_and_combine(
+        self,
+        original_image: Image.Image,
+        prompt: str,
+        combination_mode: str = "center",
+        focus_mode: str = "person",
+        negative_prompt: str = "blurry, low quality, distorted",
+        num_inference_steps: int = 25,
+        guidance_scale: float = 7.5,
+        progress_callback: Optional[callable] = None,
+        enable_prompt_enhancement: bool = True
+    ) -> Dict[str, Any]:
+        """
+        Generate background and combine with foreground using advanced blending.
+
+        Args:
+            original_image: Foreground image
+            prompt: User's background description
+            combination_mode: How to position foreground ("center", "left_half", "right_half", "full")
+            focus_mode: Focus type ("person" for tight crop, "scene" for wider context)
+            negative_prompt: What to avoid in generation
+            num_inference_steps: SDXL inference steps
+            guidance_scale: Classifier-free guidance scale
+            progress_callback: Progress reporting callback
+            enable_prompt_enhancement: Whether to use smart prompt enhancement
+
+        Returns:
+            Dictionary containing results and metadata
+        """
+
+        if not self.is_initialized:
+            raise RuntimeError("Models not loaded. Call load_models() first.")
+
+        logger.info(f"🎨 Starting generation and combination with advanced features...")
+
+        try:
+            # Enhanced memory management
+            if self.generation_count % self.cleanup_frequency == 0:
+                self._ultra_memory_cleanup()
+
+            if progress_callback:
+                progress_callback("Analyzing uploaded image...", 5)
+
+            # Analyze original image
+            image_analysis = self.analyze_image_with_clip(original_image)
+
+            if progress_callback:
+                progress_callback("Preparing images...", 10)
+
+            # Prepare original image
+            processed_original = self._prepare_image(original_image)
+            target_width, target_height = processed_original.size
+
+            if progress_callback:
+                progress_callback("Optimizing prompt...", 15)
+
+            # Smart prompt enhancement
+            if enable_prompt_enhancement:
+                enhanced_prompt = self.enhance_prompt(prompt, processed_original)
+            else:
+                enhanced_prompt = f"{prompt}, high quality, detailed, photorealistic, beautiful scenery"
+
+            enhanced_negative = f"{negative_prompt}, people, characters, cartoons, logos"
+
+            if progress_callback:
+                progress_callback("Generating complete background scene...", 25)
+
+            def bg_progress(msg, pct):
+                if progress_callback:
+                    progress_callback(f"Background: {msg}", 25 + (pct/100) * 50)
+
+            generated_background = self.generate_background(
+                prompt=enhanced_prompt,
+                width=target_width,
+                height=target_height,
+                negative_prompt=enhanced_negative,
+                num_inference_steps=num_inference_steps,
+                guidance_scale=guidance_scale,
+                progress_callback=bg_progress
+            )
+
+            if progress_callback:
+                progress_callback("Creating intelligent mask for person detection...", 80)
+
+            # Use intelligent mask generation with enhanced logging
+            logger.info("🎭 Starting intelligent mask generation...")
+            combination_mask = self.mask_generator.create_gradient_based_mask(
+                processed_original,
+                combination_mode,
+                focus_mode
+            )
+
+            # Log mask quality for debugging
+            try:
+                mask_array = np.array(combination_mask)
+                logger.info(f"📊 Generated mask stats - Mean: {mask_array.mean():.1f}, Non-zero pixels: {np.count_nonzero(mask_array)}")
+            except Exception as mask_debug_error:
+                logger.warning(f"⚠️ Mask debug logging failed: {mask_debug_error}")
+
+            if progress_callback:
+                progress_callback("Advanced image blending...", 90)
+
+            # Use advanced image blending with logging
+            logger.info("🖌️ Starting advanced image blending...")
+            combined_image = self.image_blender.simple_blend_images(
+                processed_original,
+                generated_background,
+                combination_mask
+            )
+            logger.info("✅ Image blending completed successfully")
+
+            if progress_callback:
+                progress_callback("Creating debug images...", 95)
+
+            # Generate debug images
+            debug_images = self.image_blender.create_debug_images(
+                processed_original,
+                generated_background,
+                combination_mask,
+                combined_image
+            )
+
+            # Memory cleanup after generation
+            self._ultra_memory_cleanup()
+
+            # Update generation count
+            self.generation_count += 1
+
+            if progress_callback:
+                progress_callback("Generation complete!", 100)
+
+            logger.info("✅ Complete generation and combination with fixed blending successful!")
+
+            return {
+                "combined_image": combined_image,
+                "generated_scene": generated_background,
+                "original_image": processed_original,
+                "combination_mask": combination_mask,
+                "debug_mask_gray": debug_images["mask_gray"],
+                "debug_alpha_heatmap": debug_images["alpha_heatmap"],
+                "image_analysis": image_analysis,
+                "enhanced_prompt": enhanced_prompt,
+                "original_prompt": prompt,
+                "success": True,
+                "generation_count": self.generation_count
+            }
+
+        except Exception as e:
+            import traceback
+            error_traceback = traceback.format_exc()
+            logger.error(f"❌ Generation and combination failed: {str(e)}")
+            logger.error(f"📍 Full traceback:\n{error_traceback}")
+            print(f"❌ DETAILED ERROR in scene_weaver_core.generate_and_combine:")
+            print(f"Error: {str(e)}")
+            print(f"Traceback:\n{error_traceback}")
+            self._ultra_memory_cleanup()  # Cleanup on error too
+            return {
+                "success": False,
+                "error": f"Failed: {str(e)}"
+            }
+
+    def generate_diversity_variants(
+        self,
+        original_image: Image.Image,
+        prompt: str,
+        selected_styles: Optional[List[str]] = None,
+        combination_mode: str = "center",
+        focus_mode: str = "person",
+        negative_prompt: str = "blurry, low quality, distorted",
+        progress_callback: Optional[callable] = None
+    ) -> Dict[str, Any]:
+        """
+        Generate multiple style variants of the background.
+        Uses reduced quality for faster preview generation.
+
+        Args:
+            original_image: Foreground image
+            prompt: Base background description
+            selected_styles: List of style keys to use (None = all styles)
+            combination_mode: Foreground positioning mode
+            focus_mode: Focus type for mask generation
+            negative_prompt: Base negative prompt
+            progress_callback: Progress callback function
+
+        Returns:
+            Dictionary containing variants and metadata
+        """
+        if not self.is_initialized:
+            raise RuntimeError("Models not loaded. Call load_models() first.")
+
+        logger.info("🎨 Starting diversity generation mode...")
+
+        # Determine which styles to generate
+        styles_to_generate = selected_styles or list(self.STYLE_PRESETS.keys())
+        num_styles = len(styles_to_generate)
+
+        results = {
+            "variants": [],
+            "success": True,
+            "num_variants": 0
+        }
+
+        try:
+            # Pre-process image once
+            processed_original = self._prepare_image(original_image)
+            target_width, target_height = processed_original.size
+
+            # Reduce resolution for faster generation
+            preview_size = min(768, max(target_width, target_height))
+            scale = preview_size / max(target_width, target_height)
+            preview_width = int(target_width * scale) // 8 * 8
+            preview_height = int(target_height * scale) // 8 * 8
+
+            # Generate mask once (reusable for all variants)
+            if progress_callback:
+                progress_callback("Creating foreground mask...", 5)
+
+            combination_mask = self.mask_generator.create_gradient_based_mask(
+                processed_original, combination_mode, focus_mode
+            )
+
+            # Resize mask for preview resolution
+            preview_mask = combination_mask.resize((preview_width, preview_height), Image.LANCZOS)
+            preview_original = processed_original.resize((preview_width, preview_height), Image.LANCZOS)
+
+            # Generate each style variant
+            for idx, style_key in enumerate(styles_to_generate):
+                if style_key not in self.STYLE_PRESETS:
+                    logger.warning(f"⚠️ Unknown style: {style_key}, skipping")
+                    continue
+
+                style = self.STYLE_PRESETS[style_key]
+                style_name = style["name"]
+
+                if progress_callback:
+                    base_pct = 10 + (idx / num_styles) * 80
+                    progress_callback(f"Generating {style_name} variant...", int(base_pct))
+
+                logger.info(f"🎨 Generating variant: {style_name}")
+
+                try:
+                    # Build style-specific prompt
+                    styled_prompt = f"{prompt}, {style['modifier']}, high quality, detailed"
+                    styled_negative = f"{negative_prompt}, {style['negative_extra']}, people, characters"
+
+                    # Generate background with reduced steps for speed
+                    background = self.generate_background(
+                        prompt=styled_prompt,
+                        width=preview_width,
+                        height=preview_height,
+                        negative_prompt=styled_negative,
+                        num_inference_steps=15,  # Reduced for speed
+                        guidance_scale=style["guidance_scale"]
+                    )
+
+                    # Blend images
+                    combined = self.image_blender.simple_blend_images(
+                        preview_original,
+                        background,
+                        preview_mask,
+                        use_multi_scale=False  # Skip for speed
+                    )
+
+                    results["variants"].append({
+                        "style_key": style_key,
+                        "style_name": style_name,
+                        "combined_image": combined,
+                        "background": background,
+                        "prompt_used": styled_prompt
+                    })
+
+                    # Memory cleanup between variants
+                    self._ultra_memory_cleanup()
+
+                except Exception as variant_error:
+                    logger.error(f"❌ Failed to generate {style_name} variant: {variant_error}")
+                    continue
+
+            results["num_variants"] = len(results["variants"])
+
+            if progress_callback:
+                progress_callback("Diversity generation complete!", 100)
+
+            logger.info(f"✅ Generated {results['num_variants']} style variants")
+            return results
+
+        except Exception as e:
+            logger.error(f"❌ Diversity generation failed: {e}")
+            self._ultra_memory_cleanup()
+            return {
+                "variants": [],
+                "success": False,
+                "error": str(e),
+                "num_variants": 0
+            }
+
+    def regenerate_high_quality(
+        self,
+        original_image: Image.Image,
+        prompt: str,
+        style_key: str,
+        combination_mode: str = "center",
+        focus_mode: str = "person",
+        negative_prompt: str = "blurry, low quality, distorted",
+        progress_callback: Optional[callable] = None
+    ) -> Dict[str, Any]:
+        """
+        Regenerate a specific style at full quality.
+
+        Args:
+            original_image: Original foreground image
+            prompt: Base prompt
+            style_key: Style preset key to use
+            combination_mode: Foreground positioning
+            focus_mode: Mask focus mode
+            negative_prompt: Base negative prompt
+            progress_callback: Progress callback
+
+        Returns:
+            Full quality result dictionary
+        """
+        if style_key not in self.STYLE_PRESETS:
+            return {"success": False, "error": f"Unknown style: {style_key}"}
+
+        style = self.STYLE_PRESETS[style_key]
+
+        # Build styled prompt
+        styled_prompt = f"{prompt}, {style['modifier']}"
+        styled_negative = f"{negative_prompt}, {style['negative_extra']}"
+
+        # Use full generate_and_combine with style parameters
+        return self.generate_and_combine(
+            original_image=original_image,
+            prompt=styled_prompt,
+            combination_mode=combination_mode,
+            focus_mode=focus_mode,
+            negative_prompt=styled_negative,
+            num_inference_steps=25,  # Full quality
+            guidance_scale=style["guidance_scale"],
+            progress_callback=progress_callback,
+            enable_prompt_enhancement=True
+        )
+
+    def get_memory_status(self) -> Dict[str, Any]:
+        """Enhanced memory status reporting"""
+        status = {"device": self.device}
+
+        if torch.cuda.is_available():
+            allocated = torch.cuda.memory_allocated() / 1024**3
+            total = torch.cuda.get_device_properties(0).total_memory / 1024**3
+            cached = torch.cuda.memory_reserved() / 1024**3
+
+            status.update({
+                "gpu_allocated_gb": round(allocated, 2),
+                "gpu_total_gb": round(total, 2),
+                "gpu_cached_gb": round(cached, 2),
+                "gpu_free_gb": round(total - allocated, 2),
+                "gpu_usage_percent": round((allocated / total) * 100, 1),
+                "generation_count": self.generation_count
+            })
+
+        return status

ui_manager.py

@@ -0,0 +1,513 @@
+import logging
+import time
+from pathlib import Path
+from typing import Optional, Tuple
+from PIL import Image
+import numpy as np
+import cv2
+import gradio as gr
+import spaces
+
+from scene_weaver_core import SceneWeaverCore
+from css_styles import CSSStyles
+from scene_templates import SceneTemplateManager
+
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.INFO)
+
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s [%(name)s] %(levelname)s: %(message)s',
+    datefmt='%H:%M:%S'
+)
+
+
+class UIManager:
+    """Gradio UI with enhanced memory management and professional design"""
+
+    def __init__(self):
+        self.sceneweaver = SceneWeaverCore()
+        self.template_manager = SceneTemplateManager()
+        self.generation_history = []
+        self._preview_sensitivity = 0.5
+
+    def apply_template(self, display_name: str, current_negative: str) -> Tuple[str, str, float]:
+        """
+        Apply a scene template to the prompt fields.
+
+        Args:
+            display_name: The display name from dropdown (e.g., "🏢 Modern Office")
+            current_negative: Current negative prompt value
+
+        Returns:
+            Tuple of (prompt, negative_prompt, guidance_scale)
+        """
+        if not display_name:
+            return "", current_negative, 7.5
+
+        # Convert display name to template key
+        template_key = self.template_manager.get_template_key_from_display(display_name)
+        if not template_key:
+            return "", current_negative, 7.5
+
+        template = self.template_manager.get_template(template_key)
+        if template:
+            prompt = template.prompt
+            negative = self.template_manager.get_negative_prompt_for_template(
+                template_key, current_negative
+            )
+            guidance = template.guidance_scale
+            return prompt, negative, guidance
+
+        return "", current_negative, 7.5
+
+    def quick_preview(
+        self,
+        uploaded_image: Optional[Image.Image],
+        sensitivity: float = 0.5
+    ) -> Optional[Image.Image]:
+        """
+        Generate quick foreground preview using lightweight traditional methods.
+
+        Args:
+            uploaded_image: Uploaded PIL Image
+            sensitivity: Detection sensitivity (0.0 - 1.0)
+
+        Returns:
+            Preview image with colored overlay or None
+        """
+        if uploaded_image is None:
+            return None
+
+        try:
+            logger.info(f"Generating quick preview (sensitivity={sensitivity:.2f})")
+
+            img_array = np.array(uploaded_image.convert('RGB'))
+            height, width = img_array.shape[:2]
+
+            max_preview_size = 512
+            if max(width, height) > max_preview_size:
+                scale = max_preview_size / max(width, height)
+                new_w = int(width * scale)
+                new_h = int(height * scale)
+                img_array = cv2.resize(img_array, (new_w, new_h), interpolation=cv2.INTER_AREA)
+                height, width = new_h, new_w
+
+            gray = cv2.cvtColor(img_array, cv2.COLOR_RGB2GRAY)
+            blurred = cv2.GaussianBlur(gray, (5, 5), 0)
+
+            low_threshold = int(30 + (1 - sensitivity) * 50)
+            high_threshold = int(100 + (1 - sensitivity) * 100)
+            edges = cv2.Canny(blurred, low_threshold, high_threshold)
+
+            kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (7, 7))
+            dilated = cv2.dilate(edges, kernel, iterations=2)
+
+            contours, _ = cv2.findContours(dilated, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+
+            mask = np.zeros((height, width), dtype=np.uint8)
+
+            if contours:
+                sorted_contours = sorted(contours, key=cv2.contourArea, reverse=True)
+                min_area = (width * height) * 0.01 * (1 - sensitivity)
+                for contour in sorted_contours:
+                    if cv2.contourArea(contour) > min_area:
+                        cv2.fillPoly(mask, [contour], 255)
+
+            kernel_close = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (11, 11))
+            mask = cv2.morphologyEx(mask, cv2.MORPH_CLOSE, kernel_close)
+
+            overlay = img_array.copy().astype(np.float32)
+
+            fg_mask = mask > 127
+            overlay[fg_mask] = overlay[fg_mask] * 0.5 + np.array([0, 255, 0]) * 0.5
+
+            bg_mask = mask <= 127
+            overlay[bg_mask] = overlay[bg_mask] * 0.5 + np.array([255, 0, 0]) * 0.5
+
+            overlay = np.clip(overlay, 0, 255).astype(np.uint8)
+
+            original_size = uploaded_image.size
+            preview_image = Image.fromarray(overlay)
+            if preview_image.size != original_size:
+                preview_image = preview_image.resize(original_size, Image.LANCZOS)
+
+            logger.info("Quick preview generated successfully")
+            return preview_image
+
+        except Exception as e:
+            logger.error(f"Quick preview failed: {e}")
+            return None
+
+    def _save_result(self, combined_image: Image.Image, prompt: str):
+        """Save result with memory-conscious history management"""
+        if not combined_image:
+            return
+
+        output_dir = Path("outputs")
+        output_dir.mkdir(exist_ok=True)
+
+        combined_image.save(output_dir / "latest_combined.png")
+
+        self.generation_history.append({
+            "prompt": prompt,
+            "timestamp": time.time()
+        })
+
+        max_history = self.sceneweaver.max_history
+        if len(self.generation_history) > max_history:
+            self.generation_history = self.generation_history[-max_history:]
+
+    @spaces.GPU(duration=120)
+    def generate_handler(
+        self,
+        uploaded_image: Optional[Image.Image],
+        prompt: str,
+        combination_mode: str,
+        focus_mode: str,
+        negative_prompt: str,
+        steps: int,
+        guidance: float,
+        progress=gr.Progress()
+    ):
+        """Enhanced generation handler with memory management and ZeroGPU support"""
+
+        if uploaded_image is None:
+            return None, None, None, "Please upload an image to get started!", gr.update(visible=False)
+
+        if not prompt.strip():
+            return None, None, None, "Please describe the background scene you'd like!", gr.update(visible=False)
+
+        try:
+            if not self.sceneweaver.is_initialized:
+                progress(0.05, desc="Loading AI models (first time may take 2-3 minutes)...")
+
+                def init_progress(msg, pct):
+                    if pct < 30:
+                        desc = "Loading image analysis models..."
+                    elif pct < 60:
+                        desc = "Loading Stable Diffusion XL..."
+                    elif pct < 90:
+                        desc = "Applying memory optimizations..."
+                    else:
+                        desc = "Almost ready..."
+                    progress(0.05 + (pct/100) * 0.2, desc=desc)
+
+                self.sceneweaver.load_models(progress_callback=init_progress)
+
+            def gen_progress(msg, pct):
+                if pct < 20:
+                    desc = "Analyzing your image..."
+                elif pct < 50:
+                    desc = "Generating background scene..."
+                elif pct < 80:
+                    desc = "Blending foreground and background..."
+                elif pct < 95:
+                    desc = "Applying final touches..."
+                else:
+                    desc = "Complete!"
+                progress(0.25 + (pct/100) * 0.75, desc=desc)
+
+            result = self.sceneweaver.generate_and_combine(
+                original_image=uploaded_image,
+                prompt=prompt,
+                combination_mode=combination_mode,
+                focus_mode=focus_mode,
+                negative_prompt=negative_prompt,
+                num_inference_steps=int(steps),
+                guidance_scale=float(guidance),
+                progress_callback=gen_progress
+            )
+
+            if result["success"]:
+                combined = result["combined_image"]
+                generated = result["generated_scene"]
+                original = result["original_image"]
+
+                self._save_result(combined, prompt)
+
+                status_msg = "Image created successfully!"
+
+                return combined, generated, original, status_msg, gr.update(visible=True)
+            else:
+                error_msg = result.get("error", "Something went wrong")
+                return None, None, None, f"Error: {error_msg}", gr.update(visible=False)
+
+        except Exception as e:
+            import traceback
+            error_traceback = traceback.format_exc()
+            logger.error(f"Generation handler error: {str(e)}")
+            logger.error(f"Traceback:\n{error_traceback}")
+            return None, None, None, f"Error: {str(e)}", gr.update(visible=False)
+
+    def create_interface(self):
+        """Create professional user interface"""
+
+        css = CSSStyles.get_main_css()
+
+        with gr.Blocks(
+            css=css,
+            title="SceneWeaver - AI Background Generator",
+            theme=gr.themes.Soft()
+        ) as interface:
+
+            # Header
+            gr.HTML("""
+            <div class="main-header">
+                <h1 class="main-title">
+                    <span class="title-emoji">🎨</span>
+                    SceneWeaver
+                </h1>
+                <p class="main-subtitle">AI-powered background generation with professional edge processing</p>
+            </div>
+            """)
+
+            with gr.Row():
+                # Left Column - Input controls
+                with gr.Column(scale=1, min_width=350, elem_classes=["feature-card"]):
+                    gr.HTML("""
+                    <div class="card-content">
+                        <h3 class="card-title">
+                            <span class="section-emoji">📸</span>
+                            Upload & Generate
+                        </h3>
+                    </div>
+                    """)
+
+                    uploaded_image = gr.Image(
+                        label="Upload Your Image",
+                        type="pil",
+                        height=280,
+                        elem_classes=["input-field"]
+                    )
+
+                    # Scene Template Selector
+                    with gr.Accordion("Scene Templates", open=False):
+                        template_dropdown = gr.Dropdown(
+                            label="Select a Scene",
+                            choices=[""] + self.template_manager.get_template_choices_sorted(),
+                            value="",
+                            info="24 curated scenes sorted A-Z",
+                            elem_classes=["template-dropdown"]
+                        )
+
+                    prompt_input = gr.Textbox(
+                        label="Background Scene Description",
+                        placeholder="Select a template above or describe your own scene...",
+                        lines=3,
+                        elem_classes=["input-field"]
+                    )
+
+                    combination_mode = gr.Dropdown(
+                        label="Composition Mode",
+                        choices=["center", "left_half", "right_half", "full"],
+                        value="center",
+                        info="center=Smart Center | left_half=Left Half | right_half=Right Half | full=Full Image",
+                        elem_classes=["input-field"]
+                    )
+
+                    focus_mode = gr.Dropdown(
+                        label="Focus Mode",
+                        choices=["person", "scene"],
+                        value="person",
+                        info="person=Tight Crop | scene=Include Surrounding Objects",
+                        elem_classes=["input-field"]
+                    )
+
+                    with gr.Accordion("Advanced Options", open=False):
+                        negative_prompt = gr.Textbox(
+                            label="Negative Prompt",
+                            value="blurry, low quality, distorted, people, characters",
+                            lines=2,
+                            elem_classes=["input-field"]
+                        )
+
+                        steps_slider = gr.Slider(
+                            label="Quality Steps",
+                            minimum=15,
+                            maximum=50,
+                            value=25,
+                            step=5,
+                            elem_classes=["input-field"]
+                        )
+
+                        guidance_slider = gr.Slider(
+                            label="Guidance Scale",
+                            minimum=5.0,
+                            maximum=15.0,
+                            value=7.5,
+                            step=0.5,
+                            elem_classes=["input-field"]
+                        )
+
+                    generate_btn = gr.Button(
+                        "Generate Background",
+                        variant="primary",
+                        size="lg",
+                        elem_classes=["primary-button"]
+                    )
+
+                # Right Column - Results display
+                with gr.Column(scale=2, elem_classes=["feature-card"], elem_id="results-gallery-centered"):
+                    gr.HTML("""
+                    <div class="card-content">
+                        <h3 class="card-title">
+                            <span class="section-emoji">🎭</span>
+                            Results Gallery
+                        </h3>
+                    </div>
+                    """)
+
+                    # Loading notice
+                    gr.HTML("""
+                    <div class="loading-notice">
+                        <span class="loading-notice-icon">⏱️</span>
+                        <span class="loading-notice-text">
+                            <strong>First-time users:</strong> Initial model loading takes 1-2 minutes.
+                            Subsequent generations are much faster (~30s).
+                        </span>
+                    </div>
+                    """)
+
+                    # Quick start guide
+                    gr.HTML("""
+                    <details class="user-guidance-panel">
+                        <summary class="guidance-summary">
+                            <span class="emoji-enhanced">💡</span>
+                            Quick Start Guide
+                        </summary>
+                        <div class="guidance-content">
+                            <p><strong>Step 1:</strong> Upload any image with a clear subject</p>
+                            <p><strong>Step 2:</strong> Describe or Choose your desired background scene</p>
+                            <p><strong>Step 3:</strong> Choose composition mode (center works best)</p>
+                            <p><strong>Step 4:</strong> Click Generate and wait for the magic!</p>
+                            <p><strong>Tip:</strong> For dark clothing, ensure good lighting in original photo.</p>
+                        </div>
+                    </details>
+                    """)
+
+                    with gr.Tabs():
+                        with gr.TabItem("Final Result"):
+                            combined_output = gr.Image(
+                                label="Your Generated Image",
+                                elem_classes=["result-gallery"],
+                                show_label=False
+                            )
+                        with gr.TabItem("Background"):
+                            generated_output = gr.Image(
+                                label="Generated Background",
+                                elem_classes=["result-gallery"],
+                                show_label=False
+                            )
+                        with gr.TabItem("Original"):
+                            original_output = gr.Image(
+                                label="Processed Original",
+                                elem_classes=["result-gallery"],
+                                show_label=False
+                            )
+
+                    status_output = gr.Textbox(
+                        label="Status",
+                        value="Ready to create! Upload an image and describe your vision.",
+                        interactive=False,
+                        elem_classes=["status-panel", "status-ready"]
+                    )
+
+                    with gr.Row():
+                        download_btn = gr.DownloadButton(
+                            "Download Result",
+                            value=None,
+                            visible=False,
+                            elem_classes=["secondary-button"]
+                        )
+                        clear_btn = gr.Button(
+                            "Clear All",
+                            elem_classes=["secondary-button"]
+                        )
+                        memory_btn = gr.Button(
+                            "Clean Memory",
+                            elem_classes=["secondary-button"]
+                        )
+
+            # Footer with tech credits
+            gr.HTML("""
+            <div class="app-footer">
+                <div class="footer-powered">
+                    <p class="footer-powered-title">Powered By</p>
+                    <div class="footer-tech-grid">
+                        <span class="footer-tech-item">Stable Diffusion XL</span>
+                        <span class="footer-tech-item">OpenCLIP</span>
+                        <span class="footer-tech-item">BiRefNet</span>
+                        <span class="footer-tech-item">rembg</span>
+                        <span class="footer-tech-item">PyTorch</span>
+                        <span class="footer-tech-item">Gradio</span>
+                    </div>
+                </div>
+                <div class="footer-divider"></div>
+                <p class="footer-copyright">
+                    SceneWeaver &copy; 2025 &nbsp;|&nbsp;
+                    Built with <a href="https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0" target="_blank">SDXL</a>
+                    and <a href="https://github.com/mlfoundations/open_clip" target="_blank">OpenCLIP</a>
+                </p>
+            </div>
+            """)
+
+            # Event handlers
+            # Template selection handler
+            template_dropdown.change(
+                fn=self.apply_template,
+                inputs=[template_dropdown, negative_prompt],
+                outputs=[prompt_input, negative_prompt, guidance_slider]
+            )
+
+            generate_btn.click(
+                fn=self.generate_handler,
+                inputs=[
+                    uploaded_image,
+                    prompt_input,
+                    combination_mode,
+                    focus_mode,
+                    negative_prompt,
+                    steps_slider,
+                    guidance_slider
+                ],
+                outputs=[
+                    combined_output,
+                    generated_output,
+                    original_output,
+                    status_output,
+                    download_btn
+                ]
+            )
+
+            clear_btn.click(
+                fn=lambda: (None, None, None, "Ready to create!", gr.update(visible=False)),
+                outputs=[combined_output, generated_output, original_output, status_output, download_btn]
+            )
+
+            memory_btn.click(
+                fn=lambda: self.sceneweaver._ultra_memory_cleanup() or "Memory cleaned!",
+                outputs=[status_output]
+            )
+
+            combined_output.change(
+                fn=lambda img: gr.update(value="outputs/latest_combined.png", visible=True) if (img is not None) else gr.update(visible=False),
+                inputs=[combined_output],
+                outputs=[download_btn]
+            )
+
+        return interface
+
+    def launch(self, share: bool = True, debug: bool = False):
+        """Launch the UI interface"""
+        interface = self.create_interface()
+
+        return interface.launch(
+            share=share,
+            debug=debug,
+            show_error=True,
+            height=800,
+            favicon_path=None,
+            ssl_verify=False,
+            quiet=False
+        )