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

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."""

natural_pdf/elements/region.py

@@ -13,6 +13,7 @@ from natural_pdf.classification.manager import ClassificationManager  # Keep for
 from natural_pdf.classification.mixin import ClassificationMixin
 from natural_pdf.elements.base import DirectionalMixin
 from natural_pdf.extraction.mixin import ExtractionMixin  # Import extraction mixin
+from natural_pdf.elements.text import TextElement # ADDED IMPORT
 from natural_pdf.ocr.utils import _apply_ocr_correction_to_elements  # Import utility
 from natural_pdf.selectors.parser import parse_selector, selector_to_filter_func
 from natural_pdf.utils.locks import pdf_render_lock  # Import the lock
@@ -20,11 +21,12 @@ from natural_pdf.utils.locks import pdf_render_lock  # Import the lock
 # Import new utils
 from natural_pdf.utils.text_extraction import filter_chars_spatially, generate_text_layout
 
-# --- NEW: Import tqdm utility --- #
-from natural_pdf.utils.tqdm_utils import get_tqdm
-
+from tqdm.auto import tqdm
 # --- End Classification Imports --- #
 
+# --- Shape Detection Mixin --- #
+from natural_pdf.analyzers.shape_detection_mixin import ShapeDetectionMixin
+# --- End Shape Detection Mixin --- # 
 
 if TYPE_CHECKING:
     # --- NEW: Add Image type hint for classification --- #
@@ -33,6 +35,7 @@ if TYPE_CHECKING:
     from natural_pdf.core.page import Page
     from natural_pdf.elements.collections import ElementCollection
     from natural_pdf.elements.text import TextElement
+    from natural_pdf.elements.base import Element # Added for type hint
 
 # Import OCRManager conditionally to avoid circular imports
 try:
@@ -44,7 +47,7 @@ except ImportError:
 logger = logging.getLogger(__name__)
 
 
-class Region(DirectionalMixin, ClassificationMixin, ExtractionMixin):
+class Region(DirectionalMixin, ClassificationMixin, ExtractionMixin, ShapeDetectionMixin):
     """
     Represents a rectangular region on a page.
     """
@@ -720,14 +723,36 @@ class Region(DirectionalMixin, ClassificationMixin, ExtractionMixin):
         Returns:
             PIL Image of just this region
         """
+        # Handle the case where user wants the cropped region to have a specific width
+        page_kwargs = kwargs.copy()
+        effective_resolution = resolution  # Start with the provided resolution
+        
+        if crop_only and 'width' in kwargs:
+            target_width = kwargs['width']
+            # Calculate what resolution is needed to make the region crop have target_width
+            region_width_points = self.width  # Region width in PDF points
+            
+            if region_width_points > 0:
+                # Calculate scale needed: target_width / region_width_points
+                required_scale = target_width / region_width_points
+                # Convert scale to resolution: scale * 72 DPI
+                effective_resolution = required_scale * 72.0
+                page_kwargs.pop('width')  # Remove width parameter to avoid conflicts
+                logger.debug(f"Region {self.bbox}: Calculated required resolution {effective_resolution:.1f} DPI for region crop width {target_width}")
+            else:
+                logger.warning(f"Region {self.bbox}: Invalid region width {region_width_points}, using original resolution")
+
         # First get the full page image with highlights if requested
         page_image = self._page.to_image(
-            scale=scale, resolution=resolution, include_highlights=include_highlights, **kwargs
+            scale=scale, resolution=effective_resolution, include_highlights=include_highlights, **page_kwargs
         )
 
-        # Calculate the crop coordinates - apply resolution scaling factor
-        # PDF coordinates are in points (1/72 inch), but image is scaled by resolution
-        scale_factor = resolution / 72.0  # Scale based on DPI
+        # Calculate the actual scale factor used by the page image
+        if page_image.width > 0 and self._page.width > 0:
+            scale_factor = page_image.width / self._page.width
+        else:
+            # Fallback to resolution-based calculation if dimensions are invalid
+            scale_factor = resolution / 72.0
 
         # Apply scaling to the coordinates
         x0 = int(self.x0 * scale_factor)
@@ -874,6 +899,233 @@ class Region(DirectionalMixin, ClassificationMixin, ExtractionMixin):
         image.save(filename)
         return self
 
