Update app.py

app.py

@@ -10,6 +10,7 @@ from PIL import Image, ImageOps, ImageDraw
 from roboflow import Roboflow
 from gradio_client import Client
 import gradio as gr
+import requests  # <-- for downloading PNG from URL
 
 # -------------------------------------------------------------------------
 # 🧠 Fix for Gradio schema bug ("TypeError: argument of type 'bool' is not iterable")
@@ -35,15 +36,12 @@ def _safe_json_schema_to_python_type(schema, defs=None):
     try:
         if isinstance(schema, dict) and "anyOf" in schema:
             types = [s.get("type") for s in schema["anyOf"] if isinstance(s, dict)]
-            # Handle the common case that causes the crash
             if set(types) == {"string", "null"}:
                 return "Optional[str]"
-        # Default back to the original function
         return gu._json_schema_to_python_type_original(schema, defs)
     except Exception:
         return "UnknownType"
 
-# Backup and patch the function safely
 if not hasattr(gu, "_json_schema_to_python_type_original"):
     gu._json_schema_to_python_type_original = gu._json_schema_to_python_type
     gu._json_schema_to_python_type = _safe_json_schema_to_python_type
@@ -76,11 +74,10 @@ logging.basicConfig(
 # -------------------------------------------------------------------------
 # 🤖 Roboflow configuration
 # -------------------------------------------------------------------------
-ROBOFLOW_API_KEY = "u5LX112EBlNmzYoofvPL"  # ✅ your key
+ROBOFLOW_API_KEY = "u5LX112EBlNmzYoofvPL"
 PROJECT_NAME = "model_verification_project"
 VERSION_NUMBER = 2
 
-# Force environment variable to override cached API key
 os.environ["ROBOFLOW_API_KEY"] = ROBOFLOW_API_KEY
 
 # -------------------------------------------------------------------------
@@ -88,15 +85,13 @@ os.environ["ROBOFLOW_API_KEY"] = ROBOFLOW_API_KEY
 # -------------------------------------------------------------------------
 HANDWRITING_MODEL_ENDPOINT = "3morrrrr/Handwriting_Model_Inf"
 
-# Cached client instance (lazy init)
+# Cached handwriting client
 _handwriting_client = None
 
 def get_handwriting_client(max_retries=5, retry_delay=3):
     """
-    Lazily initialize and cache the handwriting Client.
-
-    Retries a few times in case the Hugging Face Space is cold-starting,
-    to avoid crashing the whole app on startup.
+    Lazily initialize and cache the handwriting Client with retries.
+    Avoids crashing the app if the Space is waking up / slow.
     """
     global _handwriting_client
     if _handwriting_client is not None:
@@ -133,7 +128,10 @@ DEBUG_DIR = os.path.join(tempfile.gettempdir(), "debug_images")
 os.makedirs(DEBUG_DIR, exist_ok=True)
 
 logging.info(f"Debug images stored in: {DEBUG_DIR}")
-logging.info(f"Using Roboflow project '{PROJECT_NAME}' (v{VERSION_NUMBER}) with API key ending in {ROBOFLOW_API_KEY[-4:]}")
+logging.info(
+    f"Using Roboflow project '{PROJECT_NAME}' (v{VERSION_NUMBER}) "
+    f"with API key ending in {ROBOFLOW_API_KEY[-4:]}"
+)
 logging.info(f"Using handwriting model endpoint: {HANDWRITING_MODEL_ENDPOINT}")
 
 # -------------------------------------------------------------------------
@@ -171,6 +169,53 @@ def save_debug_image(image, filename, text=None):
     logging.debug(f"Saved debug image: {path}")
     return path
 
+def ensure_local_png(png_output):
+    """
+    Handle Gradio / HF output for the PNG:
+    - If it's a path string, return it.
+    - If it's a dict, use .path or .url.
+    - If it's a URL, download it to a temp file.
+    """
+    if png_output is None:
+        raise ValueError("Handwriting model returned no PNG output (None).")
+
+    png_path = None
+
+    # Case 1: plain string path
+    if isinstance(png_output, str):
+        png_path = png_output
+
+    # Case 2: dict from Gradio output: {path, url, ...}
+    elif isinstance(png_output, dict):
+        png_path = png_output.get("path") or png_output.get("url")
+
+    else:
+        raise ValueError(f"Unexpected PNG output type: {type(png_output)}")
+
+    if not png_path:
+        raise ValueError(f"PNG output from handwriting model is missing a path/url: {png_output}")
+
+    # If already a local file path
+    if os.path.exists(png_path):
+        return png_path
+
+    # If it's a URL, download it
+    if isinstance(png_path, str) and png_path.startswith("http"):
+        logging.debug(f"Downloading PNG from URL: {png_path}")
+        temp_png = os.path.join(tempfile.gettempdir(), f"handwriting_{int(time.time())}.png")
+        try:
+            r = requests.get(png_path, stream=True, timeout=30)
+            r.raise_for_status()
+            with open(temp_png, "wb") as f:
+                shutil.copyfileobj(r.raw, f)
+            logging.debug(f"Downloaded PNG to {temp_png}")
+            return temp_png
+        except Exception as e:
+            raise RuntimeError(f"Failed to download PNG from URL: {e}")
+
+    # Any other weird case
+    raise ValueError(f"Invalid PNG path returned: {png_path}")
+
 # -------------------------------------------------------------------------
 # 🧠 Load Roboflow models
 # -------------------------------------------------------------------------
@@ -178,18 +223,12 @@ rf = Roboflow(api_key=ROBOFLOW_API_KEY)
 project = rf.workspace().project(PROJECT_NAME)
 model = project.version(VERSION_NUMBER).model
 
-# Improved function to detect paper angle
+# -------------------------------------------------------------------------
+# 📐 Detect paper angle
+# -------------------------------------------------------------------------
 def detect_paper_angle(image, bounding_box):
     """
-    Detect the angle of a paper document within the given bounding box,
-    optimized for white paper detection.
-    
-    Parameters:
-    - image: PIL Image or numpy array of the full image
-    - bounding_box: Tuple of (x1, y1, x2, y2) coordinates
-    
-    Returns:
-    - angle: The detected angle in degrees
+    Detect the angle of a paper document within the given bounding box.
     """
     x1, y1, x2, y2 = bounding_box
     
@@ -202,7 +241,6 @@ def detect_paper_angle(image, bounding_box):
     # Crop the region of interest (ROI)
     roi = image_np[y1:y2, x1:x2]
     
-    # Create a debug image
     if DEBUG:
         debug_roi = Image.fromarray(roi)
         save_debug_image(debug_roi, f"paper_roi_{int(time.time())}.png", 
@@ -214,61 +252,46 @@ def detect_paper_angle(image, bounding_box):
     else:
         gray = roi
     
-    # Save the grayscale image for debugging
     if DEBUG:
         cv2.imwrite(os.path.join(DEBUG_DIR, f"gray_paper_{int(time.time())}.png"), gray)
     
-    # Method 1: Try adaptive thresholding first (good for white paper)
+    # Method 1: adaptive thresholding
     try:
-        # Apply adaptive thresholding to handle varying lighting conditions
-        # This is particularly effective for white paper
         binary = cv2.adaptiveThreshold(
             gray, 255, cv2.ADAPTIVE_THRESH_GAUSSIAN_C, 
             cv2.THRESH_BINARY_INV, 11, 2
         )
         
-        # Save binary image for debugging
         if DEBUG:
             cv2.imwrite(os.path.join(DEBUG_DIR, f"binary_paper_{int(time.time())}.png"), binary)
         
-        # Find contours in the binary image
         contours, _ = cv2.findContours(binary, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
         
-        if contours and len(contours) > 0:
-            # Sort contours by area (largest first)
+        if contours:
             contours = sorted(contours, key=cv2.contourArea, reverse=True)
-            
-            # Find the largest contour that has a reasonable area
-            # (to avoid small noise contours)
-            min_area_ratio = 0.05  # Minimum 5% of ROI area
+            min_area_ratio = 0.05
             roi_area = gray.shape[0] * gray.shape[1]
             valid_contours = [c for c in contours if cv2.contourArea(c) > roi_area * min_area_ratio]
             
             if valid_contours:
                 largest_contour = valid_contours[0]
                 
-                # Create a debug image showing detected contour
                 if DEBUG:
                     contour_debug = np.zeros_like(binary)
                     cv2.drawContours(contour_debug, [largest_contour], 0, 255, 2)
                     cv2.imwrite(os.path.join(DEBUG_DIR, f"paper_contour_{int(time.time())}.png"), contour_debug)
                 
-                # Get the minimum area rectangle that bounds the contour
                 rect = cv2.minAreaRect(largest_contour)
                 box = cv2.boxPoints(rect)
                 box = np.int0(box)
                 
-                # Create a debug image with rectangle
                 if DEBUG:
                     rect_debug = roi.copy() if len(roi.shape) == 3 else cv2.cvtColor(roi, cv2.COLOR_GRAY2RGB)
                     cv2.drawContours(rect_debug, [box], 0, (0, 0, 255), 2)
                     cv2.imwrite(os.path.join(DEBUG_DIR, f"paper_rect_{int(time.time())}.png"), rect_debug)
                 
-                # Extract the angle from the rectangle
                 center, (width, height), angle = rect
                 
-                # Adjust angle for consistent orientation
-                # OpenCV's minAreaRect returns angles in (-90, 0]
                 if width < height:
                     angle += 90
                 
@@ -277,37 +300,28 @@ def detect_paper_angle(image, bounding_box):
     except Exception as e:
         logging.warning(f"Error in adaptive threshold method: {str(e)}")
     
-    # Method 3: Fall back to Canny edge detection with improved parameters
+    # Method 2: Canny + Hough lines
     try:
-        # Apply Gaussian blur to reduce noise
         blurred = cv2.GaussianBlur(gray, (5, 5), 0)
-        
-        # Use automatic thresholding to determine Canny parameters
         median = np.median(blurred)
         lower = int(max(0, (1.0 - 0.33) * median))
         upper = int(min(255, (1.0 + 0.33) * median))
-        
-        # Apply edge detection with dynamic thresholds
         edges = cv2.Canny(blurred, lower, upper)
         
-        # Save edges image for debugging
         if DEBUG:
             cv2.imwrite(os.path.join(DEBUG_DIR, f"canny_edges_{int(time.time())}.png"), edges)
         
-        # Dilate edges to connect broken lines
         kernel = np.ones((3, 3), np.uint8)
         dilated_edges = cv2.dilate(edges, kernel, iterations=1)
         
-        # Find lines using Hough Line Transform with more sensitive parameters
         lines = cv2.HoughLinesP(
             dilated_edges, 1, np.pi/180, 
-            threshold=50,  # Lower threshold to detect more lines
-            minLineLength=max(roi.shape[0], roi.shape[1]) // 10,  # Minimum 10% of dimension
-            maxLineGap=20  # Allow larger gaps
+            threshold=50,
+            minLineLength=max(roi.shape[0], roi.shape[1]) // 10,
+            maxLineGap=20
         )
         
         if lines is not None and len(lines) > 0:
-            # Draw all detected lines for debugging
             if DEBUG:
                 lines_debug = roi.copy() if len(roi.shape) == 3 else cv2.cvtColor(roi, cv2.COLOR_GRAY2RGB)
                 for line in lines:
@@ -315,7 +329,6 @@ def detect_paper_angle(image, bounding_box):
                     cv2.line(lines_debug, (x1_l, y1_l), (x2_l, y2_l), (0, 255, 255), 2)
                 cv2.imwrite(os.path.join(DEBUG_DIR, f"hough_lines_{int(time.time())}.png"), lines_debug)
             
-            # Find the longest line
             longest_line = max(
                 lines,
                 key=lambda line: np.linalg.norm(
@@ -324,13 +337,10 @@ def detect_paper_angle(image, bounding_box):
             )
             x1_l, y1_l, x2_l, y2_l = longest_line[0]
             
-            # Calculate the angle of the line
             dx = x2_l - x1_l
             dy = y2_l - y1_l
             angle = degrees(atan2(dy, dx))
             
-            # Normalize angle to be between -45 and 45 degrees
-            # (assuming paper is roughly rectangular)
             if angle > 45:
                 angle -= 90
             elif angle < -45:
@@ -341,22 +351,20 @@ def detect_paper_angle(image, bounding_box):
     except Exception as e:
         logging.warning(f"Error in Hough lines method: {str(e)}")
     
-    # If all methods fail, return 0 (no rotation)
     logging.warning("All paper angle detection methods failed, defaulting to 0 degrees")
     return 0
 
-# Function to trim whitespace from handwriting image and return detailed info
+# -------------------------------------------------------------------------
+# ✂ Trim whitespace from handwriting image
+# -------------------------------------------------------------------------
 def extract_text_from_handwriting(image_path):
     try:
-        # Create a copy of the image in a temporary location
         temp_dir = tempfile.mkdtemp()
         temp_image_path = os.path.join(temp_dir, "trimmed_handwriting.png")
         debug_image_path = os.path.join(temp_dir, "debug_extraction.png")
         
-        # Open the image
         img = Image.open(image_path).convert("RGBA")
         
-        # Save the original for debugging
         if DEBUG:
             debug_img = img.copy()
             draw = ImageDraw.Draw(debug_img)
@@ -367,57 +375,46 @@ def extract_text_from_handwriting(image_path):
             )
             debug_img.save(os.path.join(DEBUG_DIR, "original_handwriting.png"))
         
-        # Get the original dimensions
         original_width, original_height = img.width, img.height
         
-        # Get the bounding box of non-zero areas (text content)
         gray_img = img.convert('L')
-        # Normalize the image to make text stand out
-        thresh = 240  # Higher threshold to catch light text
+        thresh = 240
         binary_img = gray_img.point(lambda p: p < thresh and 255)
-        # Get bounding box of text
         bbox = ImageOps.invert(binary_img).getbbox()
         
         text_dimensions = {}
         text_dimensions['original'] = {'width': original_width, 'height': original_height}
         
         if bbox:
-            # Add padding around the detected text
-            padding = 20  # Increased padding
+            padding = 20
             left, upper, right, lower = bbox
             
-            # Calculate non-whitespace area dimensions
             text_width = right - left
             text_height = lower - upper
             
-            # Add debug info
             text_dimensions['text_only'] = {'width': text_width, 'height': text_height}
             text_dimensions['text_percentage'] = {
                 'width': (text_width / original_width) * 100,
                 'height': (text_height / original_height) * 100
             }
             
-            # Add padding but ensure we don't go out of bounds
-            bbox = (max(0, left-padding), 
-                   max(0, upper-padding), 
-                   min(img.width, right+padding), 
-                   min(img.height, lower+padding))
+            bbox = (
+                max(0, left-padding), 
+                max(0, upper-padding), 
+                min(img.width, right+padding), 
+                min(img.height, lower+padding)
+            )
             
-            # Crop the image to the bounding box
             trimmed_img = img.crop(bbox)
             trimmed_img.save(temp_image_path)
             
-            # Final trimmed dimensions
             trimmed_width, trimmed_height = trimmed_img.width, trimmed_img.height
             text_dimensions['trimmed'] = {'width': trimmed_width, 'height': trimmed_height}
             
-            # Create a debug image showing the extraction
             if DEBUG:
                 debug_img = img.copy()
                 draw = ImageDraw.Draw(debug_img)
-                # Draw original bounding box
                 draw.rectangle(bbox, outline=(255, 0, 0, 255), width=2)
-                # Add text annotation
                 draw.text(
                     (bbox[0], bbox[1] - 15),
                     (
@@ -428,13 +425,11 @@ def extract_text_from_handwriting(image_path):
                     fill=(255, 0, 0, 255)
                 )
                 debug_img.save(debug_image_path)
-                # Save for reference
                 debug_img.save(os.path.join(DEBUG_DIR, "text_extraction.png"))
             
             logging.debug(f"Text extraction: {text_dimensions}")
             return temp_image_path, temp_dir, text_dimensions
         else:
-            # If no content found, just return the original
             shutil.copy(image_path, temp_image_path)
             text_dimensions['error'] = "No text content detected"
             logging.warning("No text content detected in handwriting image")
@@ -443,27 +438,26 @@ def extract_text_from_handwriting(image_path):
         logging.error(f"Error extracting text from image: {str(e)}")
         return image_path, None, {'error': str(e)}
 
-# Main processing function
+# -------------------------------------------------------------------------
+# 🖼 Main processing function
+# -------------------------------------------------------------------------
 def process_image(image, text, style, bias, color, stroke_width):
-    temp_dirs = []  # To track temporary directories to clean up
+    temp_dirs = []
     
     try:
         timestamp = int(time.time())
         
-        # Save input image for reference
         input_debug_path = os.path.join(DEBUG_DIR, f"{timestamp}_input.jpg")
         image.save(input_debug_path)
         
-        # Detect papers using Roboflow first to get paper dimensions for text formatting
+        # Roboflow detection
         rf_local = Roboflow(api_key=ROBOFLOW_API_KEY)
         project_local = rf_local.workspace().project(PROJECT_NAME)
         model_local = project_local.version(VERSION_NUMBER).model
         
-        # Save input image temporarily
         input_image_path = "/tmp/input_image.jpg"
         image.save(input_image_path)
         
-        # Perform inference to detect papers
         prediction = model_local.predict(input_image_path, confidence=70, overlap=50).json()
         num_papers = len(prediction['predictions'])
         logging.debug(f"Detected {num_papers} papers")
@@ -471,37 +465,36 @@ def process_image(image, text, style, bias, color, stroke_width):
         if num_papers == 0:
             logging.error("No papers detected in the image")
             return None
-            
-        # Format text based on the first detected paper dimensions
-        if len(prediction['predictions']) > 0:
+        
+        # Format text using first paper width
+        if prediction['predictions']:
             obj0 = prediction['predictions'][0]
             paper_width = obj0['width']
-            
-            # Calculate usable width (accounting for padding)
             padding_x = int(paper_width * 0.1)
             usable_width = paper_width - 2 * padding_x
-            
-            # Format text to fit within paper boundaries
             formatted_text = format_text_for_paper(text, usable_width)
             logging.debug(f"Formatted text for paper width {usable_width}px: \n{formatted_text}")
         else:
             formatted_text = text
             logging.debug("No papers detected, using original text")
         
-        # 1. Generate handwritten text using the Hugging Face model with formatted text
+        # Call handwriting model
         logging.debug(f"Calling handwriting model with formatted text: '{formatted_text}'")
         handwriting_client = get_handwriting_client()
         result = handwriting_client.predict(
-            formatted_text,   # Use formatted text instead of original
-            style,            # handwriting style
-            bias,             # neatness
-            color,            # ink color
-            stroke_width,     # stroke width
+            formatted_text,
+            style,
+            bias,
+            color,
+            stroke_width,
             api_name="/generate_handwriting_wrapper"
         )
-        # Result contains SVG and PNG outputs
-        svg_content, png_path = result
-        logging.debug(f"Generated handwriting PNG at: {png_path}")
+        
+        svg_content, png_output = result
+        logging.debug(f"Handwriting model raw PNG output: {png_output}")
+        
+        png_path = ensure_local_png(png_output)
+        logging.debug(f"Using PNG path: {png_path}")
         
         # Save original handwriting for reference
         orig_hw_debug_path = os.path.join(DEBUG_DIR, f"{timestamp}_original_handwriting.png")
@@ -511,55 +504,46 @@ def process_image(image, text, style, bias, color, stroke_width):
         except Exception as e:
             logging.error(f"Error saving original handwriting: {str(e)}")
         
-        # 2. Extract text from handwriting image and get dimensions
+        # Extract text and dimensions
         trimmed_path, temp_dir, text_dimensions = extract_text_from_handwriting(png_path)
         if temp_dir:
             temp_dirs.append(temp_dir)
-            
-        # Log text dimensions
+        
         logging.debug(f"Handwriting dimensions: {text_dimensions}")
         
-        # Load the trimmed handwriting image
         handwriting_img = Image.open(trimmed_path).convert("RGBA")
         logging.debug(f"Loaded trimmed handwriting image: {handwriting_img.width}x{handwriting_img.height}")
         
-        # Save trimmed handwriting for reference
         trimmed_hw_debug_path = os.path.join(DEBUG_DIR, f"{timestamp}_trimmed_handwriting.png")
         handwriting_img.save(trimmed_hw_debug_path)
         
-        # Convert the input image to RGBA for processing
         pil_image = image.convert("RGBA")
         
-        # Create a debug image showing detected papers
         debug_image = pil_image.copy()
         debug_draw = ImageDraw.Draw(debug_image)
         
-        # 3. Process each detected paper
+        # Process each detected paper
         for i, obj in enumerate(prediction['predictions']):
-            # Get paper dimensions
             paper_width = obj['width']
             paper_height = obj['height']
             
-            # Log paper dimensions
             logging.debug(f"Paper {i+1} dimensions: {paper_width}x{paper_height} at position ({obj['x']}, {obj['y']})")
             
-            # Add padding (20%)
             padding_x = int(paper_width * 0.20)
             padding_y = int(paper_height * 0.20)
             
-            # Calculate available area for text
             box_width = paper_width - 2 * padding_x
             box_height = paper_height - 2 * padding_y
             
-            # Calculate text box coordinates
             x1 = int(obj['x'] - paper_width / 2 + padding_x)
             y1 = int(obj['y'] - paper_height / 2 + padding_y)
             x2 = int(obj['x'] + paper_width / 2 - padding_x)
             y2 = int(obj['y'] + paper_height / 2 - padding_y)
             
-            # Draw paper boundary on debug image
-            paper_box = [(obj['x'] - paper_width/2, obj['y'] - paper_height/2), 
-                         (obj['x'] + paper_width/2, obj['y'] + paper_height/2)]
+            paper_box = [
+                (obj['x'] - paper_width/2, obj['y'] - paper_height/2), 
+                (obj['x'] + paper_width/2, obj['y'] + paper_height/2)
+            ]
             debug_draw.rectangle(paper_box, outline=(0, 255, 0, 255), width=3)
             debug_draw.text(
                 (paper_box[0][0], paper_box[0][1] - 15),
@@ -567,7 +551,6 @@ def process_image(image, text, style, bias, color, stroke_width):
                 fill=(0, 255, 0, 255)
             )
             
-            # Draw usable area on debug image
             usable_box = [(x1, y1), (x2, y2)]
             debug_draw.rectangle(usable_box, outline=(255, 255, 0, 255), width=2)
             debug_draw.text(
@@ -576,20 +559,17 @@ def process_image(image, text, style, bias, color, stroke_width):
                 fill=(255, 255, 0, 255)
             )
             
-            # Paper coordinates for detecting the actual paper orientation
             paper_x1 = int(obj['x'] - paper_width / 2)
             paper_y1 = int(obj['y'] - paper_height / 2)
             paper_x2 = int(obj['x'] + paper_width / 2)
             paper_y2 = int(obj['y'] + paper_height / 2)
             
-            # Detect the actual paper angle (not just the bounding box)
             angle = detect_paper_angle(
                 np.array(image),
                 (paper_x1, paper_y1, paper_x2, paper_y2)
             )
             logging.debug(f"Paper {i+1} angle: {angle} degrees")
             
-            # Add a debug visualization of the detected angle
             debug_draw.line(
                 [
                     (obj['x'], obj['y']),
@@ -607,34 +587,24 @@ def process_image(image, text, style, bias, color, stroke_width):
                 fill=(255, 0, 0, 255)
             )
             
-            # Calculate the initial size while maintaining aspect ratio
             handwriting_aspect = handwriting_img.width / handwriting_img.height
             
-            # Start with the full usable width
             target_width = box_width
-            
-            # Apply scale factor to make text larger (but don't exceed 2x usable width)
             target_width = min(int(target_width * TEXT_SCALE_FACTOR), box_width * 2)
-            
-            # Calculate height based on aspect ratio
             target_height = int(target_width / handwriting_aspect)
             
-            # If too tall, constrain by height
             if target_height > box_height:
                 target_height = box_height
                 target_width = int(target_height * handwriting_aspect)
             
-            # Ensure we're not making text too small
             min_width = int(box_width * MIN_WIDTH_PERCENTAGE)
             if target_width < min_width:
                 target_width = min_width
                 target_height = int(target_width / handwriting_aspect)
-                # Check height again
                 if target_height > box_height:
                     target_height = box_height
                     target_width = int(target_height * handwriting_aspect)
             
-            # Log sizing calculations
             logging.debug(
                 f"Paper {i+1} usable area: {box_width}x{box_height}"
             )
@@ -645,7 +615,6 @@ def process_image(image, text, style, bias, color, stroke_width):
                 f"(scale factor={TEXT_SCALE_FACTOR})"
             )
             
-            # Draw text area on debug image
             text_center_x = x1 + box_width // 2
             text_center_y = y1 + box_height // 2
             text_box = [
@@ -659,37 +628,30 @@ def process_image(image, text, style, bias, color, stroke_width):
                 fill=(255, 0, 255, 255)
             )
             
-            # Resize the handwriting with the calculated dimensions
             resized_handwriting = handwriting_img.resize(
                 (target_width, target_height),
                 Image.LANCZOS
             )
             
-            # Save resized handwriting for reference
             resized_hw_debug_path = os.path.join(
                 DEBUG_DIR,
                 f"{timestamp}_resized_handwriting_{i+1}.png"
             )
             resized_handwriting.save(resized_hw_debug_path)
             
-            # Create a transparent layer for the handwriting
             handwriting_layer = Image.new("RGBA", pil_image.size, (0, 0, 0, 0))
             
-            # Center handwriting on paper
             paste_x = x1 + (box_width - target_width) // 2
             paste_y = y1 + (box_height - target_height) // 2
             
-            # Paste handwriting onto layer
             handwriting_layer.paste(resized_handwriting, (paste_x, paste_y), resized_handwriting)
             
-            # Add to debug image
             debug_paste_box = [
                 (paste_x, paste_y),
                 (paste_x + target_width, paste_y + target_height)
             ]
             debug_draw.rectangle(debug_paste_box, outline=(0, 0, 255, 255), width=1)
             
-            # Create another debug visualization showing rotation center and angle
             rotation_debug_path = os.path.join(
                 DEBUG_DIR,
                 f"{timestamp}_rotation_paper_{i+1}.png"
@@ -720,37 +682,30 @@ def process_image(image, text, style, bias, color, stroke_width):
             )
             rotation_debug.save(rotation_debug_path)
             
-            # Rotate to match paper angle
             rotated_layer = handwriting_layer.rotate(
                 -angle,
                 resample=Image.BICUBIC,
                 center=(obj['x'], obj['y'])
             )
             
-            # Composite onto original image
             pil_image = Image.alpha_composite(pil_image, rotated_layer)
         
-        # Save debug image
         debug_path = os.path.join(DEBUG_DIR, f"{timestamp}_debug_overlay.png")
         debug_image.save(debug_path)
         logging.debug(f"Saved debug overlay image to {debug_path}")
         
-        # Save final result
         output_path = "/tmp/output_image.png"
         pil_image.convert("RGB").save(output_path)
         
-        # Also save a copy to debug directory for reference
         final_debug_path = os.path.join(DEBUG_DIR, f"{timestamp}_final_output.png")
         pil_image.save(final_debug_path)
         
-        # Clean up temporary directories
         for dir_path in temp_dirs:
             try:
                 shutil.rmtree(dir_path)
             except Exception as e:
                 logging.warning(f"Failed to clean up temporary directory {dir_path}: {str(e)}")
                 
-        # Create a comprehensive debug report
         debug_report = {
             'timestamp': timestamp,
             'input_image': input_debug_path,
@@ -779,17 +734,14 @@ def process_image(image, text, style, bias, color, stroke_width):
             'final_output': final_debug_path
         }
         
-        # Log the debug report
         logging.debug(f"Debug report: {debug_report}")
         
-        # Return paths to debug images along with the output path
         return {
             'output_path': output_path,
             'debug_report': debug_report
         }
     
     except Exception as e:
-        # Clean up temporary directories
         for dir_path in temp_dirs:
             try:
                 shutil.rmtree(dir_path)
@@ -799,10 +751,12 @@ def process_image(image, text, style, bias, color, stroke_width):
         logging.error(f"Error: {str(e)}")
         raise
 
-# Gradio interface function
+# -------------------------------------------------------------------------
+# 🎛 Gradio interface wrapper
+# -------------------------------------------------------------------------
 def gradio_process(image, text, style, bias, color, stroke_width, text_size):
     global TEXT_SCALE_FACTOR
-    TEXT_SCALE_FACTOR = text_size  # Update scale factor from UI slider
+    TEXT_SCALE_FACTOR = text_size
     
     if image is None:
         return None, None, "Please upload an image with paper."
@@ -818,11 +772,9 @@ def gradio_process(image, text, style, bias, color, stroke_width, text_size):
         output_path = result['output_path']
         debug_report = result['debug_report']
         
-        # Generate a detailed message about the process
         debug_msg = f"Processing complete!\n\n"
         debug_msg += f"Debug information in: {DEBUG_DIR}\n"
         
-        # Add information about handwriting dimensions
         if 'text_dimensions' in debug_report:
             td = debug_report['text_dimensions']
             if 'original' in td:
@@ -834,7 +786,6 @@ def gradio_process(image, text, style, bias, color, stroke_width, text_size):
             if 'trimmed' in td:
                 debug_msg += f"Trimmed size: {td['trimmed']['width']}x{td['trimmed']['height']} px\n"
         
-        # Add information about paper
         if 'paper_dimensions' in debug_report and len(debug_report['paper_dimensions']) > 0:
             paper = debug_report['paper_dimensions'][0]
             debug_msg += f"Detected paper: {paper['width']}x{paper['height']} px\n"
@@ -847,7 +798,9 @@ def gradio_process(image, text, style, bias, color, stroke_width, text_size):
         logging.exception("Processing error")
         return None, None, f"Error: {str(e)}"
 
-# Create Gradio interface
+# -------------------------------------------------------------------------
+# 🚀 Gradio App
+# -------------------------------------------------------------------------
 interface = gr.Interface(
     fn=gradio_process,
     inputs=[
@@ -872,6 +825,5 @@ interface = gr.Interface(
     )
 )
 
-# Launch app
 if __name__ == "__main__":
     interface.launch(share=True)