Upload 90 files

.gitattributes

@@ -33,3 +33,10 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+backend/text_editor/fonts/hind_regular.ttf filter=lfs diff=lfs merge=lfs -text
+backend/text_editor/fonts/kalam_regular.ttf filter=lfs diff=lfs merge=lfs -text
+backend/text_editor/fonts/martel_regular.ttf filter=lfs diff=lfs merge=lfs -text
+backend/text_editor/fonts/notosansdevanagari_regular.ttf filter=lfs diff=lfs merge=lfs -text
+backend/text_editor/fonts/rozhaone_regular.ttf filter=lfs diff=lfs merge=lfs -text
+backend/text_editor/fonts/teko_regular.ttf filter=lfs diff=lfs merge=lfs -text
+backend/text_editor/fonts/yatraone_regular.ttf filter=lfs diff=lfs merge=lfs -text

README.md

@@ -1,19 +1,113 @@
+# ⚡ Antigravity Studio - AI Image & Document Workspace
+
+A complete, production-grade, state-of-the-art **Image & PDF Manipulation Web Application** consisting of two primary workspaces:
+1. **AI Background Remover Workspace**: Isolate foreground subjects with U²-Net deep learning or GrabCut, refine fine hair details with Guided Filter matting, and generate customizable realistic drop shadows.
+2. **AI In-Image Text Editor Workspace**: Automatically detect, erase, and replace text in images or multi-page PDFs while perfectly matching original fonts, sizes, and ink colors.
+
+Built with **Streamlit** (frontend) and **Python + OpenCV + Deep Learning** (backend).
+
+---
+
+## ✨ Workspace 1: AI Background Remover
+
+Allows users to upload an image, extract the subject with professional-grade borders, and customize visual compositions.
+
+- **AI U²-Net Neural Network Mode**: Leverages pre-trained deep learning to automatically segment complex shapes (like portraits, hair, and soft details) without bounding box configurations.
+- **GrabCut General Subject Mode**: Detects bounding boxes automatically or supports manual coordinate tuning.
+- **Signature & Text (Ink Extraction) Mode**: Uses color distance maps to isolate handwritten ink from paper backdrops (perfect for signatures).
+- **Advanced Edge Matting**:
+  - *Guided Filter Matting*: An edge-preserving linear filtering algorithm that aligns alpha transitions to individual hair fibers.
+  - *Morphological Closing*: Fills inner holes and smooths contours.
+  - *Speckle Filtering*: Cleans isolated floating noise.
+- **Realistic Drop Shadow Engine**: Generates natural drop shadows beneath isolated subjects. Customize opacity, blur softness, offset distance, and angle.
+- **Interactive Composite Studio**: Composite transparent cutouts over Checkerboard grids, Solid colors, gradients (*Midnight Glow, Sunset Studio, Neon Cyber*), or uploaded background images.
+
 ---