+    def trim(self, padding: int = 1, threshold: float = 0.95, resolution: float = 150, pre_shrink: float = 0.5) -> "Region":
+        """
+        Trim visual whitespace from the edges of this region.
+        
+        Similar to Python's string .strip() method, but for visual whitespace in the region image.
+        Uses pixel analysis to detect rows/columns that are predominantly whitespace.
+        
+        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)
+                      Higher values mean more strict whitespace detection.
+                      E.g., 0.95 means if 95% of pixels in a row/column are white, consider it whitespace.
+            resolution: Resolution for image rendering in DPI (default: 150)
+            pre_shrink: Amount to shrink region before trimming, then expand back after (default: 0.5)
+                       This helps avoid detecting box borders/slivers as content.
+        
+        Returns:
+            New Region with visual whitespace trimmed from all edges
+            
+        Example:
+            # Basic trimming with 1 pixel padding and 0.5px pre-shrink
+            trimmed = region.trim()
+            
+            # More aggressive trimming with no padding and no pre-shrink
+            tight = region.trim(padding=0, threshold=0.9, pre_shrink=0)
+            
+            # Conservative trimming with more padding
+            loose = region.trim(padding=3, threshold=0.98)
+        """
+        # Pre-shrink the region to avoid box slivers
+        work_region = self.expand(left=-pre_shrink, right=-pre_shrink, top=-pre_shrink, bottom=-pre_shrink) if pre_shrink > 0 else self
+        
+        # Get the region image
+        image = work_region.to_image(resolution=resolution, crop_only=True, include_highlights=False)
+        
+        if image is None:
+            logger.warning(f"Region {self.bbox}: Could not generate image for trimming. Returning original region.")
+            return self
+            
+        # Convert to grayscale for easier analysis
+        import numpy as np
+        
+        # Convert PIL image to numpy array
+        img_array = np.array(image.convert('L'))  # Convert to grayscale
+        height, width = img_array.shape
+        
+        if height == 0 or width == 0:
+            logger.warning(f"Region {self.bbox}: Image has zero dimensions. Returning original region.")
+            return self
+        
+        # Normalize pixel values to 0-1 range (255 = white = 1.0, 0 = black = 0.0)
+        normalized = img_array.astype(np.float32) / 255.0
+        
+        # Find content boundaries by analyzing row and column averages
+        
+        # Analyze rows (horizontal strips) to find top and bottom boundaries
+        row_averages = np.mean(normalized, axis=1)  # Average each row
+        content_rows = row_averages < threshold  # True where there's content (not whitespace)
+        
+        # Find first and last rows with content
+        content_row_indices = np.where(content_rows)[0]
+        if len(content_row_indices) == 0:
+            # No content found, return a minimal region at the center
+            logger.warning(f"Region {self.bbox}: No content detected during trimming. Returning center point.")
+            center_x = (self.x0 + self.x1) / 2
+            center_y = (self.top + self.bottom) / 2
+            return Region(self.page, (center_x, center_y, center_x, center_y))
+        
+        top_content_row = max(0, content_row_indices[0] - padding)
+        bottom_content_row = min(height - 1, content_row_indices[-1] + padding)
+        
+        # Analyze columns (vertical strips) to find left and right boundaries  
+        col_averages = np.mean(normalized, axis=0)  # Average each column
+        content_cols = col_averages < threshold  # True where there's content
+        
+        content_col_indices = np.where(content_cols)[0]
+        if len(content_col_indices) == 0:
+            # No content found in columns either
+            logger.warning(f"Region {self.bbox}: No column content detected during trimming. Returning center point.")
+            center_x = (self.x0 + self.x1) / 2
+            center_y = (self.top + self.bottom) / 2
+            return Region(self.page, (center_x, center_y, center_x, center_y))
+            
+        left_content_col = max(0, content_col_indices[0] - padding)
+        right_content_col = min(width - 1, content_col_indices[-1] + padding)
+        
+        # Convert trimmed pixel coordinates back to PDF coordinates
+        scale_factor = resolution / 72.0  # Scale factor used in to_image()
+        
+        # Calculate new PDF coordinates and ensure they are Python floats
+        trimmed_x0 = float(work_region.x0 + (left_content_col / scale_factor))
+        trimmed_top = float(work_region.top + (top_content_row / scale_factor))
+        trimmed_x1 = float(work_region.x0 + ((right_content_col + 1) / scale_factor))  # +1 because we want inclusive right edge
+        trimmed_bottom = float(work_region.top + ((bottom_content_row + 1) / scale_factor))  # +1 because we want inclusive bottom edge
+        
+        # Ensure the trimmed region doesn't exceed the work region boundaries
+        final_x0 = max(work_region.x0, trimmed_x0)
+        final_top = max(work_region.top, trimmed_top)
+        final_x1 = min(work_region.x1, trimmed_x1)
+        final_bottom = min(work_region.bottom, trimmed_bottom)
+        
+        # Ensure valid coordinates (width > 0, height > 0)
+        if final_x1 <= final_x0 or final_bottom <= final_top:
+            logger.warning(f"Region {self.bbox}: Trimming resulted in invalid dimensions. Returning original region.")
+            return self
+        
+        # Create the trimmed region
+        trimmed_region = Region(self.page, (final_x0, final_top, final_x1, final_bottom))
+        
+        # Expand back by the pre_shrink amount to restore original positioning
+        if pre_shrink > 0:
+            trimmed_region = trimmed_region.expand(left=pre_shrink, right=pre_shrink, top=pre_shrink, bottom=pre_shrink)
+        
+        # Copy relevant metadata
+        trimmed_region.region_type = self.region_type
+        trimmed_region.normalized_type = self.normalized_type
+        trimmed_region.confidence = self.confidence
+        trimmed_region.model = self.model
+        trimmed_region.name = self.name
+        trimmed_region.label = self.label
+        trimmed_region.source = "trimmed"  # Indicate this is a derived region
+        trimmed_region.parent_region = self
+        
+        logger.debug(f"Region {self.bbox}: Trimmed to {trimmed_region.bbox} (padding={padding}, threshold={threshold}, pre_shrink={pre_shrink})")
+        return trimmed_region
+
+    def clip(
+        self,
+        obj: Optional[Any] = None,
+        left: Optional[float] = None,
+        top: Optional[float] = None,
+        right: Optional[float] = None,
+        bottom: Optional[float] = None,
+    ) -> "Region":
+        """
+        Clip this region to specific bounds, either from another object with bbox or explicit coordinates.
+        
+        The clipped region will be constrained to not exceed the specified boundaries.
+        You can provide either an object with bounding box properties, specific coordinates, or both.
+        When both are provided, explicit coordinates take precedence.
+        
+        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 Region with bounds clipped to the specified constraints
+            
+        Examples:
+            # Clip to another region's bounds
+            clipped = region.clip(container_region)
+            
+            # Clip to any element's bounds
+            clipped = region.clip(text_element)
+            
+            # Clip to specific coordinates
+            clipped = region.clip(left=100, right=400)
+            
+            # Mix object bounds with specific overrides
+            clipped = region.clip(obj=container, bottom=page.height/2)
+        """
+        from natural_pdf.elements.base import extract_bbox
+        
+        # Start with current region bounds
+        clip_x0 = self.x0
+        clip_top = self.top
+        clip_x1 = self.x1
+        clip_bottom = self.bottom
+        
+        # Apply object constraints if provided
+        if obj is not None:
+            obj_bbox = extract_bbox(obj)
+            if obj_bbox is not None:
+                obj_x0, obj_top, obj_x1, obj_bottom = obj_bbox
+                # Constrain to the intersection with the provided object
+                clip_x0 = max(clip_x0, obj_x0)
+                clip_top = max(clip_top, obj_top)
+                clip_x1 = min(clip_x1, obj_x1)
+                clip_bottom = min(clip_bottom, obj_bottom)
+            else:
+                logger.warning(
+                    f"Region {self.bbox}: Cannot extract bbox from clipping object {type(obj)}. "
+                    "Object must have bbox property or x0/top/x1/bottom attributes."
+                )
+        
+        # Apply explicit coordinate constraints (these take precedence)
+        if left is not None:
+            clip_x0 = max(clip_x0, left)
+        if top is not None:
+            clip_top = max(clip_top, top)
+        if right is not None:
+            clip_x1 = min(clip_x1, right)
+        if bottom is not None:
+            clip_bottom = min(clip_bottom, bottom)
+        
+        # Ensure valid coordinates
+        if clip_x1 <= clip_x0 or clip_bottom <= clip_top:
+            logger.warning(
+                f"Region {self.bbox}: Clipping resulted in invalid dimensions "
+                f"({clip_x0}, {clip_top}, {clip_x1}, {clip_bottom}). Returning minimal region."
+            )
+            # Return a minimal region at the clip area's top-left
+            return Region(self.page, (clip_x0, clip_top, clip_x0, clip_top))
+        
+        # Create the clipped region
+        clipped_region = Region(self.page, (clip_x0, clip_top, clip_x1, clip_bottom))
+        
+        # Copy relevant metadata
+        clipped_region.region_type = self.region_type
+        clipped_region.normalized_type = self.normalized_type
+        clipped_region.confidence = self.confidence
+        clipped_region.model = self.model
+        clipped_region.name = self.name
+        clipped_region.label = self.label
+        clipped_region.source = "clipped"  # Indicate this is a derived region
+        clipped_region.parent_region = self
+        
+        logger.debug(
+            f"Region {self.bbox}: Clipped to {clipped_region.bbox} "
+            f"(constraints: obj={type(obj).__name__ if obj else None}, "
+            f"left={left}, top={top}, right={right}, bottom={bottom})"
+        )
+        return clipped_region
+
     def get_elements(
         self, selector: Optional[str] = None, apply_exclusions=True, **kwargs
     ) -> List["Element"]:
