natural-pdf 0.1.0__py3-none-any.whl

natural_pdf/utils/reading_order.py

@@ -0,0 +1,227 @@
+"""
+Reading order utilities for natural-pdf.
+"""
+from typing import List, Dict, Any, Callable, Optional
+
+
+def establish_reading_order(elements: List[Dict[str, Any]], 
+                           algorithm: str = 'basic') -> List[Dict[str, Any]]:
+    """
+    Establish reading order for a collection of elements.
+    
+    Args:
+        elements: List of elements to order
+        algorithm: Algorithm to use ('basic', 'column', 'complex')
+        
+    Returns:
+        List of elements in reading order
+    """
+    if algorithm == 'basic':
+        return _basic_reading_order(elements)
+    elif algorithm == 'column':
+        return _column_reading_order(elements)
+    elif algorithm == 'complex':
+        return _complex_reading_order(elements)
+    else:
+        # Default to basic
+        return _basic_reading_order(elements)
+
+
+def _basic_reading_order(elements: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    """
+    Basic top-to-bottom, left-to-right reading order.
+    
+    Args:
+        elements: List of elements to order
+        
+    Returns:
+        List of elements in reading order
+    """
+    # Simple sort by y0 (top), then by x0 (left)
+    return sorted(elements, key=lambda e: (
+        e.get('top', e.get('y0', 0)), 
+        e.get('x0', 0)
+    ))
+
+
+def _column_reading_order(elements: List[Dict[str, Any]], 
+                         column_threshold: float = 0.2,
+                         x_tolerance: float = 10.0) -> List[Dict[str, Any]]:
+    """
+    Reading order that accounts for columns.
+    
+    This is more complex as it needs to detect columns first,
+    then read each column in order.
+    
+    Args:
+        elements: List of elements to order
+        column_threshold: Percentage overlap threshold for column detection (0.0 to 1.0)
+        x_tolerance: Horizontal tolerance for determining column edges
+        
+    Returns:
+        List of elements in reading order
+    """
+    if not elements:
+        return []
+    
+    # 1. Group elements by line
+    lines = group_elements_by_line(elements)
+    
+    # 2. For each line, find the x-coordinate ranges (potential column boundaries)
+    line_x_ranges = []
+    for line in lines:
+        for el in line:
+            x0 = el.get('x0', 0)
+            x1 = el.get('x1', 0)
+            line_x_ranges.append((x0, x1))
+    
+    # If we don't have enough ranges to detect columns, just use basic ordering
+    if len(line_x_ranges) < 3:
+        return _basic_reading_order(elements)
+    
+    # 3. Detect columns by clustering x-coordinate ranges
+    def overlaps(range1, range2, threshold=column_threshold):
+        """Determine if two ranges overlap by more than threshold percentage."""
+        # Calculate overlap
+        overlap_start = max(range1[0], range2[0])
+        overlap_end = min(range1[1], range2[1])
+        overlap = max(0, overlap_end - overlap_start)
+        
+        # Calculate lengths
+        len1 = range1[1] - range1[0]
+        len2 = range2[1] - range2[0]
+        
+        # Calculate overlap as percentage of the shorter range
+        shorter_len = min(len1, len2)
+        if shorter_len == 0:
+            return False
+            
+        return overlap / shorter_len >= threshold
+    
+    # Cluster x-ranges into columns
+    columns = []
+    for x_range in line_x_ranges:
+        # Skip zero-width ranges
+        if x_range[1] - x_range[0] <= 0:
+            continue
+            
+        # Try to find an existing column to add to
+        added = False
+        for col in columns:
+            if any(overlaps(x_range, r) for r in col):
+                col.append(x_range)
+                added = True
+                break
+                
+        # If not added to an existing column, create a new one
+        if not added:
+            columns.append([x_range])
+    
+    # 4. Get column boundaries by averaging x-ranges in each column
+    column_bounds = []
+    for col in columns:
+        left = sum(r[0] for r in col) / len(col)
+        right = sum(r[1] for r in col) / len(col)
+        column_bounds.append((left, right))
+    
+    # Sort columns by x-coordinate (left to right)
+    column_bounds.sort(key=lambda b: b[0])
+    
+    # 5. Assign each element to a column
+    element_columns = {}
+    for el in elements:
+        # Get element x-coordinates
+        el_x0 = el.get('x0', 0)
+        el_x1 = el.get('x1', 0)
+        el_center = (el_x0 + el_x1) / 2
+        
+        # Find the column this element belongs to
+        for i, (left, right) in enumerate(column_bounds):
+            # Extend bounds by tolerance
+            extended_left = left - x_tolerance
+            extended_right = right + x_tolerance
+            
+            # Check if center point is within extended column bounds
+            if extended_left <= el_center <= extended_right:
+                element_columns[el] = i
+                break
+        else:
+            # If no column found, assign to nearest column
+            distances = [(i, min(abs(el_center - left), abs(el_center - right)))
+                         for i, (left, right) in enumerate(column_bounds)]
+            nearest_col = min(distances, key=lambda d: d[1])[0]
+            element_columns[el] = nearest_col
+    
+    # 6. Sort elements by column, then by vertical position
+    sorted_elements = []
+    for col_idx, _ in enumerate(column_bounds):
+        # Get elements in this column
+        col_elements = [el for el in elements if element_columns.get(el) == col_idx]
+        # Sort by top coordinate
+        col_elements.sort(key=lambda e: e.get('top', e.get('y0', 0)))
+        # Add to final list
+        sorted_elements.extend(col_elements)
+    
+    return sorted_elements
+
+
+def _complex_reading_order(elements: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    """
+    Complex reading order that accounts for various document structures.
+    
+    This considers columns, text flow around images, tables, etc.
+    
+    Args:
+        elements: List of elements to order
+        
+    Returns:
+        List of elements in reading order
+    """
+    # TODO: Implement complex layout analysis
+    # For now, fall back to column-aware reading order
+    return _column_reading_order(elements)
+
+
+def group_elements_by_line(elements: List[Dict[str, Any]], 
+                          tolerance: float = 3.0) -> List[List[Dict[str, Any]]]:
+    """
+    Group elements into lines based on vertical position.
+    
+    Args:
+        elements: List of elements to group
+        tolerance: Maximum vertical distance for elements to be considered on the same line
+        
+    Returns:
+        List of lists, where each sublist contains elements on the same line
+    """
+    if not elements:
+        return []
+    
+    # Sort by top coordinate
+    sorted_elements = sorted(elements, key=lambda e: e.get('top', e.get('y0', 0)))
+    
+    lines = []
+    current_line = [sorted_elements[0]]
+    current_top = sorted_elements[0].get('top', sorted_elements[0].get('y0', 0))
+    
+    for element in sorted_elements[1:]:
+        element_top = element.get('top', element.get('y0', 0))
+        
+        # If element is close enough to current line's top, add to current line
+        if abs(element_top - current_top) <= tolerance:
+            current_line.append(element)
+        else:
+            # Otherwise, start a new line
+            lines.append(current_line)
+            current_line = [element]
+            current_top = element_top
+    
+    # Add the last line
+    if current_line:
+        lines.append(current_line)
+    
+    # Sort elements within each line by x0
+    for line in lines:
+        line.sort(key=lambda e: e.get('x0', 0))
+    
+    return lines

natural_pdf/utils/visualization.py

@@ -0,0 +1,223 @@
+"""
+Visualization utilities for natural-pdf.
+"""
+from typing import List, Dict, Tuple, Optional, Union, Any, Set
+import io
+import math
+import random
+import itertools # Added for cycling
+from PIL import Image, ImageDraw, ImageFont
+
+# Define a base list of visually distinct colors for highlighting
+# Format: (R, G, B)
+_BASE_HIGHLIGHT_COLORS = [
+    (255, 0, 0),      # Red
+    (0, 255, 0),      # Green
+    (0, 0, 255),      # Blue
+    (255, 0, 255),    # Magenta
+    (0, 255, 255),    # Cyan
+    (255, 165, 0),    # Orange
+    (128, 0, 128),    # Purple
+    (0, 128, 0),      # Dark Green
+    (0, 0, 128),      # Navy
+    (255, 215, 0),    # Gold
+    (75, 0, 130),     # Indigo
+    (240, 128, 128),  # Light Coral
+    (32, 178, 170),   # Light Sea Green
+    (138, 43, 226),   # Blue Violet
+    (160, 82, 45),    # Sienna
+]
+
+# Default Alpha for highlight fills
+DEFAULT_FILL_ALPHA = 100
+
+class ColorManager:
+    """
+    Manages color assignment for highlights, ensuring consistency for labels.
+    """
+    def __init__(self, alpha: int = DEFAULT_FILL_ALPHA):
+        """
+        Initializes the ColorManager.
+
+        Args:
+            alpha (int): The default alpha transparency (0-255) for highlight fills.
+        """
+        self._alpha = alpha
+        # Shuffle the base colors to avoid the same sequence every time
+        self._available_colors = random.sample(_BASE_HIGHLIGHT_COLORS, len(_BASE_HIGHLIGHT_COLORS))
+        self._color_cycle = itertools.cycle(self._available_colors)
+        self._labels_colors: Dict[str, Tuple[int, int, int, int]] = {}
+
+    def _get_rgba_color(self, rgb: Tuple[int, int, int]) -> Tuple[int, int, int, int]:
+        """Applies the instance's alpha to an RGB tuple."""
+        return (*rgb, self._alpha)
+
+    def get_color(self, label: Optional[str] = None, 
+                  force_cycle: bool = False) -> Tuple[int, int, int, int]:
+        """
+        Gets an RGBA color tuple.
+
+        If a label is provided, it returns a consistent color for that label.
+        If no label is provided, it cycles through the available colors (unless force_cycle=False).
+        If force_cycle is True, it always returns the next color in the cycle, ignoring the label.
+
+        Args:
+            label (Optional[str]): The label associated with the highlight.
+            force_cycle (bool): If True, ignore the label and always get the next cycle color.
+
+        Returns:
+            Tuple[int, int, int, int]: An RGBA color tuple (0-255).
+        """
+        if force_cycle:
+            # Always get the next color, don't store by label
+            rgb = next(self._color_cycle)
+            return self._get_rgba_color(rgb)
+            
+        if label is not None:
+            if label in self._labels_colors:
+                # Return existing color for this label
+                return self._labels_colors[label]
+            else:
+                # New label, get next color and store it
+                rgb = next(self._color_cycle)
+                rgba = self._get_rgba_color(rgb)
+                self._labels_colors[label] = rgba
+                return rgba
+        else:
+            # No label and not forced cycle - get next color from cycle
+            rgb = next(self._color_cycle)
+            return self._get_rgba_color(rgb)
+
+    def get_label_colors(self) -> Dict[str, Tuple[int, int, int, int]]:
+        """Returns the current mapping of labels to colors."""
+        return self._labels_colors.copy()
+
+    def reset(self) -> None:
+        """Resets the color cycle and clears the label-to-color mapping."""
+        # Re-shuffle and reset the cycle
+        self._available_colors = random.sample(_BASE_HIGHLIGHT_COLORS, len(_BASE_HIGHLIGHT_COLORS))
+        self._color_cycle = itertools.cycle(self._available_colors)
+        self._labels_colors = {}
+
+# --- Global color state and functions removed --- 
+# HIGHLIGHT_COLORS, _color_cycle, _current_labels_colors, _used_colors_iterator
+# get_next_highlight_color(), reset_highlight_colors()
+
+def create_legend(labels_colors: Dict[str, Tuple[int, int, int, int]], 
+                 width: int = 200, 
+                 item_height: int = 30) -> Image.Image:
+    """
+    Create a legend image for the highlighted elements.
+    
+    Args:
+        labels_colors: Dictionary mapping labels to colors
+        width: Width of the legend image
+        item_height: Height of each legend item
+        
+    Returns:
+        PIL Image with the legend
+    """
+    # Calculate the height based on the number of labels
+    height = len(labels_colors) * item_height + 10  # 10px padding
+    
+    # Create a white image
+    legend = Image.new('RGBA', (width, height), (255, 255, 255, 255))
+    draw = ImageDraw.Draw(legend)
+    
+    # Try to load a font, use default if not available
+    try:
+        # Use a commonly available font, adjust size
+        font = ImageFont.truetype("DejaVuSans.ttf", 12) 
+    except IOError:
+        try:
+             font = ImageFont.truetype("Arial.ttf", 12)
+        except IOError:
+            font = ImageFont.load_default()
+    
+    # Draw each legend item
+    y = 5  # Start with 5px padding
+    for label, color in labels_colors.items():
+        # Get the color components
+        # Handle potential case where alpha isn't provided (use default 255)
+        if len(color) == 3:
+            r, g, b = color
+            alpha = 255 # Assume opaque if alpha is missing
+        else:
+            r, g, b, alpha = color
+        
+        # Calculate the apparent color when drawn on white background
+        # Alpha blending formula: result = (source * alpha) + (dest * (1-alpha))
+        # Where alpha is normalized to 0-1 range
+        alpha_norm = alpha / 255.0
+        apparent_r = int(r * alpha_norm + 255 * (1 - alpha_norm))
+        apparent_g = int(g * alpha_norm + 255 * (1 - alpha_norm))
+        apparent_b = int(b * alpha_norm + 255 * (1 - alpha_norm))
+        
+        # Use solid color that matches the apparent color of the semi-transparent highlight
+        legend_color = (apparent_r, apparent_g, apparent_b, 255)
+        
+        # Draw the color box
+        draw.rectangle([(10, y), (30, y + item_height - 5)], fill=legend_color)
+        
+        # Draw the label text
+        draw.text((40, y + (item_height // 2) - 6), label, fill=(0, 0, 0, 255), font=font)
+        
+        # Move to the next position
+        y += item_height
+    
+    return legend
+
+def merge_images_with_legend(image: Image.Image, 
+                            legend: Image.Image, 
+                            position: str = 'right') -> Image.Image:
+    """
+    Merge an image with a legend.
+    
+    Args:
+        image: Main image
+        legend: Legend image
+        position: Position of the legend ('right', 'bottom', 'top', 'left')
+        
+    Returns:
+        Merged image
+    """
+    if not legend:
+        return image # Return original image if legend is None or empty
+        
+    # Determine background color from top-left pixel (safer than assuming white)
+    bg_color = image.getpixel((0,0)) if image.mode == 'RGBA' else (255, 255, 255, 255)
+
+    if position == 'right':
+        # Create a new image with extra width for the legend
+        merged_width = image.width + legend.width
+        merged_height = max(image.height, legend.height)
+        merged = Image.new('RGBA', (merged_width, merged_height), bg_color)
+        merged.paste(image, (0, 0))
+        merged.paste(legend, (image.width, 0), legend if legend.mode == 'RGBA' else None) # Handle transparency
+    elif position == 'bottom':
+        # Create a new image with extra height for the legend
+        merged_width = max(image.width, legend.width)
+        merged_height = image.height + legend.height
+        merged = Image.new('RGBA', (merged_width, merged_height), bg_color)
+        merged.paste(image, (0, 0))
+        merged.paste(legend, (0, image.height), legend if legend.mode == 'RGBA' else None)
+    elif position == 'top':
+        # Create a new image with extra height for the legend
+        merged_width = max(image.width, legend.width)
+        merged_height = image.height + legend.height
+        merged = Image.new('RGBA', (merged_width, merged_height), bg_color)
+        merged.paste(legend, (0, 0), legend if legend.mode == 'RGBA' else None)
+        merged.paste(image, (0, legend.height))
+    elif position == 'left':
+        # Create a new image with extra width for the legend
+        merged_width = image.width + legend.width
+        merged_height = max(image.height, legend.height)
+        merged = Image.new('RGBA', (merged_width, merged_height), bg_color)
+        merged.paste(legend, (0, 0), legend if legend.mode == 'RGBA' else None)
+        merged.paste(image, (legend.width, 0))
+    else:
+        # Invalid position, return the original image
+        print(f"Warning: Invalid legend position '{position}'. Returning original image.")
+        merged = image
+    
+    return merged

natural_pdf/widgets/__init__.py

@@ -0,0 +1,4 @@
+from .viewer import SimpleInteractiveViewerWidget as InteractiveViewerWidget
+
+# Also provide the original implementation for reference
+from .viewer import InteractiveViewerWidget as _OriginalInteractiveViewerWidget 

natural_pdf/widgets/frontend/viewer.js

@@ -0,0 +1,88 @@
+// natural_pdf/widgets/frontend/viewer.js
+// Minimal version for debugging module loading
+
+(function() {
+    // Use a flag to prevent multiple definitions if this script runs multiple times
+    if (window.interactiveViewerWidgetDefined) {
+        console.log("[DEBUG] viewer_widget already defined. Skipping re-definition.");
+        // If it was already defined, maybe trigger a manual load if require is available?
+        // This is tricky because the initial load might have failed partially.
+        if (typeof require !== 'undefined') {
+             console.log("[DEBUG] Attempting require(['viewer_widget'])...");
+             try {
+                 require(['viewer_widget'], function(module) {
+                     console.log("[DEBUG] Manual require succeeded:", module);
+                 }, function(err) {
+                     console.error("[DEBUG] Manual require failed:", err);
+                 });
+             } catch (e) {
+                 console.error("[DEBUG] Error during manual require:", e);
+             }
+        }
+        return;
+    }
+    window.interactiveViewerWidgetDefined = true;
+    console.log("[DEBUG] Defining viewer_widget module for the first time...");
+
+    // Check for requirejs *after* setting the flag, before defining
+     if (typeof requirejs === 'undefined') {
+         console.error('[DEBUG] requirejs is still not defined. Widget frontend cannot load.');
+         // Maybe display an error in the widget area itself?
+         // This suggests a fundamental issue with the Jupyter environment setup.
+         return;
+     }
+     if (typeof define !== 'function' || !define.amd) {
+          console.error('[DEBUG] define is not a function or define.amd is missing. Cannot define module.');
+          return;
+     }
+
+    // Clear any previous potentially failed definition
+    require.undef('viewer_widget');
+
+    // Define the module
+    define('viewer_widget', ['@jupyter-widgets/base'], function(widgets) {
+        console.log("[DEBUG] viewer_widget define callback executed.");
+        console.log("[DEBUG] @jupyter-widgets/base loaded:", widgets);
+
+        // Define a very simple view class
+        class InteractiveViewerView extends widgets.DOMWidgetView {
+            render() {
+                console.log("[DEBUG] InteractiveViewerView: render() called.");
+                this.el.textContent = 'Minimal Widget Loaded!'; // Simple text content
+                this.el.style.border = '2px solid green';
+                this.el.style.padding = '10px';
+
+                // Log received data
+                this.model.on('change:image_uri', () => console.log("[DEBUG] image_uri changed:", this.model.get('image_uri') ? 'Present' : 'Empty'), this);
+                this.model.on('change:page_dimensions', () => console.log("[DEBUG] page_dimensions changed:", this.model.get('page_dimensions')), this);
+                this.model.on('change:elements', () => console.log("[DEBUG] elements changed:", this.model.get('elements').length), this);
+
+                 // Log initial data
+                 console.log("[DEBUG] Initial image_uri:", this.model.get('image_uri') ? 'Present' : 'Empty');
+                 console.log("[DEBUG] Initial page_dimensions:", this.model.get('page_dimensions'));
+                 console.log("[DEBUG] Initial elements count:", this.model.get('elements').length);
+            }
+
+            remove() {
+                console.log("[DEBUG] InteractiveViewerView: remove() called.");
+                super.remove();
+            }
+        }
+
+        console.log("[DEBUG] viewer_widget module definition returning view.");
+        // Return the view class
+        return {
+            InteractiveViewerView: InteractiveViewerView
+        };
+    }, function(err) {
+         // Error callback for the define function
+         console.error("[DEBUG] Error loading module dependencies:", err);
+         const failedId = err.requireModules && err.requireModules[0];
+         if (failedId === 'react' || failedId === 'react-dom' || failedId === 'htm') {
+             console.error(`[DEBUG] Failed to load CDN dependency: ${failedId}. Check network connection and CDN availability.`);
+         } else if (failedId === '@jupyter-widgets/base') {
+              console.error("[DEBUG] Failed to load @jupyter-widgets/base. Ensure ipywidgets frontend is installed and enabled.");
+         }
+    });
+
+})();