-title: Helpful AI
-emoji: 🚀
-colorFrom: red
-colorTo: red
-sdk: docker
-app_port: 8501
-tags:
-- streamlit
-pinned: false
-short_description: For Background remove , DSLR Blurring , Text Editing
+
+## ✨ Workspace 2: AI Document & PDF Text Editor
+
+Allows users to upload an image or multi-page PDF, find text, and perform clean in-place corrections.
+
+- **Automated Layout Scan**: Scans images or document page textures using **EasyOCR** to discover bounding boxes of all text segments.
+- **Translucent OCR Overlays**: Renders glowing overlays displaying editable text fields in the document.
+- **Zero-Configuration PDF Engine**: Powered by **PyMuPDF (Fitz)**. Render multi-page PDFs, navigate pages, and compile edited page images back into a single multi-page PDF document.
+- **Adaptive Ink & Paper Color Sampling**: Extracts the median BGR ink color (foreground character strokes) and surrounding paper texture color (background) using Otsu's adaptive binarization of characters.
+- **Seamless Texture-Preserving Eraser**: Creates a character-level binary mask, dilates it by 2px, and runs OpenCV Fast Inpainting (**Telea's algorithm**). This erases old text while preserving paper folds, grain, gridlines, and shadows.
+- **Adaptive Text Synthesis**: Scales the replacement text according to the bounding box height, matches standard font families (Serif, Sans-Serif, Monospace), and renders it anti-aliased with the sampled ink color.
+
+---
+
+## 📂 Project Structure
+
+```text
+e:\bg remover\
+├── app.py                     # Main Streamlit dashboard routing entrypoint & CSS styles
+├── requirements.txt           # Unified dependency manifest
+├── README.md                  # Detailed workspace and setup documentation
+│
+├── frontend/                  # Modern UI Layout Modules
+│   ├── __init__.py
+│   ├── home.py                # Premium Glassmorphic Studio Navigation landing page
+│   ├── bg_remover_ui.py       # Custom Background Remover controls and workflows
+│   ├── text_editor_ui.py      # PDF page navigation, OCR list, Find/Replace editor
+│   ├── preview_ui.py          # Before/After comparison and backdrop composites
+│   └── download_ui.py         # Downscaled/lazy high-res download compiler
+│
+└── backend/                   # Algorithms and Heavy Processing Backends
+    ├── __init__.py
+    ├── utilities.py           # Image format converters and checkerboard pattern generators
+    │
+    ├── bg_remover/            # Background Remover Subpackage
+    │   ├── __init__.py
+    │   ├── segmentation.py    # GrabCut, contour analysis, and corner color GMM seeding
+    │   ├── edge_detection.py  # Fast Guided Filter matting and morphological refinements
+    │   ├── shadow_generator.py# Affine transformation drop shadow translations and blenders
+    │   └── image_processor.py # Background remover high-level pipeline orchestrator
+    │
+    └── text_editor/           # Text Editor & Document Subpackage
+        ├── __init__.py
+        ├── pdf_processor.py   # PyMuPDF page extractors and PDF compilers
+        ├── ocr_engine.py      # EasyOCR layout scanning engine
+        ├── color_detector.py  # Character-level ink/paper color samplers
+        ├── font_detector.py   # System TTF font loader and height-based size mapper
+        ├── text_replacer.py   # Telea inpainter and PIL anti-aliased text renderer
+        └── orchestrator.py    # Text correction orchestrator
+```
+
+---
+
+## 🚀 Installation & Running Locally
+
+Ensure you have **Python 3.10+** installed. Follow these steps:
+
+### 1. Install Dependencies
+Open a terminal in the root of the workspace (`e:\bg remover\`) and run:
+```bash
+pip install -r requirements.txt
+```
+
+### 2. Run the Application
+Start the Streamlit dashboard:
+```bash
+streamlit run app.py
+```
+
+### 3. Open in Browser
+The local server will start and prompt you to open the dashboard at:
+- **Local URL**: `http://localhost:8501`
+
 ---
 
-# Welcome to Streamlit!
+## 🛠️ Offline Verification & Test Suites
 
-Edit `/src/streamlit_app.py` to customize this app to your heart's desire. :heart:
+We have built extensive automated tests to guarantee system stability and code correctness:
 
-If you have any questions, checkout our [documentation](https://docs.streamlit.io) and [community
-forums](https://discuss.streamlit.io).
+- **Background Remover Tests**:
+  ```bash
+  python "C:\Users\Asus\.gemini\antigravity\brain\76a54bfc-09a7-4a96-809d-8b8c797bd925\scratch\test_pipeline.py"
+  ```
+- **Document Text Editor Tests**:
+  ```bash
+  python "C:\Users\Asus\.gemini\antigravity\brain\76a54bfc-09a7-4a96-809d-8b8c797bd925\scratch\test_text_editor.py"
+  ```
+Both test suites should print `[SUCCESS]` and pass seamlessly!

app.py

@@ -0,0 +1,183 @@
+import streamlit as st
+import os
+import sys
+
+# Add current workspace directory to sys.path to allow absolute imports
+sys.path.append(os.path.abspath(os.path.dirname(__file__)))
+
+from frontend.home import render_sidebar_brand, render_home_dashboard
+from frontend.bg_remover_ui import render_bg_remover_ui
+from frontend.text_editor_ui import render_text_editor_ui
+from frontend.dslr_blur_ui import render_dslr_blur_ui
+
+# Set Streamlit page config
+st.set_page_config(
+    page_title="Antigravity Studio - AI Image & Document Workspace",
+    page_icon="⚡",
+    layout="wide",
+    initial_sidebar_state="expanded"
+)
+
+# Custom CSS for Glassmorphic Dark Theme with glowing neon accents
+st.markdown(
+    """
+    <style>
+    /* Import modern Google Fonts */
+    @import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap');
+    
+    /* Apply fonts and background styles */
+    .stApp {
+        background-color: #0E1117;
+        font-family: 'Inter', sans-serif;
+        color: #E2E8F0;
+    }
+    
+    /* Header Custom Styles */
+    .gradient-title {
+        font-family: 'Inter', sans-serif;
+        font-weight: 800;
+        font-size: 2.8rem;
+        background: linear-gradient(135deg, #00F0FF 0%, #FF007F 100%);
+        -webkit-background-clip: text;
+        -webkit-text-fill-color: transparent;
+        text-align: center;
+        margin-top: 10px;
+        margin-bottom: 5px;
+        letter-spacing: -1px;
+    }
+    
+    .subtitle {
+        text-align: center;
+        color: #8A99AD;
+        font-size: 1.1rem;
+        font-weight: 300;
+        margin-bottom: 30px;
+    }
+    
+    /* Glassmorphism Containers */
+    .glass-card {
+        background: rgba(255, 255, 255, 0.03);
+        border-radius: 16px;
+        border: 1px solid rgba(255, 255, 255, 0.08);
+        padding: 24px;
+        backdrop-filter: blur(12px);
+        -webkit-backdrop-filter: blur(12px);
+        box-shadow: 0 8px 32px 0 rgba(0, 0, 0, 0.37);
+        margin-bottom: 20px;
+    }
+    
+    /* Upload UI wrapper */
+    .upload-container {
+        padding: 40px;
+        background: rgba(0, 240, 255, 0.01);
+        border: 1px dashed rgba(0, 240, 255, 0.3);
+        transition: all 0.3s ease;
+    }
+    
+    .upload-container:hover {
+        border-color: #FF007F;
+        background: rgba(255, 0, 127, 0.01);
+    }
+    
+    /* Custom Success Badge */
+    .success-badge {
+        background: rgba(0, 240, 255, 0.1);
+        color: #00F0FF;
+        border: 1px solid rgba(0, 240, 255, 0.2);
+        border-radius: 8px;
+        padding: 10px 15px;
+        font-size: 0.9rem;
+        margin: 15px 0;
+        text-align: center;
+    }
+    
+    /* Labels and Headers */
+    .preview-label {
+        font-size: 0.8rem;
+        font-weight: 700;
+        letter-spacing: 1.5px;
+        color: #FF007F;
+        margin-bottom: 10px;
+        text-align: center;
+        text-transform: uppercase;
+    }
+    
+    /* Custom Styled Sliders & Widgets in Sidebar */
+    [data-testid="stSidebar"] {
+        background-color: #0A0D14;
+        border-right: 1px solid rgba(255, 255, 255, 0.05);
+    }
+    
+    [data-testid="stSidebar"] .stMarkdown h2, [data-testid="stSidebar"] .stMarkdown h3 {
+        color: #00F0FF;
+        font-weight: 600;
+    }
+    
+    /* Streamlit buttons customized */
+    div.stButton > button {
+        background: linear-gradient(135deg, #00F0FF 0%, #7000FF 100%);
+        color: white;
+        border: none;
+        border-radius: 8px;
+        padding: 10px 24px;
+        font-weight: 600;
+        transition: all 0.2s ease-in-out;
+        box-shadow: 0 4px 15px rgba(0, 240, 255, 0.2);
+    }
+    
+    div.stButton > button:hover {
+        background: linear-gradient(135deg, #FF007F 0%, #7000FF 100%);
+        transform: translateY(-2px);
+        box-shadow: 0 6px 20px rgba(255, 0, 127, 0.35);
+        color: white;
+    }
+    
+    /* Glowing accents */
+    .glow-accent {
+        text-shadow: 0 0 10px rgba(0, 240, 255, 0.5);
+    }
+    
+    </style>
+    """,
+    unsafe_allow_html=True
+)
+
+# ----------------- SESSION STATE INITIALIZATION -----------------
+if "active_workspace" not in st.session_state:
+    st.session_state.active_workspace = "Home"
+
+# ----------------- SIDEBAR BRANDING & ROUTING -----------------
+render_sidebar_brand()
+
+st.sidebar.markdown("### 🧭 NAVIGATION")
+nav_choice = st.sidebar.selectbox(
+    "Active Workspace",
+    ["Home Dashboard", "AI Background Remover", "AI DSLR Background Blur", "AI In-Image Text Editor"],
+    index=["Home Dashboard", "AI Background Remover", "AI DSLR Background Blur", "AI In-Image Text Editor"].index(
+        "Home Dashboard" if st.session_state.active_workspace == "Home" else st.session_state.active_workspace
+    ),
+    key="nav_choice_select"
+)
+
+# Sync sidebar navigation selection with active session state
+choice_mapped = "Home" if nav_choice == "Home Dashboard" else nav_choice
+if choice_mapped != st.session_state.active_workspace:
+    st.session_state.active_workspace = choice_mapped
+    st.rerun()
+
+# Quick nav back to Home from sidebar footer
+st.sidebar.markdown("<br><br><br>", unsafe_allow_html=True)
+if st.session_state.active_workspace != "Home":
+    if st.sidebar.button("← Back to Dashboard", use_container_width=True):
+        st.session_state.active_workspace = "Home"
+        st.rerun()
+
+# ----------------- WORKSPACE RENDERING -----------------
+if st.session_state.active_workspace == "Home":
+    render_home_dashboard()
+elif st.session_state.active_workspace == "AI Background Remover":
+    render_bg_remover_ui()
+elif st.session_state.active_workspace == "AI DSLR Background Blur":
+    render_dslr_blur_ui()
+elif st.session_state.active_workspace == "AI In-Image Text Editor":
+    render_text_editor_ui()

backend/__init__.py

@@ -0,0 +1 @@
+# Backend package

backend/bg_remover/__init__.py

@@ -0,0 +1 @@
+# Background remover subpackage

backend/bg_remover/edge_detection.py

@@ -0,0 +1,85 @@
+import cv2
+import numpy as np
+
+def guided_filter(I: np.ndarray, p: np.ndarray, r: int, eps: float) -> np.ndarray:
+    """
+    Fast Guided Filter implementation for edge-preserving matting.
+    I: Guidance image (BGR, uint8)
+    p: Grayscale mask to filter (uint8 or float, normalized to [0, 1])
+    r: Local window radius
+    eps: Regularization parameter
+    """
+    if I.dtype == np.uint8:
+        I = I.astype(np.float32) / 255.0
+    else:
+        I = I.astype(np.float32)
+        
+    p = p.astype(np.float32)
+    
+    # Extract grayscale guidance for fast processing
+    if len(I.shape) == 3:
+        I_gray = cv2.cvtColor(I, cv2.COLOR_BGR2GRAY)
+    else:
+        I_gray = I
+        
+    # Local window means
+    mean_I = cv2.boxFilter(I_gray, -1, (r, r))
+    mean_p = cv2.boxFilter(p, -1, (r, r))
+    
+    mean_II = cv2.boxFilter(I_gray * I_gray, -1, (r, r))
+    mean_Ip = cv2.boxFilter(I_gray * p, -1, (r, r))
+    
+    # Variance & Covariance
+    var_I = mean_II - mean_I * mean_I
+    cov_Ip = mean_Ip - mean_I * mean_p
+    
+    # Solve linear coefficients
+    a = cov_Ip / (var_I + eps)
+    b = mean_p - a * mean_I
+    
+    # Average coefficients
+    mean_a = cv2.boxFilter(a, -1, (r, r))
+    mean_b = cv2.boxFilter(b, -1, (r, r))
+    
+    # Reconstruct filtered mask
+    q = mean_a * I_gray + mean_b
+    return np.clip(q, 0.0, 1.0)
+
+def refine_mask(mask: np.ndarray, 
+                img: np.ndarray = None,
+                closing_size: int = 5, 
+                keep_largest_only: bool = True,
+                feather_radius: int = 3,
+                matting_enabled: bool = False,
+                matting_radius: int = 10,
+                matting_eps: float = 1e-3) -> np.ndarray:
+    """
+    Refines a binary mask by morphological closing, speckle filtering, and edge matting/feathering.
+    """
+    h, w = mask.shape[:2]
+    refined = mask.copy()
+    
+    # 1. Morphological closing to fill holes inside the object
+    if closing_size > 0:
+        kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (closing_size, closing_size))
+        refined = cv2.morphologyEx(refined, cv2.MORPH_CLOSE, kernel)
+        refined = cv2.morphologyEx(refined, cv2.MORPH_OPEN, kernel) # clean small edge noise
+        
+    # 2. Keep only the largest connected component to eliminate floating background noise
+    if keep_largest_only:
+        num_labels, labels, stats, _ = cv2.connectedComponentsWithStats(refined)
+        if num_labels > 1:
+            largest_label = 1 + np.argmax(stats[1:, cv2.CC_STAT_AREA])
+            refined = np.where(labels == largest_label, 255, 0).astype(np.uint8)
+            
+    # 3. Apply Edge Matting (Guided Filter) or Edge Feathering
+    if matting_enabled and img is not None:
+        mask_norm = refined.astype(np.float32) / 255.0
+        filtered_mask = guided_filter(img, mask_norm, matting_radius, matting_eps)
+        refined = (filtered_mask * 255.0).astype(np.uint8)
+    elif feather_radius > 0:
+        ksize = 2 * feather_radius + 1
+        refined_floats = cv2.GaussianBlur(refined.astype(float), (ksize, ksize), 0)
+        refined = np.clip(refined_floats, 0, 255).astype(np.uint8)
+        
+    return refined

backend/bg_remover/image_processor.py

@@ -0,0 +1,194 @@
+import cv2
+import numpy as np
+from PIL import Image
+from backend.utilities import pil_to_cv, cv_to_pil, resize_for_processing
+from backend.bg_remover.segmentation import detect_automatic_bounding_box, run_grabcut
+from backend.bg_remover.edge_detection import refine_mask
+from backend.bg_remover.shadow_generator import generate_drop_shadow
+
+try:
+    from rembg import remove as rembg_remove
+    REMBG_AVAILABLE = True
+except ImportError:
+    REMBG_AVAILABLE = False
+
+_session_cache = {}
+
+def get_rembg_session(model_name: str):
+    """Retrieves or initializes a cached rembg model session to prevent reloading weights."""
+    global _session_cache
+    if model_name not in _session_cache:
+        try:
+            from rembg import new_session
+            _session_cache[model_name] = new_session(model_name)
+        except Exception as e:
+            _session_cache[model_name] = None
+    return _session_cache[model_name]
+
+class ImageProcessor:
+    """
+    High-level orchestrator class to execute the background removal image processing pipeline.
+    """
+    @staticmethod
+    def process_image(
+        pil_image: Image.Image,
+        rect: tuple = None,
+        margin_percentage: float = 5.0,
+        iter_count: int = 5,
+        bg_seed_sensitivity: float = 35.0,
+        closing_size: int = 5,
+        keep_largest_only: bool = True,
+        feather_radius: int = 3,
+        matting_enabled: bool = True,
+        matting_radius: int = 10,
+        matting_eps: float = 1e-3,
+        shadow_enabled: bool = False,
+        shadow_opacity: float = 0.5,
+        shadow_blur: int = 15,
+        shadow_distance: int = 20,
+        shadow_angle: float = 45.0,
+        max_preview_dim: int = None,
+        subject_mode: str = "AI Neural Network (U²-Net)"
+    ) -> dict:
+        """
+        Processes the input PIL image and returns a dictionary of output PIL images.
+        """
+        # 1. Automatically normalize EXIF camera orientation tags
+        from PIL import ImageOps
+        pil_image = ImageOps.exif_transpose(pil_image)
+        
+        # Convert PIL to OpenCV (BGR)
+        cv_raw = pil_to_cv(pil_image)
+        
+        # 2. Downscale for interactive preview speed if requested
+        if max_preview_dim is not None:
+            cv_img = resize_for_processing(cv_raw, max_preview_dim)
+        else:
+            cv_img = cv_raw.copy()
+            
+        h, w = cv_img.shape[:2]
+        
+        # 3. Bounding Box & Segmentation Determination
+        is_neural = (subject_mode in ["AI BiRefNet (SOTA General)", "AI U²-Net (Legacy Neural)", "AI Neural Network (U²-Net)"] and REMBG_AVAILABLE)
+        
+        if is_neural:
+            try:
+                # Resolve correct model session
+                if "BiRefNet" in subject_mode:
+                    session = get_rembg_session("birefnet-general")
+                else:
+                    session = get_rembg_session("u2net")
+                    
+                if max_preview_dim is not None:
+                    w_p, h_p = cv_img.shape[1], cv_img.shape[0]
+                    pil_preview = pil_image.resize((w_p, h_p), Image.Resampling.LANCZOS)
+                    cutout_pil = rembg_remove(pil_preview, session=session)
+                else:
+                    cutout_pil = rembg_remove(pil_image, session=session)
+                    
+                cv_cutout = pil_to_cv(cutout_pil)
+                refined_mask = cv_cutout[:, :, 3].copy()
+                
+                # Resilient shape normalization to handle EXIF or transpose mismatches from rembg
+                if refined_mask.shape[:2] != (h, w):
+                    if refined_mask.shape[0] == w and refined_mask.shape[1] == h:
+                        refined_mask = refined_mask.T
+                    else:
+                        refined_mask = cv2.resize(refined_mask, (w, h), interpolation=cv2.INTER_LINEAR)
+                        
+                actual_rect = (0, 0, w, h)
+            except Exception as e:
+                is_neural = False
+                
+        if not is_neural:
+            if subject_mode == "Signature & Text (Ink)":
+                pw = max(2, min(20, w // 20))
+                ph = max(2, min(20, h // 20))
+                c_tl = np.mean(cv_img[0:ph, 0:pw, :3], axis=(0, 1))
+                c_tr = np.mean(cv_img[0:ph, w-pw:w, :3], axis=(0, 1))
+                c_bg = (c_tl + c_tr) / 2.0
+                
+                dist = np.sqrt(np.sum((cv_img[:, :, :3] - c_bg) ** 2, axis=2))
+                
+                low_t = 15.0
+                high_t = 45.0
+                alpha = np.clip((dist - low_t) / (high_t - low_t) * 255.0, 0, 255).astype(np.uint8)
+                
+                refined_mask = alpha
+                if closing_size > 0:
+                    kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (closing_size, closing_size))
+                    refined_mask = cv2.morphologyEx(refined_mask, cv2.MORPH_CLOSE, kernel)
+                    
+                actual_rect = (0, 0, w, h)
+            else:
+                if rect is None:
+                    actual_rect = detect_automatic_bounding_box(cv_img, margin_percentage)
+                else:
+                    if max_preview_dim is not None:
+                        orig_h, orig_w = cv_raw.shape[:2]
+                        scale_x = w / orig_w
+                        scale_y = h / orig_h
+                        rx, ry, rw, rh = rect
+                        actual_rect = (
+                            int(rx * scale_x),
+                            int(ry * scale_y),
+                            int(rw * scale_x),
+                            int(rh * scale_y)
+                        )
+                    else:
+                        actual_rect = rect
+                        
+                raw_mask = run_grabcut(cv_img, actual_rect, iter_count, bg_seed_sensitivity=bg_seed_sensitivity)
+                
+                refined_mask = refine_mask(
+                    mask=raw_mask, 
+                    img=cv_img,
+                    closing_size=closing_size, 
+                    keep_largest_only=keep_largest_only, 
+                    feather_radius=feather_radius,
+                    matting_enabled=matting_enabled,
+                    matting_radius=matting_radius,
+                    matting_eps=matting_eps
+                )
+        
+        # 6. Generate Transparent PNG Cutout
+        cutout = np.zeros((h, w, 4), dtype=np.uint8)
+        cutout[:, :, :3] = cv_img[:, :, :3]
+        cutout[:, :, 3] = refined_mask
+        
+        # 7. Generate Drop Shadow Composite
+        if shadow_enabled:
+            shadow_composite = generate_drop_shadow(
+                cv_img,
+                refined_mask,
+                opacity=shadow_opacity,
+                blur_radius=shadow_blur,
+                distance=shadow_distance,
+                angle_degrees=shadow_angle
+            )
+        else:
+            shadow_composite = cutout
+            
+        # 8. Scale Bounding Box back to original coords if resized (for UI display overlay)
+        if max_preview_dim is not None:
+            orig_h, orig_w = cv_raw.shape[:2]
+            scale_x = orig_w / w
+            scale_y = orig_h / h
+            ax, ay, aw, ah = actual_rect
+            rect_out = (
+                int(ax * scale_x),
+                int(ay * scale_y),
+                int(aw * scale_x),
+                int(ah * scale_y)
+            )
+        else:
+            rect_out = actual_rect
+            
+        # 9. Convert outputs back to PIL
+        return {
+            "original": cv_to_pil(cv_img),
+            "mask": Image.fromarray(refined_mask).convert("L"),
+            "transparent": cv_to_pil(cutout),
+            "shadow": cv_to_pil(shadow_composite),
+            "rect": rect_out
+        }

backend/bg_remover/segmentation.py

@@ -0,0 +1,137 @@
+import cv2
+import numpy as np
+
+def detect_automatic_bounding_box(img: np.ndarray, margin_percentage: float = 5.0) -> tuple:
+    """
+    Detect the main subject's bounding box using edge density and contour analysis.
+    Filters out full-frame border contours.
+    """
+    h, w = img.shape[:2]
+    
+    # 1. Preprocess: Convert to grayscale and blur
+    gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
+    blurred = cv2.GaussianBlur(gray, (5, 5), 0)
+    
+    # 2. Compute edge density using Canny
+    edges = cv2.Canny(blurred, 30, 100)
+    
+    # 3. Morphological closing to join close edge segments
+    kernel = cv2.getStructuringElement(cv2.MORPH_RECT, (15, 15))
+    closed = cv2.morphologyEx(edges, cv2.MORPH_CLOSE, kernel)
+    dilated = cv2.dilate(closed, kernel, iterations=2)
+    
+    # 4. Find contours of the edge-dense regions
+    contours, _ = cv2.findContours(dilated, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+    
+    # If contours exist, find the bounding box of the largest ones
+    if contours:
+        # Filter contours by area and ignore frame border contours that cover the entire image
+        valid_contours = []
+        for c in contours:
+            cx, cy, ccw, cch = cv2.boundingRect(c)
+            if ccw >= w - 10 and cch >= h - 10:
+                continue
+            if cv2.contourArea(c) > (w * h * 0.002):
+                valid_contours.append(c)
+                
+        # Sort valid contours by area descending
+        valid_contours = sorted(valid_contours, key=cv2.contourArea, reverse=True)
+        
+        if valid_contours:
+            # Get the unified bounding box of the significant contours
+            x_min, y_min = w, h
+            x_max, y_max = 0, 0
+            for c in valid_contours[:3]:  # Top 3 largest contours
+                x, y, cw, ch = cv2.boundingRect(c)
+                x_min = min(x_min, x)
+                y_min = min(y_min, y)
+                x_max = max(x_max, x + cw)
+                y_max = max(y_max, y + ch)
+            
+            # Add a slight padding/margin
+            pad_x = int((x_max - x_min) * 0.05)
+            pad_y = int((y_max - y_min) * 0.05)
+            
+            x = max(0, x_min - pad_x)
+            y = max(0, y_min - pad_y)
+            cw = min(w - x, (x_max - x_min) + 2 * pad_x)
+            ch = min(h - y, (y_max - y_min) + 2 * pad_y)
+            
+            # Ensure it is valid
+            if cw > 10 and ch > 10:
+                return (x, y, cw, ch)
+                
+    # Fallback: Center-based bounding box with specified margin
+    margin_w = int(w * (margin_percentage / 100.0))
+    margin_h = int(h * (margin_percentage / 100.0))
+    
+    x = margin_w
+    y = margin_h
+    cw = w - (2 * margin_w)
+    ch = h - (2 * margin_h)
+    
+    return (x, y, cw, ch)
+
+def run_grabcut(img: np.ndarray, rect: tuple, iter_count: int = 5, bg_seed_sensitivity: float = 35.0) -> np.ndarray:
+    """
+    Run GrabCut algorithm on BGR image using the provided bounding box.
+    Optionally initializes the GrabCut mask with background seeds from the top corners.
+    """
+    h, w = img.shape[:2]
+    
+    # Ensure rect is valid and within image boundaries
+    rx, ry, rw, rh = rect
+    rx = max(0, min(rx, w - 2))
+    ry = max(0, min(ry, h - 2))
+    rw = max(1, min(rw, w - rx))
+    rh = max(1, min(rh, h - ry))
+    safe_rect = (rx, ry, rw, rh)
+    
+    # Initialize GrabCut background/foreground models
+    bgd_model = np.zeros((1, 65), dtype=np.float64)
+    fgd_model = np.zeros((1, 65), dtype=np.float64)
+    
+    # Create GrabCut mask
+    mask = np.zeros((h, w), dtype=np.uint8)
+    
+    try:
+        if bg_seed_sensitivity > 0.0 and len(img.shape) == 3:
+            # 1. Initialize entire mask inside the bounding box as Probable Foreground (3)
+            # and outside as Sure Background (0)
+            cv2.rectangle(mask, (rx, ry), (rx + rw, ry + rh), cv2.GC_PR_FGD, -1)
+            
+            # 2. Sample only top corner regions (Top-Left and Top-Right) to detect background color
+            pw = max(2, min(20, w // 20))
+            ph = max(2, min(20, h // 20))
+            
+            # Extract corner colors (BGR channels average)
+            c_tl = np.mean(img[0:ph, 0:pw, :3], axis=(0, 1))
+            c_tr = np.mean(img[0:ph, w-pw:w, :3], axis=(0, 1))
+            
+            # 3. For each pixel, compute distance to nearest corner color
+            diff_tl = np.sqrt(np.sum((img[:, :, :3] - c_tl) ** 2, axis=2))
+            diff_tr = np.sqrt(np.sum((img[:, :, :3] - c_tr) ** 2, axis=2))
+            
+            min_diff = np.minimum(diff_tl, diff_tr)
+            
+            # 4. Mark pixels inside safe_rect that are very close to corner colors as Probable Background (2)
+            bg_mask = (min_diff < bg_seed_sensitivity)
+            bbox_mask = np.zeros((h, w), dtype=bool)
+            bbox_mask[ry:ry+rh, rx:rx+rw] = True
+            
+            # Final probable background assignments
+            mask[bbox_mask & bg_mask] = cv2.GC_PR_BGD
+            
+            # Run GrabCut in MASK mode
+            cv2.grabCut(img, mask, safe_rect, bgd_model, fgd_model, iter_count, cv2.GC_INIT_WITH_MASK)
+        else:
+            # Traditional RECT-only initialization
+            cv2.grabCut(img, mask, safe_rect, bgd_model, fgd_model, iter_count, cv2.GC_INIT_WITH_RECT)
+        
+        # Convert output mask to binary
+        binary_mask = np.where((mask == cv2.GC_FGD) | (mask == cv2.GC_PR_FGD), 255, 0).astype(np.uint8)
+        return binary_mask
+    except Exception as e:
+        fallback_mask = np.zeros((h, w), dtype=np.uint8)
+        cv2.rectangle(fallback_mask, (rx, ry), (rx + rw, ry + rh), 255, -1)
+        return fallback_mask

backend/bg_remover/shadow_generator.py

@@ -0,0 +1,68 @@
+import cv2
+import numpy as np
+import math
+
+def blend_rgba(top: np.ndarray, bottom: np.ndarray) -> np.ndarray:
+    """
+    Perform alpha blending of an RGBA image 'top' over an RGBA image 'bottom'.
+    """
+    top_a = top[:, :, 3:4].astype(float) / 255.0
+    bottom_a = bottom[:, :, 3:4].astype(float) / 255.0
+    
+    out_a = top_a + bottom_a * (1.0 - top_a)
+    out_a_safe = np.where(out_a == 0, 1.0, out_a)
+    
+    top_rgb = top[:, :, :3].astype(float)
+    bottom_rgb = bottom[:, :, :3].astype(float)
+    
+    out_rgb = (top_rgb * top_a + bottom_rgb * bottom_a * (1.0 - top_a)) / out_a_safe
+    
+    out_img = np.zeros_like(top)
+    out_img[:, :, :3] = np.clip(out_rgb, 0, 255).astype(np.uint8)
+    out_img[:, :, 3] = np.clip(out_a * 255, 0, 255).astype(np.uint8)[:, :, 0]
+    
+    return out_img
+
+def generate_drop_shadow(img: np.ndarray, 
+                         mask: np.ndarray, 
+                         opacity: float = 0.5, 
+                         blur_radius: int = 15, 
+                         distance: int = 20, 
+                         angle_degrees: float = 45.0) -> np.ndarray:
+    """
+    Generate a realistic drop shadow layer behind the foreground cutout.
+    """
+    h, w = mask.shape[:2]
+    
+    cutout = np.zeros((h, w, 4), dtype=np.uint8)
+    if img.shape[2] == 4:
+        cutout[:, :, :3] = img[:, :, :3]
+    else:
+        cutout[:, :, :3] = img
+    cutout[:, :, 3] = mask
+    
+    if opacity <= 0.0 or (distance <= 0 and blur_radius <= 0):
+        return cutout
+        
+    shadow = np.zeros((h, w, 4), dtype=np.uint8)
+    shadow[:, :, 3] = mask
+    
+    angle_radians = math.radians(angle_degrees)
+    dx = int(distance * math.cos(angle_radians))
+    dy = int(distance * math.sin(angle_radians))
+    
+    M = np.float32([[1, 0, dx], [0, 1, dy]])
+    translated_shadow = cv2.warpAffine(
+        shadow, M, (w, h), 
+        borderMode=cv2.BORDER_CONSTANT, 
+        borderValue=(0, 0, 0, 0)
+    )
+    
+    if blur_radius > 0:
+        ksize = 2 * blur_radius + 1
+        translated_shadow = cv2.GaussianBlur(translated_shadow, (ksize, ksize), 0)
+        
+    translated_shadow[:, :, 3] = (translated_shadow[:, :, 3] * opacity).astype(np.uint8)
+    
+    final_composite = blend_rgba(top=cutout, bottom=translated_shadow)
+    return final_composite

backend/dslr_blur/blur_processor.py

@@ -0,0 +1,172 @@
+import cv2
+import numpy as np
+from PIL import Image
+from backend.utilities import pil_to_cv, cv_to_pil
+
+class DSLRBlurProcessor:
+    """
+    Orchestrator class to execute the DSLR Background Blur image processing pipeline.
+    """
+    
+    @staticmethod
+    def apply_feathering(mask: np.ndarray, radius: int) -> np.ndarray:
+        """
+        Feathers the binary mask to create a soft, anti-aliased edge transition.
+        Returns a float32 mask scaled between 0.0 and 1.0.
+        """
+        if radius <= 0:
+            return mask.astype(np.float32) / 255.0
+            
+        # Ensure kernel size is odd
+        k_size = radius * 2 + 1
+        feathered = cv2.GaussianBlur(mask, (k_size, k_size), 0)
+        return feathered.astype(np.float32) / 255.0
+
+    @staticmethod
+    def inpaint_background(img: np.ndarray, mask: np.ndarray) -> np.ndarray:
+        """
+        Inpaints/erases the foreground subject out of the background.
+        Uses a highly optimized downscaled inpainting approach to prevent color bleeding
+        and edge-halos when the background gets blurred.
+        """
+        h, w = img.shape[:2]
+        
+        # 1. Dilate the mask by 15px to fully cover edge transition and anti-aliasing zones
+        kernel_size = 15
+        kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (kernel_size, kernel_size))
+        dilated_mask = cv2.dilate(mask, kernel, iterations=1)
+        
+        # 2. Downscale the image and mask to 25% size for lightning-fast inpainting
+        scale = 0.25
+        down_w = int(w * scale)
+        down_h = int(h * scale)
+        
+        img_small = cv2.resize(img, (down_w, down_h), interpolation=cv2.INTER_AREA)
+        mask_small = cv2.resize(dilated_mask, (down_w, down_h), interpolation=cv2.INTER_NEAREST)
+        
+        # 3. Perform Fast Telea inpainting on the downscaled image
+        inpainted_small = cv2.inpaint(img_small, mask_small, 5, cv2.INPAINT_TELEA)
+        
+        # 4. Upscale back to the original image dimensions
+        inpainted = cv2.resize(inpainted_small, (w, h), interpolation=cv2.INTER_CUBIC)
+        
+        # 5. Composite back the real background pixels (keeping inpainted pixels only under dilated mask)
+        bg_only = img.copy()
+        mask_indices = dilated_mask > 0
+        bg_only[mask_indices] = inpainted[mask_indices]
+        
+        return bg_only
+
+    @staticmethod
+    def apply_blur(img: np.ndarray, mode: str, strength: float, smoothness: float) -> np.ndarray:
+        """
+        Applies a natural, aesthetically pleasing blur to the background.
+        Supports:
+          - "Gaussian Blur (Soft & Smooth)"
+          - "Lens Blur / Circular Bokeh (Realistic DSLR)"
+        """
+        # Map strength (1 - 100) to actual kernel/radius dimensions
+        # For Gaussian: map to odd numbers from 3 to 101
+        g_strength = int(strength / 100.0 * 50.0) * 2 + 1
+        g_strength = max(3, g_strength)
+        
+        # For Circular Bokeh: map circular kernel diameter from 3 to 61
+        l_diameter = int(strength / 100.0 * 30.0) * 2 + 1
+        l_diameter = max(3, l_diameter)
+        
+        if mode == "Lens Blur / Circular Bokeh (Realistic DSLR)":
+            # Create a flat circular convolution kernel representing lens aperture
+            kernel = np.zeros((l_diameter, l_diameter), dtype=np.float32)
+            cv2.circle(kernel, (l_diameter // 2, l_diameter // 2), l_diameter // 2, 1, -1)
+            
+            # Normalize the kernel
+            kernel_sum = np.sum(kernel)
+            if kernel_sum > 0:
+                kernel /= kernel_sum
+            else:
+                kernel[l_diameter // 2, l_diameter // 2] = 1.0
+                
+            # Convolve background to form circular bokeh discs
+            blurred = cv2.filter2D(img, -1, kernel)
+        else:
+            # Gaussian Blur
+            blurred = cv2.GaussianBlur(img, (g_strength, g_strength), 0)
+            
+        # Bilateral filter post-smoothing for a creamy, noise-free studio look
+        if smoothness > 0:
+            d = int(smoothness / 100.0 * 15)
+            d = max(3, d | 1)  # must be odd
+            sigma_color = smoothness / 100.0 * 150.0
+            sigma_space = smoothness / 100.0 * 150.0
+            blurred = cv2.bilateralFilter(blurred, d, sigma_color, sigma_space)
+            
+        return blurred
+
+    @staticmethod
+    def composite_layers(
+        fg_img: np.ndarray, 
+        bg_img: np.ndarray, 
+        alpha: np.ndarray, 
+        subject_protection: float
+    ) -> np.ndarray:
+        """
+        Composites the sharp foreground subject over the blurred background.
+        alpha: float32 grayscale feathered mask in range [0, 1.0]. Shape is (H, W).
+        subject_protection: float (0 - 100) -> Protects original fine details.
+        """
+        # Expand alpha to 3 channels for RGB broadcasting
+        alpha_3d = np.expand_dims(alpha, axis=2)
+        
+        # Subject Protection clamps the minimum alpha of subject pixels to prevent them blurring
+        if subject_protection > 0:
+            protection_factor = subject_protection / 100.0
+            mask_fg = alpha > 0.05
+            alpha_3d[mask_fg] = np.maximum(alpha_3d[mask_fg], protection_factor)
+            
+        # Alpha blend: out = fg * alpha + bg * (1 - alpha)
+        composited = fg_img.astype(np.float32) * alpha_3d + bg_img.astype(np.float32) * (1.0 - alpha_3d)
+        return np.clip(composited, 0, 255).astype(np.uint8)
+
+    @classmethod
+    def process_dslr_blur(
+        cls,
+        pil_image: Image.Image,
+        mask_pil: Image.Image,
+        blur_mode: str = "Lens Blur / Circular Bokeh (Realistic DSLR)",
+        blur_strength: float = 30.0,
+        edge_feathering: int = 5,
+        subject_protection: float = 80.0,
+        background_smoothness: float = 30.0
+    ) -> Image.Image:
+        """
+        Main entry point to execute the DSLR Background Blur pipeline.
+        """
+        # 1. Convert to CV BGR/BGRA arrays
+        cv_img = pil_to_cv(pil_image)
+        mask = np.array(mask_pil.convert("L"))
+        
+        # Ensure matching shapes
+        h, w = cv_img.shape[:2]
+        if mask.shape[:2] != (h, w):
+            mask = cv2.resize(mask, (w, h), interpolation=cv2.INTER_NEAREST)
+            
+        # 2. Feather the mask to create anti-aliased subject edges
+        alpha = cls.apply_feathering(mask, edge_feathering)
+        
+        # 3. Inpaint the background to erase the subject and prevent colored edge halos/bleeding
+        bg_inpainted = cls.inpaint_background(cv_img[:, :, :3], mask)
+        
+        # 4. Apply Gaussian or circular lens bokeh blur to the background
+        bg_blurred = cls.apply_blur(bg_inpainted, blur_mode, blur_strength, background_smoothness)
+        
+        # 5. Composite original sharp subject over the blurred background using feathered alpha
+        result_cv = cls.composite_layers(cv_img[:, :, :3], bg_blurred, alpha, subject_protection)
+        
+        # 6. Re-apply alpha channel if original image was RGBA
+        if cv_img.shape[2] == 4:
+            result_rgba = np.zeros((h, w, 4), dtype=np.uint8)
+            result_rgba[:, :, :3] = result_cv
+            result_rgba[:, :, 3] = cv_img[:, :, 3]
+            return cv_to_pil(result_rgba)
+        else:
+            return cv_to_pil(result_cv)

backend/dslr_blur/depth_blur.py

@@ -0,0 +1,170 @@
+import cv2
+import numpy as np
+from PIL import Image
+from backend.utilities import pil_to_cv, cv_to_pil
+from backend.bg_remover.image_processor import ImageProcessor
+from backend.dslr_blur.blur_processor import DSLRBlurProcessor
+from backend.enhancement.onnx_engine import ONNXInferenceEngine
+
+class DepthBlurEngine:
+    """
+    Fuses Depth Anything V2 depth maps and BiRefNet masks to execute 
+    spatially-varying, optical DSLR depth-of-field blurs.
+    """
+    
+    @classmethod
+    def generate_synthetic_depth_map(cls, h: int, w: int, mask: np.ndarray) -> np.ndarray:
+        """
+        Fallback generator that constructs a smooth vertical linear perspective depth map
+        in case the neural ONNX model is offline or unavailable.
+        """
+        # Create vertical gradient: 0 at top (infinity), 255 at bottom (foreground ground plane)
+        y, x = np.indices((h, w))
+        depth = (y / h * 255.0).astype(np.uint8)
+        
+        # Clamp subject pixels to foreground (240) to keep the focus plane sharp
+        depth[mask > 127] = 230
+        return depth
+
+    @classmethod
+    def run_depth_estimation(cls, cv_img: np.ndarray, mask: np.ndarray) -> np.ndarray:
+        """
+        Attempts to run Depth Anything V2 neural depth estimation with a graceful 
+        vertical linear perspective fallback on network/load failures.
+        """
+        h, w = cv_img.shape[:2]
+        try:
+            # Try running ONNX Depth Anything session
+            depth_map = ONNXInferenceEngine.run_depth_anything(cv_img[:, :, :3])
+            return depth_map
+        except Exception as e:
+            print(f"[Depth Engine] Depth Anything V2 failed: {e}. Generating synthetic linear depth gradient.")
+            return cls.generate_synthetic_depth_map(h, w, mask)
+
+    @classmethod
+    def process_depth_blur(
+        cls,
+        pil_image: Image.Image,
+        mask_pil: Image.Image,
+        blur_mode: str = "Lens Blur / Circular Bokeh (Realistic DSLR)",
+        blur_preset: str = "DSLR 85mm",
+        blur_strength: float = 45.0,
+        edge_feathering: int = 5,
+        subject_protection: float = 85.0,
+        background_smoothness: float = 30.0
+    ) -> dict:
+        """
+        Executes the complete spatially-varying optical depth blur pipeline.
+        Returns a dictionary containing:
+          - "result": PIL composite image with depth blur
+          - "depth_map": PIL depth map image (for visual developer previews)
+        """
+        # 1. Convert formats
+        cv_img = pil_to_cv(pil_image)
+        mask = np.array(mask_pil.convert("L"))
+        h, w = cv_img.shape[:2]
+        
+        # Ensure matching shapes
+        if mask.shape[:2] != (h, w):
+            mask = cv2.resize(mask, (w, h), interpolation=cv2.INTER_NEAREST)
+            
+        # 2. Pre-generate or run depth estimation
+        depth = cls.run_depth_estimation(cv_img, mask)
+        
+        # 3. Soft-feather the mask
+        alpha = DSLRBlurProcessor.apply_feathering(mask, edge_feathering)
+        
+        # 4. Calibrate Focus Plane Depth (D_subject) to the isolated subject
+        subject_pixels = depth[mask > 127]
+        if len(subject_pixels) > 0:
+            D_subject = float(np.median(subject_pixels))
+        else:
+            D_subject = 220.0 # Default foreground depth focus
+            
+        # 5. Map Preset parameters to Max Blur Strength
+        # Presets: Portrait, DSLR 50mm, DSLR 85mm, Studio, Cinematic, Custom
+        preset_max_blur = {
+            "Portrait": 25.0,
+            "DSLR 50mm": 40.0,
+            "DSLR 85mm": 55.0,
+            "Studio": 20.0,
+            "Cinematic": 75.0,
+            "Custom": blur_strength
+        }
+        max_blur = preset_max_blur.get(blur_preset, blur_strength)
+        
+        # 6. Calculate Spatially-Varying Blur Radius map
+        # Dist from focus plane scaled [0.0, 1.0]
+        dist_from_focus = np.abs(depth.astype(np.float32) - D_subject) / 255.0
+        
+        # Blur radius maps from 0 to max_blur (subject has 0 blur because of (1 - alpha))
+        radius_map = max_blur * (1.0 - alpha) * dist_from_focus
+        
+        # 7. Reconstruct Background to prevent colored halos/subject bleeding
+        bg_inpainted = DSLRBlurProcessor.inpaint_background(cv_img[:, :, :3], mask)
+        
+        # 8. Vectorized N-Layer Depth-of-Field Blending
+        # Generate N=6 discrete blur radius stops for linear interpolation
+        radii = [0, int(0.15 * max_blur), int(0.35 * max_blur), int(0.60 * max_blur), int(0.85 * max_blur), int(max_blur)]
+        # Filter duplicates and ensure they are sorted ascending
+        radii = sorted(list(set(radii)))
+        
+        # Pre-compute N blurred background layers
+        blurred_layers = []
+        for r in radii:
+            if r == 0:
+                blurred_layers.append(bg_inpainted)
+            else:
+                # Ensure the radius maps to an odd number internally in apply_blur
+                blurred_layers.append(DSLRBlurProcessor.apply_blur(bg_inpainted, blur_mode, r, background_smoothness))
+                
+        # Perform vectorized linear interpolation across depth intervals
+        composite_bg = np.zeros_like(cv_img[:, :, :3], dtype=np.float32)
+        
+        for k in range(len(radii) - 1):
+            r_low = radii[k]
+            r_high = radii[k+1]
+            
+            # Identify pixels whose target blur radius falls inside this interval
+            if k == len(radii) - 2:
+                interval_mask = (radius_map >= r_low) & (radius_map <= r_high)
+            else:
+                interval_mask = (radius_map >= r_low) & (radius_map < r_high)
+                
+            if not np.any(interval_mask):
+                continue
+                
+            # Grab target radii values in this interval
+            r_vals = radius_map[interval_mask]
+            
+            # Linear interpolation weight: w = 1.0 at low_radius, 0.0 at high_radius
+            w_interp = (r_high - r_vals) / (r_high - r_low)
+            w_interp_3d = np.expand_dims(w_interp, axis=1) # shape (num_pixels, 1)
+            
+            # Slice pixels from adjacent blurred layers
+            low_pixels = blurred_layers[k][interval_mask].astype(np.float32)
+            high_pixels = blurred_layers[k+1][interval_mask].astype(np.float32)
+            
+            # Blend pixels and write back
+            blended_pixels = low_pixels * w_interp_3d + high_pixels * (1.0 - w_interp_3d)
+            composite_bg[interval_mask] = blended_pixels
+            
+        # Clip to valid range and cast
+        bg_depth_blurred = np.clip(composite_bg, 0, 255).astype(np.uint8)
+        
+        # 9. Composite the original sharp subject over this depth-blurred background
+        result_cv = DSLRBlurProcessor.composite_layers(cv_img[:, :, :3], bg_depth_blurred, alpha, subject_protection)
+        
+        # 10. Re-apply alpha transparency if present
+        if cv_img.shape[2] == 4:
+            result_rgba = np.zeros((h, w, 4), dtype=np.uint8)
+            result_rgba[:, :, :3] = result_cv
+            result_rgba[:, :, 3] = cv_img[:, :, 3]
+            output_pil = cv_to_pil(result_rgba)
+        else:
+            output_pil = cv_to_pil(result_cv)
+            
+        return {
+            "result": output_pil,
+            "depth_map": Image.fromarray(depth).convert("L")
+        }

backend/enhancement/onnx_engine.py

@@ -0,0 +1,205 @@
+import os
+import cv2
+import numpy as np
+import urllib.request
+from PIL import Image
+
+class ONNXInferenceEngine:
+    """
+    Handles downloading, caching, and inference of ONNX models for:
+    - Depth Anything V2 (Depth Estimation)
+    - GFPGAN v1.4 (Face Restoration)
+    - Real-ESRGAN x2 (Super Resolution & Artifact Removal)
+    """
+    
+    MODELS_DIR = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "models")
+    
+    MODEL_URLS = {
+        "depth_anything": "https://huggingface.co/onnx-community/depth-anything-v2-small/resolve/main/onnx/model.onnx", # 97 MB
+        "gfpgan": "https://huggingface.co/Gourieff/ReActor/resolve/main/models/facerestore_models/GFPGANv1.4.onnx",     # 140 MB
+        "realesrgan": "https://huggingface.co/sberbank-ai/Real-ESRGAN/resolve/main/RealESRGAN_x2.onnx"                  # 67 MB
+    }
+    
+    @classmethod
+    def get_model_path(cls, model_key: str) -> str:
+        """Gets local path to the model, downloading it if not present."""
+        os.makedirs(cls.MODELS_DIR, exist_ok=True)
+        filename = f"{model_key}.onnx"
+        dest_path = os.path.join(cls.MODELS_DIR, filename)
+        
+        if os.path.exists(dest_path) and os.path.getsize(dest_path) > 10 * 1024 * 1024:
+            return dest_path
+            
+        url = cls.MODEL_URLS[model_key]
+        temp_path = dest_path + ".tmp"
+        
+        print(f"[ONNX Engine] Downloading {model_key} model weights (~{cls._get_size_str(model_key)})...")
+        try:
+            req = urllib.request.Request(url, headers={'User-Agent': 'Mozilla/5.0'})
+            with urllib.request.urlopen(req) as response, open(temp_path, "wb") as out_file:
+                block_size = 1024 * 1024 # 1 MB chunks
+                while True:
+                    buffer = response.read(block_size)
+                    if not buffer:
+                        break
+                    out_file.write(buffer)
+            os.replace(temp_path, dest_path)
+            print(f"[ONNX Engine] Successfully downloaded and cached {model_key} model.")
+            return dest_path
+        except Exception as e:
+            if os.path.exists(temp_path):
+                os.remove(temp_path)
+            print(f"[ONNX Engine] Failed to download {model_key}: {e}")
+            raise e
+
+    @staticmethod
+    def _get_size_str(model_key: str) -> str:
+        sizes = {"depth_anything": "97MB", "gfpgan": "140MB", "realesrgan": "67MB"}
+        return sizes.get(model_key, "Unknown")
+
+    @classmethod
+    def get_session(cls, model_key: str):
+        """Initializes and returns an ONNX Runtime inference session."""
+        try:
+            import onnxruntime as ort
+            model_path = cls.get_model_path(model_key)
+            # Use CPU execution provider with optimized thread configurations
+            sess_options = ort.SessionOptions()
+            sess_options.intra_op_num_threads = 2
+            sess_options.execution_mode = ort.ExecutionMode.ORT_SEQUENTIAL
+            session = ort.InferenceSession(model_path, sess_options, providers=["CPUExecutionProvider"])
+            return session
+        except Exception as e:
+            print(f"[ONNX Engine] Error loading {model_key} session: {e}")
+            return None
+
+    @classmethod
+    def run_depth_anything(cls, cv_img: np.ndarray) -> np.ndarray:
+        """
+        Executes Depth Anything V2 Small ONNX model to extract a relative depth map.
+        Input: cv_img (BGR numpy array). Output: Grayscale depth map normalized to [0, 255].
+        """
+        session = cls.get_session("depth_anything")
+        if session is None:
+            raise RuntimeError("Depth Anything V2 ONNX session is not available.")
+            
+        h, w = cv_img.shape[:2]
+        
+        # 1. Preprocess: Resize to 518x518 (multiple of 14, model input standard)
+        input_size = 518
+        img_rgb = cv2.cvtColor(cv_img, cv2.COLOR_BGR2RGB)
+        img_resized = cv2.resize(img_rgb, (input_size, input_size), interpolation=cv2.INTER_AREA)
+        
+        # Normalize with ImageNet stats
+        img_float = img_resized.astype(np.float32) / 255.0
+        mean = np.array([0.485, 0.456, 0.406], dtype=np.float32)
+        std = np.array([0.229, 0.224, 0.225], dtype=np.float32)
+        img_norm = (img_float - mean) / std
+        
+        # Transpose to CHW (3, 518, 518) and add batch dim
+        img_tensor = np.transpose(img_norm, (2, 0, 1))
+        img_tensor = np.expand_dims(img_tensor, axis=0)
+        
+        # 2. Run Inference
+        inputs = {session.get_inputs()[0].name: img_tensor}
+        depth_out = session.run(None, inputs)[0]
+        
+        # Depth output shape is (1, 1, 518, 518) or (1, 518, 518)
+        depth_map = np.squeeze(depth_out)
+        
+        # 3. Postprocess: Min-Max normalize to [0, 255]
+        d_min, d_max = depth_map.min(), depth_map.max()
+        if d_max > d_min:
+            depth_map = (depth_map - d_min) / (d_max - d_min) * 255.0
+        else:
+            depth_map = np.zeros_like(depth_map)
+            
+        depth_map = depth_map.astype(np.uint8)
+        
+        # Resize back to original dimensions using bilinear interpolation
+        depth_original = cv2.resize(depth_map, (w, h), interpolation=cv2.INTER_LINEAR)
+        return depth_original
+
+    @classmethod
+    def run_gfpgan(cls, face_bgr: np.ndarray) -> np.ndarray:
+        """
+        Executes GFPGAN v1.4 ONNX model on a cropped facial BGR image.
+        Input: face_bgr (BGR array, expected 512x512). Output: Restored BGR face.
+        """
+        session = cls.get_session("gfpgan")
+        if session is None:
+            raise RuntimeError("GFPGAN ONNX session is not available.")
+            
+        # 1. Preprocess: Resize to 512x512
+        face_resized = cv2.resize(face_bgr, (512, 512), interpolation=cv2.INTER_AREA)
+        face_rgb = cv2.cvtColor(face_resized, cv2.COLOR_BGR2RGB)
+        
+        # Normalize to [-1.0, 1.0]
+        face_float = face_rgb.astype(np.float32)
+        face_norm = (face_float - 127.5) / 127.5
+        
+        # Transpose to CHW and expand batch
+        face_tensor = np.transpose(face_norm, (2, 0, 1))
+        face_tensor = np.expand_dims(face_tensor, axis=0)
+        
+        # 2. Run Inference
+        inputs = {session.get_inputs()[0].name: face_tensor}
+        restored_out = session.run(None, inputs)[0]
+        
+        # 3. Postprocess: Scale back to [0, 255]
+        restored_face = np.squeeze(restored_out)
+        restored_face = np.transpose(restored_face, (1, 2, 0)) # CHW -> HWC
+        restored_face = np.clip((restored_face + 1.0) * 127.5, 0, 255).astype(np.uint8)
+        
+        # Convert RGB back to BGR
+        restored_bgr = cv2.cvtColor(restored_face, cv2.COLOR_RGB2BGR)
+        return restored_bgr
+
+    @classmethod
+    def run_realesrgan(cls, cv_img: np.ndarray) -> np.ndarray:
+        """
+        Executes Real-ESRGAN x2 ONNX model to upscale and remove compression artifacts.
+        Input: cv_img (BGR). Output: 2x Super-Resolved BGR image.
+        """
+        session = cls.get_session("realesrgan")
+        if session is None:
+            raise RuntimeError("Real-ESRGAN ONNX session is not available.")
+            
+        h, w = cv_img.shape[:2]
+        
+        # For CPU safety, if the input image is already large, we scale it down before upscaling
+        # to prevent memory overflows and extremely slow processing.
+        max_input_dim = 700
+        if max(h, w) > max_input_dim:
+            if h > w:
+                new_h = max_input_dim
+                new_w = int(w * (max_input_dim / h))
+            else:
+                new_w = max_input_dim
+                new_h = int(h * (max_input_dim / w))
+            processing_img = cv2.resize(cv_img, (new_w, new_h), interpolation=cv2.INTER_AREA)
+        else:
+            processing_img = cv_img.copy()
+            
+        ph, pw = processing_img.shape[:2]
+        
+        # 1. Preprocess: Convert to RGB and normalize to [0.0, 1.0]
+        img_rgb = cv2.cvtColor(processing_img, cv2.COLOR_BGR2RGB)
+        img_float = img_rgb.astype(np.float32) / 255.0
+        
+        # Transpose to CHW and add batch dimension
+        img_tensor = np.transpose(img_float, (2, 0, 1))
+        img_tensor = np.expand_dims(img_tensor, axis=0)
+        
+        # 2. Run Inference
+        inputs = {session.get_inputs()[0].name: img_tensor}
+        upscaled_out = session.run(None, inputs)[0]
+        
+        # 3. Postprocess
+        upscaled_img = np.squeeze(upscaled_out)
+        upscaled_img = np.transpose(upscaled_img, (1, 2, 0)) # CHW -> HWC
+        upscaled_img = np.clip(upscaled_img * 255.0, 0, 255).astype(np.uint8)
+        
+        # Convert RGB to BGR
+        upscaled_bgr = cv2.cvtColor(upscaled_img, cv2.COLOR_RGB2BGR)
+        return upscaled_bgr

backend/enhancement/photo_enhancer.py

@@ -0,0 +1,150 @@
+import cv2
+import numpy as np
+from PIL import Image
+from backend.utilities import pil_to_cv, cv_to_pil
+from backend.enhancement.onnx_engine import ONNXInferenceEngine
+
+class PhotoEnhancer:
+    """
+    Orchestrates AI Photo Enhancement, Face Restoration, and Color Grading.
+    """
+    
+    @staticmethod
+    def apply_color_grading(img: np.ndarray, vibrancy_boost: float = 1.15, contrast_boost: float = 1.02) -> np.ndarray:
+        """
+        Preserves 100% of the original photo's natural color palette, balance, and contrast.
+        Returns the input image completely untouched.
+        """
+        return img
+
+    @classmethod
+    def restore_faces(cls, img: np.ndarray) -> np.ndarray:
+        """
+        Detects faces in the image, runs GFPGAN ONNX inference on crops, 
+        and blends them back seamlessly using feathered alpha blending.
+        """
+        # Load OpenCV Haar Cascade face detector
+        face_cascade = cv2.CascadeClassifier(cv2.data.haarcascades + 'haarcascade_frontalface_default.xml')
+        gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
+        
+        # Detect faces
+        faces = face_cascade.detectMultiScale(gray, scaleFactor=1.1, minNeighbors=5, minSize=(40, 40))
+        if len(faces) == 0:
+            return img
+            
+        result = img.copy()
+        h, w = img.shape[:2]
+        
+        print(f"[Photo Enhancer] Detected {len(faces)} face(s) for GFPGAN restoration.")
+        for idx, (fx, fy, fw, fh) in enumerate(faces):
+            try:
+                # Add 40% padding around the detected face region for natural context
+                pad_x = int(fw * 0.4)
+                pad_y = int(fh * 0.4)
+                
+                x1 = max(0, fx - pad_x)
+                y1 = max(0, fy - pad_y)
+                x2 = min(w, fx + fw + pad_x)
+                y2 = min(h, fy + fh + pad_y)
+                
+                crop_w = x2 - x1
+                crop_h = y2 - y1
+                
+                if crop_w < 20 or crop_h < 20:
+                    continue
+                    
+                face_crop = img[y1:y2, x1:x2]
+                
+                # Execute GFPGAN ONNX restoration
+                restored_face_512 = ONNXInferenceEngine.run_gfpgan(face_crop)
+                
+                # Resize the restored face back to the crop's original dimensions
+                restored_face = cv2.resize(restored_face_512, (crop_w, crop_h), interpolation=cv2.INTER_CUBIC)
+                
+                # Create a feathered ellipse blending mask to overlay the face crop seamlessly
+                mask = np.zeros((crop_h, crop_w), dtype=np.float32)
+                cx = crop_w // 2
+                cy = crop_h // 2
+                rx = int(crop_w * 0.45)
+                ry = int(crop_h * 0.45)
+                cv2.ellipse(mask, (cx, cy), (rx, ry), 0, 0, 360, 1.0, -1)
+                
+                # Blur the mask to create a smooth, linear alpha transition
+                mask_blurred = cv2.GaussianBlur(mask, (31, 31), 0)
+                mask_3d = np.expand_dims(mask_blurred, axis=2)
+                
+                # Blend the restored face back onto the image
+                original_crop = result[y1:y2, x1:x2].astype(np.float32)
+                restored_crop = restored_face.astype(np.float32)
+                
+                blended_crop = restored_crop * mask_3d + original_crop * (1.0 - mask_3d)
+                result[y1:y2, x1:x2] = np.clip(blended_crop, 0, 255).astype(np.uint8)
+            except Exception as e:
+                print(f"[Photo Enhancer] Face {idx+1} restoration failed: {e}. Falling back to original face.")
+                
+        return result
+
+    @classmethod
+    def apply_opencv_enhancement(cls, img: np.ndarray) -> np.ndarray:
+        """
+        High-performance zero-dependency detail enhancer (Bilateral denoising + Unsharp Masking).
+        Preserves 100% original color, contrast, and histogram distributions.
+        """
+        # 1. Bilateral filtering (reduces noise, preserves sharp object edges)
+        denoised = cv2.bilateralFilter(img, 9, 35, 35)
+        
+        # 2. High-Pass Unsharp Masking (recovers micro-details and textures)
+        blurred = cv2.GaussianBlur(denoised, (0, 0), 3)
+        sharpened = cv2.addWeighted(denoised, 1.4, blurred, -0.4, 0)
+        
+        return sharpened
+
+    @classmethod
+    def process_enhancement(
+        cls,
+        pil_image: Image.Image,
+        mode: str = "Professional DSLR",
+        face_restoration: bool = True
+    ) -> Image.Image:
+        """
+        Main entry point to execute the photo enhancement pipeline.
+        Modes:
+          - "Standard": Fast, zero-dependency detail sharpener + color grading.
+          - "High Quality (Neural)": Real-ESRGAN super-resolution + color grading.
+          - "Professional DSLR": Full pipeline (Real-ESRGAN + GFPGAN Face Restore + Color Grading).
+        """
+        cv_img = pil_to_cv(pil_image)
+        
+        # 1. Photo Upscaling & Detail Sharpness
+        if mode in ["High Quality (Neural)", "Professional DSLR"]:
+            try:
+                # Try running Real-ESRGAN ONNX
+                enhanced_cv = ONNXInferenceEngine.run_realesrgan(cv_img[:, :, :3])
+            except Exception as e:
+                print(f"[Photo Enhancer] Real-ESRGAN upscale failed: {e}. Falling back to OpenCV sharpener.")
+                # Fallback to high-speed OpenCV sharpener
+                enhanced_cv = cls.apply_opencv_enhancement(cv_img[:, :, :3])
+        else:
+            # Standard Mode (OpenCV sharpener)
+            enhanced_cv = cls.apply_opencv_enhancement(cv_img[:, :, :3])
+            
+        # 2. Face Restoration (GFPGAN)
+        if face_restoration and mode == "Professional DSLR":
+            try:
+                enhanced_cv = cls.restore_faces(enhanced_cv)
+            except Exception as e:
+                print(f"[Photo Enhancer] GFPGAN face restoration failed: {e}.")
+                
+        # 3. Color Grading & Aesthetics
+        final_cv = cls.apply_color_grading(enhanced_cv)
+        
+        # Apply original transparency alpha channel if present
+        if cv_img.shape[2] == 4:
+            h, w = final_cv.shape[:2]
+            alpha = cv2.resize(cv_img[:, :, 3], (w, h), interpolation=cv2.INTER_LINEAR)
+            result_rgba = np.zeros((h, w, 4), dtype=np.uint8)
+            result_rgba[:, :, :3] = final_cv
+            result_rgba[:, :, 3] = alpha
+            return cv_to_pil(result_rgba)
+        else:
+            return cv_to_pil(final_cv)

backend/models/depth_anything.onnx

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:afb6a5c28f3b6bf1618c6e43f02073ef9dfdc70e937502d51603e57b0a1df10c
+size 99060839

backend/text_editor/__init__.py

@@ -0,0 +1,2 @@
+from backend.text_editor.orchestrator import TextEditorOrchestrator
+from backend.text_editor.pdf_processor import get_pdf_page_count, pdf_page_to_pil, compile_images_to_pdf