@@ -1261,8 +1513,6 @@ class Region(DirectionalMixin, ClassificationMixin, ExtractionMixin):
         unique_tops = cluster_coords(tops)
         unique_lefts = cluster_coords(lefts)
 
-        # --- Setup tqdm --- #
-        tqdm = get_tqdm()
         # Determine iterable for tqdm
         cell_iterator = cell_dicts
         if show_progress:
@@ -1777,7 +2027,7 @@ class Region(DirectionalMixin, ClassificationMixin, ExtractionMixin):
 
     def get_sections(
         self, start_elements=None, end_elements=None, boundary_inclusion="both"
-    ) -> List["Region"]:
+    ) -> "ElementCollection[Region]":
         """
         Get sections within this region based on start/end elements.
 
@@ -1897,7 +2147,7 @@ class Region(DirectionalMixin, ClassificationMixin, ExtractionMixin):
             section = self.get_section_between(start_element, end_element, boundary_inclusion)
             sections.append(section)
 
-        return sections
+        return ElementCollection(sections)
 
     def create_cells(self):
         """
@@ -2413,3 +2663,94 @@ class Region(DirectionalMixin, ClassificationMixin, ExtractionMixin):
         return ElementCollection(cell_regions)
 
     # --- END NEW METHOD ---
+
+    def to_text_element(
+        self,
+        text_content: Optional[Union[str, Callable[["Region"], Optional[str]]]] = None,
+        source_label: str = "derived_from_region",
+        object_type: str = "word", # Or "char", controls how it's categorized
+        default_font_size: float = 10.0,
+        default_font_name: str = "RegionContent",
+        confidence: Optional[float] = None, # Allow overriding confidence
+        add_to_page: bool = False # NEW: Option to add to page
+    ) -> "TextElement":
+        """
+        Creates a new TextElement object based on this region's geometry.
+
+        The text for the new TextElement can be provided directly,
+        generated by a callback function, or left as None.
+
+        Args:
+            text_content:
+                - If a string, this will be the text of the new TextElement.
+                - If a callable, it will be called with this region instance
+                  and its return value (a string or None) will be the text.
+                - If None (default), the TextElement's text will be None.
+            source_label: The 'source' attribute for the new TextElement.
+            object_type: The 'object_type' for the TextElement's data dict
+                         (e.g., "word", "char").
+            default_font_size: Placeholder font size if text is generated.
+            default_font_name: Placeholder font name if text is generated.
+            confidence: Confidence score for the text. If text_content is None,
+                        defaults to 0.0. If text is provided/generated, defaults to 1.0
+                        unless specified.
+            add_to_page: If True, the created TextElement will be added to the
+                         region's parent page. (Default: False)
+
+        Returns:
+            A new TextElement instance.
+        
+        Raises:
+            ValueError: If the region does not have a valid 'page' attribute.
+        """
+        actual_text: Optional[str] = None
+        if isinstance(text_content, str):
+            actual_text = text_content
+        elif callable(text_content):
+            try:
+                actual_text = text_content(self)
+            except Exception as e:
+                logger.error(f"Error executing text_content callback for region {self.bbox}: {e}", exc_info=True)
+                actual_text = None # Ensure actual_text is None on error
+
+        final_confidence = confidence
+        if final_confidence is None:
+            final_confidence = 1.0 if actual_text is not None and actual_text.strip() else 0.0
+
+        if not hasattr(self, 'page') or self.page is None:
+            raise ValueError("Region must have a valid 'page' attribute to create a TextElement.")
+
+        elem_data = {
+            "text": actual_text,
+            "x0": self.x0,
+            "top": self.top,
+            "x1": self.x1,
+            "bottom": self.bottom,
+            "width": self.width,
+            "height": self.height,
+            "object_type": object_type,
+            "page_number": self.page.page_number,
+            "stroking_color": getattr(self, 'stroking_color', (0,0,0)),
+            "non_stroking_color": getattr(self, 'non_stroking_color', (0,0,0)),
+            "fontname": default_font_name,
+            "size": default_font_size,
+            "upright": True,
+            "direction": 1,
+            "adv": self.width,
+            "source": source_label,
+            "confidence": final_confidence,
+            "_char_dicts": [] 
+        }
+        text_element = TextElement(elem_data, self.page)
+
+        if add_to_page:
+            if hasattr(self.page, '_element_mgr') and self.page._element_mgr is not None:
+                add_as_type = "words" if object_type == "word" else "chars" if object_type == "char" else object_type
+                # REMOVED try-except block around add_element
+                self.page._element_mgr.add_element(text_element, element_type=add_as_type)
+                logger.debug(f"TextElement created from region {self.bbox} and added to page {self.page.page_number} as {add_as_type}.")
+            else:
+                page_num_str = str(self.page.page_number) if hasattr(self.page, 'page_number') else 'N/A'
+                logger.warning(f"Cannot add TextElement to page: Page {page_num_str} for region {self.bbox} is missing '_element_mgr'.")
+        
+        return text_element