natural-pdf 0.1.12__py3-none-any.whl → 0.1.14__py3-none-any.whl

natural_pdf/elements/base.py

@@ -15,6 +15,40 @@ if TYPE_CHECKING:
     from natural_pdf.elements.region import Region
 
 
+def extract_bbox(obj: Any) -> Optional[Tuple[float, float, float, float]]:
+    """
+    Extract bounding box coordinates from any object that has bbox properties.
+    
+    Args:
+        obj: Object that might have bbox coordinates (Element, Region, etc.)
+        
+    Returns:
+        Tuple of (x0, top, x1, bottom) or None if object doesn't have bbox properties
+    """
+    # Try bbox property first (most common)
+    if hasattr(obj, 'bbox') and obj.bbox is not None:
+        bbox = obj.bbox
+        if isinstance(bbox, (tuple, list)) and len(bbox) == 4:
+            return tuple(float(coord) for coord in bbox)
+    
+    # Try individual coordinate properties
+    if all(hasattr(obj, attr) for attr in ['x0', 'top', 'x1', 'bottom']):
+        try:
+            return (float(obj.x0), float(obj.top), float(obj.x1), float(obj.bottom))
+        except (ValueError, TypeError):
+            pass
+    
+    # If object is a dict with bbox keys
+    if isinstance(obj, dict):
+        if all(key in obj for key in ['x0', 'top', 'x1', 'bottom']):
+            try:
+                return (float(obj['x0']), float(obj['top']), float(obj['x1']), float(obj['bottom']))
+            except (ValueError, TypeError):
+                pass
+    
+    return None
+
+
 class DirectionalMixin:
     """
     Mixin class providing directional methods for both Element and Region classes.
@@ -25,7 +59,7 @@ class DirectionalMixin:
         direction: str,
         size: Optional[float] = None,
         cross_size: str = "full",
-        include_element: bool = False,
+        include_source: bool = False,
         until: Optional[str] = None,
         include_endpoint: bool = True,
         **kwargs,
@@ -37,7 +71,7 @@ class DirectionalMixin:
             direction: 'left', 'right', 'above', or 'below'
             size: Size in the primary direction (width for horizontal, height for vertical)
             cross_size: Size in the cross direction ('full' or 'element')
-            include_element: Whether to include this element/region's area in the result
+            include_source: Whether to include this element/region's area in the result
             until: Optional selector string to specify a boundary element
             include_endpoint: Whether to include the boundary element found by 'until'
             **kwargs: Additional parameters for the 'until' selector search
@@ -51,7 +85,7 @@ class DirectionalMixin:
         is_positive = direction in ("right", "below")  # right/below are positive directions
         pixel_offset = 1  # Offset for excluding elements/endpoints
 
-        # 1. Determine initial boundaries based on direction and include_element
+        # 1. Determine initial boundaries based on direction and include_source
         if is_horizontal:
             # Initial cross-boundaries (vertical)
             y0 = 0 if cross_size == "full" else self.top
@@ -59,11 +93,11 @@ class DirectionalMixin:
 
             # Initial primary boundaries (horizontal)
             if is_positive:  # right
-                x0_initial = self.x0 if include_element else self.x1 + pixel_offset
+                x0_initial = self.x0 if include_source else self.x1 + pixel_offset
                 x1_initial = self.x1  # This edge moves
             else:  # left
                 x0_initial = self.x0  # This edge moves
-                x1_initial = self.x1 if include_element else self.x0 - pixel_offset
+                x1_initial = self.x1 if include_source else self.x0 - pixel_offset
         else:  # Vertical
             # Initial cross-boundaries (horizontal)
             x0 = 0 if cross_size == "full" else self.x0
@@ -71,11 +105,11 @@ class DirectionalMixin:
 
             # Initial primary boundaries (vertical)
             if is_positive:  # below
-                y0_initial = self.top if include_element else self.bottom + pixel_offset
+                y0_initial = self.top if include_source else self.bottom + pixel_offset
                 y1_initial = self.bottom  # This edge moves
             else:  # above
                 y0_initial = self.top  # This edge moves
-                y1_initial = self.bottom if include_element else self.top - pixel_offset
+                y1_initial = self.bottom if include_source else self.top - pixel_offset
 
         # 2. Calculate the final primary boundary, considering 'size' or page limits
         if is_horizontal:
@@ -161,7 +195,7 @@ class DirectionalMixin:
 
         result = Region(self.page, final_bbox)
         result.source_element = self
-        result.includes_source = include_element
+        result.includes_source = include_source
         # Optionally store the boundary element if found
         if target:
             result.boundary_element = target
@@ -172,7 +206,7 @@ class DirectionalMixin:
         self,
         height: Optional[float] = None,
         width: str = "full",
-        include_element: bool = False,
+        include_source: bool = False,
         until: Optional[str] = None,
         include_endpoint: bool = True,
         **kwargs,
@@ -183,7 +217,7 @@ class DirectionalMixin:
         Args:
             height: Height of the region above, in points
             width: Width mode - "full" for full page width or "element" for element width
-            include_element: Whether to include this element/region in the result (default: False)
+            include_source: Whether to include this element/region in the result (default: False)
             until: Optional selector string to specify an upper boundary element
             include_endpoint: Whether to include the boundary element in the region (default: True)
             **kwargs: Additional parameters
@@ -195,7 +229,7 @@ class DirectionalMixin:
             direction="above",
             size=height,
             cross_size=width,
-            include_element=include_element,
+            include_source=include_source,
             until=until,
             include_endpoint=include_endpoint,
             **kwargs,
@@ -205,7 +239,7 @@ class DirectionalMixin:
         self,
         height: Optional[float] = None,
         width: str = "full",
-        include_element: bool = False,
+        include_source: bool = False,
         until: Optional[str] = None,
         include_endpoint: bool = True,
         **kwargs,
@@ -216,7 +250,7 @@ class DirectionalMixin:
         Args:
             height: Height of the region below, in points
             width: Width mode - "full" for full page width or "element" for element width
-            include_element: Whether to include this element/region in the result (default: False)
+            include_source: Whether to include this element/region in the result (default: False)
             until: Optional selector string to specify a lower boundary element
             include_endpoint: Whether to include the boundary element in the region (default: True)
             **kwargs: Additional parameters
@@ -228,7 +262,7 @@ class DirectionalMixin:
             direction="below",
             size=height,
             cross_size=width,
-            include_element=include_element,
+            include_source=include_source,
             until=until,
             include_endpoint=include_endpoint,
             **kwargs,
@@ -238,7 +272,7 @@ class DirectionalMixin:
         self,
         width: Optional[float] = None,
         height: str = "full",
-        include_element: bool = False,
+        include_source: bool = False,
         until: Optional[str] = None,
         include_endpoint: bool = True,
         **kwargs,
@@ -249,7 +283,7 @@ class DirectionalMixin:
         Args:
             width: Width of the region to the left, in points
             height: Height mode - "full" for full page height or "element" for element height
-            include_element: Whether to include this element/region in the result (default: False)
+            include_source: Whether to include this element/region in the result (default: False)
             until: Optional selector string to specify a left boundary element
             include_endpoint: Whether to include the boundary element in the region (default: True)
             **kwargs: Additional parameters
@@ -261,7 +295,7 @@ class DirectionalMixin:
             direction="left",
             size=width,
             cross_size=height,
-            include_element=include_element,
+            include_source=include_source,
             until=until,
             include_endpoint=include_endpoint,
             **kwargs,
@@ -271,7 +305,7 @@ class DirectionalMixin:
         self,
         width: Optional[float] = None,
         height: str = "full",
-        include_element: bool = False,
+        include_source: bool = False,
         until: Optional[str] = None,
         include_endpoint: bool = True,
         **kwargs,
@@ -282,7 +316,7 @@ class DirectionalMixin:
         Args:
             width: Width of the region to the right, in points
             height: Height mode - "full" for full page height or "element" for element height
-            include_element: Whether to include this element/region in the result (default: False)
+            include_source: Whether to include this element/region in the result (default: False)
             until: Optional selector string to specify a right boundary element
             include_endpoint: Whether to include the boundary element in the region (default: True)
             **kwargs: Additional parameters
@@ -294,7 +328,7 @@ class DirectionalMixin:
             direction="right",
             size=width,
             cross_size=height,
-            include_element=include_element,
+            include_source=include_source,
             until=until,
             include_endpoint=include_endpoint,
             **kwargs,

natural_pdf/elements/collections.py

@@ -18,6 +18,7 @@ from typing import (
     Union,
     overload,
 )
+import hashlib
 
 from pdfplumber.utils.geometry import objects_to_bbox
 
@@ -37,6 +38,8 @@ from natural_pdf.export.mixin import ExportMixin
 from natural_pdf.ocr import OCROptions
 from natural_pdf.ocr.utils import _apply_ocr_correction_to_elements
 from natural_pdf.selectors.parser import parse_selector, selector_to_filter_func
+from natural_pdf.analyzers.shape_detection_mixin import ShapeDetectionMixin
+from tqdm.auto import tqdm
 
 # Potentially lazy imports for optional dependencies needed in save_pdf
 try:
@@ -46,8 +49,6 @@ except ImportError:
 
 try:
     from natural_pdf.exporters.searchable_pdf import create_searchable_pdf
-
-    pass
 except ImportError:
     create_searchable_pdf = None
 
@@ -64,6 +65,7 @@ if TYPE_CHECKING:
     from natural_pdf.core.page import Page
     from natural_pdf.core.pdf import PDF  # ---> ADDED PDF type hint
     from natural_pdf.elements.region import Region
+    from natural_pdf.elements.text import TextElement # Ensure TextElement is imported
 
 T = TypeVar("T")
 P = TypeVar("P", bound="Page")
@@ -1586,13 +1588,162 @@ class ElementCollection(
 
         return all_data
 
+    def to_text_elements(
+        self,
+        text_content_func: Optional[Callable[["Region"], Optional[str]]] = None, 
+        source_label: str = "derived_from_region",
+        object_type: str = "word",
+        default_font_size: float = 10.0,
+        default_font_name: str = "RegionContent",
+        confidence: Optional[float] = None,
+        add_to_page: bool = False # Default is False
+    ) -> "ElementCollection[TextElement]":
+        """
+        Converts each Region in this collection to a TextElement.
 
