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

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)
@@ -772,6 +797,7 @@ class Region(DirectionalMixin, ClassificationMixin, ExtractionMixin):
         # Add a default color for standalone show
         color: Optional[Union[Tuple, str]] = "blue",
         label: Optional[str] = None,
+        width: Optional[int] = None,  # Add width parameter
     ) -> "Image.Image":
         """
         Show the page with just this region highlighted temporarily.
@@ -782,6 +808,7 @@ class Region(DirectionalMixin, ClassificationMixin, ExtractionMixin):
             legend_position: Position of the legend
             color: Color to highlight this region (default: blue)
             label: Optional label for this region in the legend
+            width: Optional width for the output image in pixels
 
         Returns:
             PIL Image of the page with only this region highlighted
@@ -812,6 +839,7 @@ class Region(DirectionalMixin, ClassificationMixin, ExtractionMixin):
             page_index=self._page.index,
             temporary_highlights=[temp_highlight_data],
             scale=scale,
+            width=width,  # Pass the width parameter
             labels=labels,
             legend_position=legend_position,
         )
@@ -871,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"]:
@@ -1258,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:
@@ -1333,6 +1586,7 @@ class Region(DirectionalMixin, ClassificationMixin, ExtractionMixin):
         self,
         *,
         text: str,
+        contains: str = "all",
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -1344,6 +1598,7 @@ class Region(DirectionalMixin, ClassificationMixin, ExtractionMixin):
         self,
         selector: str,
         *,
+        contains: str = "all",
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -1355,6 +1610,7 @@ class Region(DirectionalMixin, ClassificationMixin, ExtractionMixin):
         selector: Optional[str] = None,  # Now optional
         *,
         text: Optional[str] = None,  # New text parameter
+        contains: str = "all",  # New parameter for containment behavior
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -1368,6 +1624,9 @@ class Region(DirectionalMixin, ClassificationMixin, ExtractionMixin):
         Args:
             selector: CSS-like selector string.
             text: Text content to search for (equivalent to 'text:contains(...)').
+            contains: How to determine if elements are inside: 'all' (fully inside),
+                     'any' (any overlap), or 'center' (center point inside).
+                     (default: "all")
             apply_exclusions: Whether to exclude elements in exclusion regions (default: True).
             regex: Whether to use regex for text search (`selector` or `text`) (default: False).
             case: Whether to do case-sensitive text search (`selector` or `text`) (default: True).
@@ -1380,6 +1639,7 @@ class Region(DirectionalMixin, ClassificationMixin, ExtractionMixin):
         elements = self.find_all(
             selector=selector,
             text=text,
+            contains=contains,
             apply_exclusions=apply_exclusions,
             regex=regex,
             case=case,
@@ -1392,6 +1652,7 @@ class Region(DirectionalMixin, ClassificationMixin, ExtractionMixin):
         self,
         *,
         text: str,
+        contains: str = "all",
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -1403,6 +1664,7 @@ class Region(DirectionalMixin, ClassificationMixin, ExtractionMixin):
         self,
         selector: str,
         *,
+        contains: str = "all",
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -1414,6 +1676,7 @@ class Region(DirectionalMixin, ClassificationMixin, ExtractionMixin):
         selector: Optional[str] = None,  # Now optional
         *,
         text: Optional[str] = None,  # New text parameter
+        contains: str = "all",  # New parameter to control inside/overlap behavior
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -1427,6 +1690,9 @@ class Region(DirectionalMixin, ClassificationMixin, ExtractionMixin):
         Args:
             selector: CSS-like selector string.
             text: Text content to search for (equivalent to 'text:contains(...)').
+            contains: How to determine if elements are inside: 'all' (fully inside),
+                     'any' (any overlap), or 'center' (center point inside).
+                     (default: "all")
             apply_exclusions: Whether to exclude elements in exclusion regions (default: True).
             regex: Whether to use regex for text search (`selector` or `text`) (default: False).
             case: Whether to do case-sensitive text search (`selector` or `text`) (default: True).
@@ -1442,6 +1708,10 @@ class Region(DirectionalMixin, ClassificationMixin, ExtractionMixin):
         if selector is None and text is None:
             raise ValueError("Provide either 'selector' or 'text'.")
 
+        # Validate contains parameter
+        if contains not in ["all", "any", "center"]:
+            raise ValueError(f"Invalid contains value: {contains}. Must be 'all', 'any', or 'center'")
+
         # Construct selector if 'text' is provided
         effective_selector = ""
         if text is not None:
@@ -1481,22 +1751,34 @@ class Region(DirectionalMixin, ClassificationMixin, ExtractionMixin):
             # Let the page handle its exclusion logic if needed
             potential_elements = self.page.find_all(
                 selector=effective_selector,
-                apply_exclusions=False,  # Apply exclusions LATER based on region bbox
+                apply_exclusions=apply_exclusions,
                 regex=regex,
                 case=case,
                 **kwargs,
             )
 
-            # Filter these elements to those strictly within the region's bounds
+            # Filter these elements based on the specified containment method
             region_bbox = self.bbox
-            matching_elements = [
-                el
-                for el in potential_elements
-                if el.x0 >= region_bbox[0]
-                and el.top >= region_bbox[1]
-                and el.x1 <= region_bbox[2]
-                and el.bottom <= region_bbox[3]
-            ]
+            matching_elements = []
+            
+            if contains == "all":  # Fully inside (strict)
+                matching_elements = [
+                    el for el in potential_elements
+                    if el.x0 >= region_bbox[0]
+                    and el.top >= region_bbox[1]
+                    and el.x1 <= region_bbox[2]
+                    and el.bottom <= region_bbox[3]
+                ]
+            elif contains == "any":  # Any overlap
+                matching_elements = [
+                    el for el in potential_elements
+                    if self.intersects(el)
+                ]
+            elif contains == "center":  # Center point inside
+                matching_elements = [
+                    el for el in potential_elements
+                    if self.is_element_center_inside(el)
+                ]
 
             return ElementCollection(matching_elements)
 
@@ -1745,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.
 
@@ -1865,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):
         """
@@ -1988,7 +2270,7 @@ class Region(DirectionalMixin, ClassificationMixin, ExtractionMixin):
             from natural_pdf.qa.document_qa import get_qa_engine
         except ImportError:
             logger.error(
-                "Question answering requires optional dependencies. Install with `pip install natural-pdf[qa]`"
+                "Question answering requires optional dependencies. Install with `pip install natural-pdf[core-ml]`"
             )
             return {
                 "answer": None,
@@ -2381,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