-class PageCollection(Generic[P], ApplyMixin):
-    """
-    A collection of PDF pages with cross-page operations.
+        Args:
+            text_content_func: A callable that takes a Region and returns its text
+                               (or None). If None, all created TextElements will
+                               have text=None.
+            source_label: The 'source' attribute for the new TextElements.
+            object_type: The 'object_type' for the TextElement's data dict.
+            default_font_size: Placeholder font size.
+            default_font_name: Placeholder font name.
+            confidence: Confidence score.
+            add_to_page: If True (default is False), also adds the created 
+                         TextElements to their respective page's element manager.
+
+        Returns:
+            A new ElementCollection containing the created TextElement objects.
+        """
+        from natural_pdf.elements.region import Region # Local import for type checking if needed or to resolve circularity
+        from natural_pdf.elements.text import TextElement # Ensure TextElement is imported for type hint if not in TYPE_CHECKING
 
-    This class provides methods for working with multiple pages, such as finding
-    elements across pages, extracting text from page ranges, and more.
+        new_text_elements: List["TextElement"] = []
+        if not self.elements: # Accesses self._elements via property
+            return ElementCollection([])
+
+        page_context_for_adding: Optional["Page"] = None
+        if add_to_page:
+            # Try to determine a consistent page context if adding elements
+            first_valid_region_with_page = next(
+                (el for el in self.elements if isinstance(el, Region) and hasattr(el, 'page') and el.page is not None), 
+                None
+            )
+            if first_valid_region_with_page:
+                page_context_for_adding = first_valid_region_with_page.page
+            else:
+                logger.warning("Cannot add TextElements to page: No valid Region with a page attribute found in collection, or first region's page is None.")
+                add_to_page = False # Disable adding if no valid page context can be determined
+
+        for element in self.elements: # Accesses self._elements via property/iterator
+            if isinstance(element, Region):
+                text_el = element.to_text_element(
+                    text_content=text_content_func, 
+                    source_label=source_label,
+                    object_type=object_type,
+                    default_font_size=default_font_size,
+                    default_font_name=default_font_name,
+                    confidence=confidence
+                )
+                new_text_elements.append(text_el)
+
+                if add_to_page:
+                    if not hasattr(text_el, 'page') or text_el.page is None:
+                        logger.warning(f"TextElement created from region {element.bbox} has no page attribute. Cannot add to page.")
+                        continue
+                    
+                    if page_context_for_adding and text_el.page == page_context_for_adding:
+                        if hasattr(page_context_for_adding, '_element_mgr') and page_context_for_adding._element_mgr is not None:
+                            add_as_type = "words" if object_type == "word" else "chars" if object_type == "char" else object_type
+                            page_context_for_adding._element_mgr.add_element(text_el, element_type=add_as_type)
+                        else:
+                            page_num_str = str(page_context_for_adding.page_number) if hasattr(page_context_for_adding, 'page_number') else 'N/A'
+                            logger.error(f"Page context for region {element.bbox} (Page {page_num_str}) is missing '_element_mgr'. Cannot add TextElement.")
+                    elif page_context_for_adding and text_el.page != page_context_for_adding:
+                        current_page_num_str = str(text_el.page.page_number) if hasattr(text_el.page, 'page_number') else "Unknown"
+                        context_page_num_str = str(page_context_for_adding.page_number) if hasattr(page_context_for_adding, 'page_number') else "N/A"
+                        logger.warning(f"TextElement for region {element.bbox} from page {current_page_num_str} "
+                                       f"not added as it's different from collection's inferred page context {context_page_num_str}.")
+                    elif not page_context_for_adding: 
+                        logger.warning(f"TextElement for region {element.bbox} created, but no page context was determined for adding.")
+            else:
+                logger.warning(f"Skipping element {type(element)}, not a Region.")
+        
+        if add_to_page and page_context_for_adding:
+            page_num_str = str(page_context_for_adding.page_number) if hasattr(page_context_for_adding, 'page_number') else 'N/A'
+            logger.info(f"Created and added {len(new_text_elements)} TextElements to page {page_num_str}.")
+        elif add_to_page and not page_context_for_adding: 
+             logger.info(f"Created {len(new_text_elements)} TextElements, but could not add to page as page context was not determined or was inconsistent.")
+        else: # add_to_page is False
+            logger.info(f"Created {len(new_text_elements)} TextElements (not added to page).")
+
+        return ElementCollection(new_text_elements)
+
+    def trim(self, padding: int = 1, threshold: float = 0.95, resolution: float = 150, show_progress: bool = True) -> "ElementCollection":
+        """
+        Trim visual whitespace from each region in the collection.
+        
+        Applies the trim() method to each element in the collection,
+        returning a new collection with the trimmed regions.
+        
+        Args:
+            padding: Number of pixels to keep as padding after trimming (default: 1)
+            threshold: Threshold for considering a row/column as whitespace (0.0-1.0, default: 0.95)
+            resolution: Resolution for image rendering in DPI (default: 150)
+            show_progress: Whether to show a progress bar for the trimming operation
+        
+        Returns:
+            New ElementCollection with trimmed regions
+        """
+        return self.apply(
+            lambda element: element.trim(padding=padding, threshold=threshold, resolution=resolution),
+            show_progress=show_progress
+        )
+
+    def clip(
+        self,
+        obj: Optional[Any] = None,
+        left: Optional[float] = None,
+        top: Optional[float] = None,
+        right: Optional[float] = None,
+        bottom: Optional[float] = None,
+    ) -> "ElementCollection":
+        """
+        Clip each element in the collection to the specified bounds.
+        
+        This method applies the clip operation to each individual element,
+        returning a new collection with the clipped elements.
+        
+        Args:
+            obj: Optional object with bbox properties (Region, Element, TextElement, etc.)
+            left: Optional left boundary (x0) to clip to
+            top: Optional top boundary to clip to  
+            right: Optional right boundary (x1) to clip to
+            bottom: Optional bottom boundary to clip to
+            
+        Returns:
+            New ElementCollection containing the clipped elements
+            
+        Examples:
+            # Clip each element to another region's bounds
+            clipped_elements = collection.clip(container_region)
+            
+            # Clip each element to specific coordinates
+            clipped_elements = collection.clip(left=100, right=400)
+            
+            # Mix object bounds with specific overrides
+            clipped_elements = collection.clip(obj=container, bottom=page.height/2)
+        """
+        return self.apply(
+            lambda element: element.clip(obj=obj, left=left, top=top, right=right, bottom=bottom)
+        )
+
+
+class PageCollection(Generic[P], ApplyMixin, ShapeDetectionMixin):
+    """
+    Represents a collection of Page objects, often from a single PDF document.
+    Provides methods for batch operations on these pages.
     """
 
     def __init__(self, pages: List[P]):
@@ -1921,7 +2072,7 @@ class PageCollection(Generic[P], ApplyMixin):
         end_elements=None,
         new_section_on_page_break=False,
         boundary_inclusion="both",
-    ) -> List["Region"]:
+    ) -> "ElementCollection[Region]":
         """
         Extract sections from a page collection based on start/end elements.
 
@@ -2214,7 +2365,7 @@ class PageCollection(Generic[P], ApplyMixin):
                 region.start_element = start_element
                 sections.append(region)
 
-        return sections
+        return ElementCollection(sections)
 
     def _gather_analysis_data(
         self,

natural_pdf/elements/line.py

@@ -28,6 +28,11 @@ class LineElement(Element):
         """
         super().__init__(obj, page)
 
+    @property
+    def source(self) -> Optional[str]:
+        """Get the source of this line element (e.g., 'pdf', 'detected')."""
+        return self._obj.get("source")
+
     @property
     def type(self) -> str:
         """Element type."""