natural-pdf 0.1.16__py3-none-any.whl → 0.1.17__py3-none-any.whl

natural_pdf/core/page.py

@@ -61,6 +61,7 @@ from natural_pdf.classification.manager import ClassificationManager  # For type
 # # --- Classification Imports --- #
 from natural_pdf.classification.mixin import ClassificationMixin  # Import classification mixin
 from natural_pdf.core.element_manager import ElementManager
+from natural_pdf.describe.mixin import DescribeMixin  # Import describe mixin
 from natural_pdf.elements.base import Element  # Import base element
 from natural_pdf.elements.text import TextElement
 from natural_pdf.extraction.mixin import ExtractionMixin  # Import extraction mixin
@@ -92,7 +93,7 @@ except ImportError:
 logger = logging.getLogger(__name__)
 
 
-class Page(ClassificationMixin, ExtractionMixin, ShapeDetectionMixin):
+class Page(ClassificationMixin, ExtractionMixin, ShapeDetectionMixin, DescribeMixin):
     """
     Enhanced Page wrapper built on top of pdfplumber.Page.
 

natural_pdf/describe/__init__.py

@@ -0,0 +1,21 @@
+"""
+Describe functionality for natural-pdf.
+
+Provides summary and inspection methods for pages, collections, and regions.
+"""
+
+from .base import describe_page, describe_collection, inspect_collection, describe_region, describe_element
+from .summary import ElementSummary, InspectionSummary
+from .mixin import DescribeMixin, InspectMixin
+
+__all__ = [
+    'describe_page',
+    'describe_collection', 
+    'inspect_collection',
+    'describe_region',
+    'describe_element',
+    'ElementSummary',
+    'InspectionSummary',
+    'DescribeMixin',
+    'InspectMixin'
+] 

natural_pdf/describe/base.py

@@ -0,0 +1,457 @@
+"""
+Main describe functions for pages, collections, and regions.
+"""
+
+import logging
+from collections import Counter
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+
+from .elements import (
+    describe_line_elements,
+    describe_rect_elements,
+    describe_region_elements,
+    describe_text_elements,
+)
+from .summary import ElementSummary, InspectionSummary
+
+if TYPE_CHECKING:
+    from natural_pdf.core.page import Page
+    from natural_pdf.elements.base import Element
+    from natural_pdf.elements.collections import ElementCollection
+    from natural_pdf.elements.region import Region
+
+logger = logging.getLogger(__name__)
+
+
+def describe_page(page: "Page") -> ElementSummary:
+    """
+    Describe what's on a page with high-level summary.
+    
+    Args:
+        page: Page to describe
+        
+    Returns:
+        ElementSummary with page overview
+    """
+    data = {}
+    
+    # Get all elements
+    all_elements = page.get_elements()
+    
+    if not all_elements:
+        data["message"] = "No elements found on page"
+        return ElementSummary(data, f"Page {page.number} Summary")
+    
+    # Element counts by type (exclude chars - too granular)
+    type_counts = Counter()
+    for element in all_elements:
+        element_type = getattr(element, 'type', 'unknown')
+        if element_type != 'char':  # Skip character elements
+            type_counts[element_type] += 1
+    
+    # Format element counts as dictionary for proper list formatting
+    element_summary = {}
+    for element_type, count in type_counts.most_common():
+        type_display = element_type.replace('_', ' ').title()
+        if element_type == 'word':
+            # Add source breakdown for text
+            text_elements = [e for e in all_elements if getattr(e, 'type', '') == 'word']
+            sources = Counter()
+            for elem in text_elements:
+                source = getattr(elem, 'source', 'unknown')
+                sources[source] += 1
+            
+            if len(sources) > 1:
+                source_parts = []
+                for source, source_count in sources.most_common():
+                    source_parts.append(f"{source_count} {source}")
+                element_summary["text"] = f"{count} elements ({', '.join(source_parts)})"
+            else:
+                element_summary["text"] = f"{count} elements"
+        else:
+            element_summary[element_type] = f"{count} elements"
+    
+    data["elements"] = element_summary
+    
+    # Text analysis if we have text elements (exclude chars - too granular)
+    text_elements = [e for e in all_elements if getattr(e, 'type', '') == 'word']
+    if text_elements:
+        text_analysis = describe_text_elements(text_elements)
+        if text_analysis and 'message' not in text_analysis:
+            data["text_analysis"] = text_analysis
+    
+    return ElementSummary(data, f"Page {page.number} Summary")
+
+
+def describe_collection(collection: "ElementCollection") -> ElementSummary:
+    """
+    Describe an element collection with type-specific analysis.
+    
+    Args:
+        collection: ElementCollection to describe
+        
+    Returns:
+        ElementSummary with collection analysis
+    """
+    elements = list(collection)
+    
+    if not elements:
+        data = {"message": "Empty collection"}
+        return ElementSummary(data, "Collection Summary")
+    
+    data = {}
+    
+    # Group elements by type
+    by_type = {}
+    for element in elements:
+        element_type = getattr(element, 'type', 'unknown')
+        by_type.setdefault(element_type, []).append(element)
+    
+    # Overall summary for mixed collections (exclude chars from overview)
+    if len(by_type) > 1:
+        type_counts = {k: len(v) for k, v in by_type.items() if k != 'char'}
+        total = sum(type_counts.values())
+        
+        summary_parts = []
+        for element_type, count in sorted(type_counts.items(), key=lambda x: x[1], reverse=True):
+            type_display = element_type.replace('_', ' ').title()
+            summary_parts.append(f"**{type_display}**: {count}")
+        
+        if summary_parts:  # Only add overview if we have non-char elements
+            data["overview"] = {
+                "total_elements": total,
+                "type_breakdown": summary_parts
+            }
+    
+    # Type-specific analysis (exclude chars - too granular)
+    for element_type, type_elements in by_type.items():
+        if element_type == 'char':
+            # Skip character elements - too granular for useful analysis
+            continue
+        elif element_type == 'word':
+            analysis = describe_text_elements(type_elements)
+        elif element_type == 'rect':
+            analysis = describe_rect_elements(type_elements)
+        elif element_type == 'line':
+            analysis = describe_line_elements(type_elements)
+        elif element_type == 'region':
+            analysis = describe_region_elements(type_elements)
+        else:
+            analysis = {"count": len(type_elements)}
+        
+        if analysis and 'message' not in analysis:
+            section_name = element_type.replace('_', ' ').title()
+            if len(by_type) == 1:
+                # Single type collection - flatten the structure
+                data.update(analysis)
+            else:
+                # Mixed collection - keep sections separate
+                data[section_name] = analysis
+    
+    # Count non-char elements for title
+    non_char_count = len([e for e in elements if getattr(e, 'type', 'unknown') != 'char'])
+    title = f"Collection Summary ({non_char_count} elements)"
+    return ElementSummary(data, title)
+
+
+def describe_region(region: "Region") -> ElementSummary:
+    """
+    Describe a region with its properties and contents.
+    
+    Args:
+        region: Region to describe
+        
+    Returns:
+        ElementSummary with region analysis
+    """
+    data = {}
+    
+    # Region info
+    region_info = {
+        "page": region.page.number,
+        "dimensions": f"{region.width:.0f}×{region.height:.0f} pts",
+        "area": f"{region.width * region.height:.0f} sq pts",
+        "position": f"({region.x0:.0f}, {region.top:.0f}) to ({region.x1:.0f}, {region.bottom:.0f})"
+    }
+    
+    # Add metadata if available
+    if hasattr(region, 'metadata') and region.metadata:
+        region_info["metadata"] = region.metadata
+    
+    data["region_info"] = region_info
+    
+    # Content analysis
+    content_elements = region.find_all("*")
+    if content_elements:
+        content_analysis = describe_collection(content_elements)
+        # Extract the data and add as "content" section
+        data["content"] = content_analysis.to_dict()
+    else:
+        data["content"] = {"message": "No elements found in region"}
+    
+    return ElementSummary(data, "Region Summary")
+
+
+def inspect_collection(collection: "ElementCollection", limit: int = 30) -> InspectionSummary:
+    """
+    Inspect elements in a collection with detailed tabular view.
+    
+    Args:
+        collection: ElementCollection to inspect
+        limit: Maximum elements per type to show (default: 30)
+        
+    Returns:
+        InspectionSummary with element tables
+    """
+    elements = list(collection)
+    
+    if not elements:
+        data = {"message": "Empty collection"}
+        return InspectionSummary(data, "Collection Inspection")
+    
+    data = {}
+    
+    # Check if multi-page
+    pages = set()
+    for element in elements:
+        if hasattr(element, 'page') and hasattr(element.page, 'number'):
+            pages.add(element.page.number)
+    show_page_column = len(pages) > 1
+    
+    # Group by type
+    by_type = {}
+    for element in elements:
+        element_type = getattr(element, 'type', 'unknown')
+        by_type.setdefault(element_type, []).append(element)
+    
+    # Create tables for each type (exclude chars - too granular)
+    for element_type, type_elements in by_type.items():
+        if element_type == 'char':
+            # Skip character elements - too granular for useful inspection
+            continue
+            
+        # Limit elements shown
+        display_elements = type_elements[:limit]
+        
+        # Get appropriate columns for this type
+        columns = _get_columns_for_type(element_type, show_page_column)
+        
+        # Extract data for each element
+        element_data = []
+        for element in display_elements:
+            row = {}
+            for col in columns:
+                value = _extract_element_value(element, col)
+                row[col] = value
+            element_data.append(row)
+        
+        # Create section
+        section_name = f"{element_type}_elements"
+        section_data = {
+            "elements": element_data,
+            "columns": columns
+        }
+        
+        # Add note if truncated
+        if len(type_elements) > limit:
+            section_data["note"] = f"Showing {limit} of {len(type_elements)} elements (pass limit= to see more)"
+        
+        data[section_name] = section_data
+    
+    # Count non-char elements for title
+    non_char_count = len([e for e in elements if getattr(e, 'type', 'unknown') != 'char'])
+    title = f"Collection Inspection ({non_char_count} elements)"
+    return InspectionSummary(data, title)
+
+
+def _get_columns_for_type(element_type: str, show_page_column: bool) -> List[str]:
+    """Get appropriate columns for element type."""
+    base_columns = ['x0', 'top', 'x1', 'bottom']
+    
+    if element_type == 'word':
+        columns = ['text'] + base_columns + ['font_family', 'size', 'bold', 'italic', 'source', 'confidence']
+        # Add color for text elements
+        columns.append('color')
+    elif element_type == 'rect':
+        columns = base_columns + ['width', 'height', 'stroke', 'fill', 'stroke_width']
+    elif element_type == 'line':
+        columns = base_columns + ['width', 'is_horizontal', 'is_vertical']  # LineElement properties
+    elif element_type == 'region':
+        columns = base_columns + ['width', 'height', 'type']
+    else:
+        columns = base_columns + ['type']
+    
+    if show_page_column:
+        columns.append('page')
+    
+    return columns
+
+
+def _extract_element_value(element: "Element", column: str) -> Any:
+    """Extract value for a column from an element."""
+    try:
+        if column == 'text':
+            text = getattr(element, 'text', '')
+            if text and len(text) > 50:
+                return text[:50] + "..."
+            return text or ""
+        
+        elif column == 'page':
+            if hasattr(element, 'page') and hasattr(element.page, 'number'):
+                return element.page.number
+            return ""
+        
+        elif column == 'confidence':
+            confidence = getattr(element, 'confidence', None)
+            if confidence is not None and isinstance(confidence, (int, float)):
+                return f"{confidence:.2f}"
+            return ""
+        
+        elif column == 'font_family':
+            # Use the cleaner font_family property from TextElement
+            font_family = getattr(element, 'font_family', None)
+            if font_family:
+                return font_family
+            # Fallback to fontname
+            return getattr(element, 'fontname', '')
+        
+        elif column in ['bold', 'italic']:
+            value = getattr(element, column, False)
+            return value if isinstance(value, bool) else False
+        
+        elif column in ['stroke', 'fill', 'color']:
+            # For rectangles and text, these return color tuples
+            value = getattr(element, column, None)
+            if value and isinstance(value, (tuple, list)) and len(value) >= 3:
+                # Convert to hex color for display
+                try:
+                    r, g, b = [int(v * 255) if v <= 1 else int(v) for v in value[:3]]
+                    return f"#{r:02x}{g:02x}{b:02x}"
+                except:
+                    return str(value)
+            return ""
+        
+        elif column in ['x0', 'top', 'x1', 'bottom', 'width', 'height', 'size', 'stroke_width']:
+            value = getattr(element, column, 0)
+            if isinstance(value, (int, float)) and not isinstance(value, bool):
+                return int(round(value))
+            return 0
+        
+        elif column in ['is_horizontal', 'is_vertical']:
+            value = getattr(element, column, False)
+            return value if isinstance(value, bool) else False
+        
+        else:
+            # Generic attribute access
+            value = getattr(element, column, '')
+            if value is None:
+                return ""
+            return str(value)
+    
+    except Exception as e:
+        # Fallback for any unexpected errors
+        logger.warning(f"Error extracting {column} from element: {e}")
+        return ""
+
+
+def describe_element(element: "Element") -> "ElementSummary":
+    """
+    Describe an individual element with its properties and attributes.
+    
+    Args:
+        element: The element to describe
+        
+    Returns:
+        ElementSummary with formatted element properties
+    """
+    from natural_pdf.describe.summary import ElementSummary
+    
+    # Get basic element info
+    element_type = getattr(element, 'type', element.__class__.__name__)
+    
+    # Build the description data - use dict structure for proper list formatting
+    data = {
+        "info": {
+            "object_type": "element",
+            "element_type": element_type,
+            "class_name": element.__class__.__name__
+        }
+    }
+    
+    # Add geometric properties - use dict structure for proper list formatting
+    if hasattr(element, 'bbox'):
+        data["geometry"] = {
+            "position": f"({round(element.x0, 1)}, {round(element.top, 1)}, {round(element.x1, 1)}, {round(element.bottom, 1)})",
+            "size": f"({round(element.width, 1)}, {round(element.height, 1)})"
+        }
+    
+    # Add text content if available - use dict structure for proper list formatting
+    if hasattr(element, 'text') and element.text:
+        text = str(element.text).strip()
+        display_text = text[:50] + "..." if len(text) > 50 else text
+        data["content"] = {
+            "text": f"'{display_text}'",
+            "length": f"{len(text)} chars"
+        }
+    
+    # Add common text properties - use dict structure for proper list formatting
+    text_props = {}
+    for prop in ['font_family', 'size', 'bold', 'italic', 'source', 'confidence']:
+        if hasattr(element, prop):
+            value = getattr(element, prop)
+            if value is not None:
+                if prop == 'confidence' and isinstance(value, (int, float)):
+                    text_props[prop] = round(value, 3)
+                elif prop == 'size' and isinstance(value, (int, float)):
+                    text_props[prop] = round(value, 1)
+                elif prop in ['bold', 'italic']:
+                    text_props[prop] = value
+                else:
+                    text_props[prop] = value
+    
+    if text_props:
+        data["properties"] = text_props
+    
+    # Add color information - use dict structure for proper list formatting
+    color_info = {}
+    for prop in ['color', 'fill', 'stroke']:
+        if hasattr(element, prop):
+            value = getattr(element, prop)
+            if value is not None:
+                if isinstance(value, (tuple, list)) and len(value) >= 3:
+                    # Convert RGB to hex if it's a color tuple
+                    try:
+                        if all(isinstance(v, (int, float)) for v in value[:3]):
+                            r, g, b = [int(v * 255) if v <= 1 else int(v) for v in value[:3]]
+                            color_info[prop] = f"#{r:02x}{g:02x}{b:02x}"
+                        else:
+                            color_info[prop] = str(value)
+                    except:
+                        color_info[prop] = str(value)
+                else:
+                    color_info[prop] = str(value)
+    
+    if color_info:
+        data["colors"] = color_info
+    
+    # Add page information - use dict structure for proper list formatting
+    if hasattr(element, 'page') and element.page:
+        page_num = getattr(element.page, 'number', None)
+        if page_num is not None:
+            data["page"] = {"number": page_num}
+    
+    # Add polygon information if available - use dict structure for proper list formatting
+    if hasattr(element, 'has_polygon') and element.has_polygon:
+        if hasattr(element, 'polygon'):
+            polygon = element.polygon
+            if polygon and len(polygon) > 0:
+                data["shape"] = {"polygon_points": len(polygon)}
+    
+    # Create title
+    title = f"{element_type.title()} Element"
+    if hasattr(element, 'text') and element.text:
+        preview = str(element.text).strip()[:30]
+        if preview:
+            title += f": '{preview}'"
+    
+    return ElementSummary(data, title) 

natural_pdf/describe/elements.py

@@ -0,0 +1,411 @@
+"""
+Element-specific describe functions.
+"""
+
+import logging
+from collections import Counter
+from typing import TYPE_CHECKING, Any, Dict, List
+
+if TYPE_CHECKING:
+    from natural_pdf.elements.base import Element
+
+logger = logging.getLogger(__name__)
+
+
+def describe_text_elements(elements: List["Element"]) -> Dict[str, Any]:
+    """
+    Describe text elements with typography and OCR analysis.
+    
+    Args:
+        elements: List of text elements
+        
+    Returns:
+        Dictionary with text analysis sections
+    """
+    if not elements:
+        return {"message": "No text elements found"}
+    
+    result = {}
+    
+    # Source breakdown
+    sources = Counter()
+    ocr_elements = []
+    
+    for element in elements:
+        source = getattr(element, 'source', 'unknown')
+        sources[source] += 1
+        if source == 'ocr':
+            ocr_elements.append(element)
+    
+    if len(sources) > 1:
+        result['sources'] = dict(sources)
+    
+    # Typography analysis
+    typography = _analyze_typography(elements)
+    if typography:
+        result['typography'] = typography
+    
+    # OCR quality analysis
+    if ocr_elements:
+        ocr_quality = _analyze_ocr_quality(ocr_elements)
+        if ocr_quality:
+            result['ocr_quality'] = ocr_quality
+    
+    return result
+
+
+def describe_rect_elements(elements: List["Element"]) -> Dict[str, Any]:
+    """
+    Describe rectangle elements with size and style analysis.
+    
+    Args:
+        elements: List of rectangle elements
+        
+    Returns:
+        Dictionary with rectangle analysis
+    """
+    if not elements:
+        return {"message": "No rectangle elements found"}
+    
+    result = {}
+    
+    # Size analysis
+    sizes = []
+    stroke_count = 0
+    fill_count = 0
+    colors = Counter()
+    stroke_widths = []
+    
+    for element in elements:
+        # Size
+        width = getattr(element, 'width', 0)
+        height = getattr(element, 'height', 0)
+        if width and height:
+            sizes.append((width, height))
+        
+        # Style properties - use RectangleElement properties
+        stroke = getattr(element, 'stroke', None)
+        if stroke and stroke != (0, 0, 0):  # Check if stroke color exists and isn't black
+            stroke_count += 1
+        fill = getattr(element, 'fill', None)
+        if fill and fill != (0, 0, 0):  # Check if fill color exists and isn't black
+            fill_count += 1
+        
+        # Stroke width
+        stroke_width = getattr(element, 'stroke_width', 0)
+        if stroke_width > 0:
+            stroke_widths.append(stroke_width)
+            
+        # Color - use the element's stroke/fill properties
+        color = stroke or fill
+        if color:
+            if isinstance(color, (tuple, list)):
+                if color == (0, 0, 0) or color == (0.0, 0.0, 0.0):
+                    colors['black'] += 1
+                elif color == (1, 1, 1) or color == (1.0, 1.0, 1.0):
+                    colors['white'] += 1
+                else:
+                    colors[str(color)] += 1
+            else:
+                colors[str(color)] += 1
+    
+    # Size statistics
+    if sizes:
+        widths = [s[0] for s in sizes]
+        heights = [s[1] for s in sizes]
+        result['size_stats'] = {
+            'width_range': f"{min(widths):.0f}-{max(widths):.0f}",
+            'height_range': f"{min(heights):.0f}-{max(heights):.0f}",
+            'avg_area': f"{sum(w*h for w,h in sizes)/len(sizes):.0f} sq pts"
+        }
+    
+    # Style breakdown
+    style_info = {}
+    if stroke_count:
+        style_info['stroke'] = stroke_count
+    if fill_count:
+        style_info['fill'] = fill_count
+    if stroke_widths:
+        stroke_width_counts = Counter(stroke_widths)
+        # Convert float keys to strings to avoid formatting issues
+        stroke_width_dict = {str(k): v for k, v in stroke_width_counts.most_common()}
+        style_info['stroke_widths'] = stroke_width_dict
+    if colors:
+        style_info['colors'] = dict(colors.most_common(5))
+    
+    if style_info:
+        result['styles'] = style_info
+    
+    return result
+
+
+def describe_line_elements(elements: List["Element"]) -> Dict[str, Any]:
+    """
+    Describe line elements with length and style analysis.
+    
+    Args:
+        elements: List of line elements
+        
+    Returns:
+        Dictionary with line analysis
+    """
+    if not elements:
+        return {"message": "No line elements found"}
+    
+    result = {}
+    
+    lengths = []
+    widths = []
+    colors = Counter()
+    
+    for element in elements:
+        # Calculate length
+        x0 = getattr(element, 'x0', 0)
+        y0 = getattr(element, 'top', 0)
+        x1 = getattr(element, 'x1', 0)
+        y1 = getattr(element, 'bottom', 0)
+        
+        length = ((x1 - x0) ** 2 + (y1 - y0) ** 2) ** 0.5
+        if length > 0:
+            lengths.append(length)
+        
+        # Line width - use the element's width property
+        width = getattr(element, 'width', 0)  # LineElement has a width property
+        if width:
+            widths.append(width)
+        
+        # Color - use the element's color property
+        color = getattr(element, 'color', None)  # LineElement has a color property
+        if color:
+            if isinstance(color, (tuple, list)):
+                if color == (0, 0, 0) or color == (0.0, 0.0, 0.0):
+                    colors['black'] += 1
+                else:
+                    colors[str(color)] += 1
+            else:
+                colors[str(color)] += 1
+    
+    # Length statistics
+    if lengths:
+        result['length_stats'] = {
+            'min': f"{min(lengths):.0f}",
+            'max': f"{max(lengths):.0f}",
+            'avg': f"{sum(lengths)/len(lengths):.0f}"
+        }
+    
+    # Width statistics
+    if widths:
+        width_counts = Counter(widths)
+        # Convert float keys to strings to avoid formatting issues
+        result['line_widths'] = {str(k): v for k, v in width_counts.most_common()}
+    
+    # Orientation analysis
+    horizontal_count = sum(1 for el in elements if getattr(el, 'is_horizontal', False))
+    vertical_count = sum(1 for el in elements if getattr(el, 'is_vertical', False))
+    diagonal_count = len(elements) - horizontal_count - vertical_count
+    
+    if horizontal_count or vertical_count or diagonal_count:
+        orientation_info = {}
+        if horizontal_count:
+            orientation_info['horizontal'] = horizontal_count
+        if vertical_count:
+            orientation_info['vertical'] = vertical_count
+        if diagonal_count:
+            orientation_info['diagonal'] = diagonal_count
+        result['orientations'] = orientation_info
+    
+    # Colors
+    if colors:
+        result['colors'] = dict(colors.most_common())
+    
+    return result
+
+
+def describe_region_elements(elements: List["Element"]) -> Dict[str, Any]:
+    """
+    Describe region elements with type and metadata analysis.
+    
+    Args:
+        elements: List of region elements
+        
+    Returns:
+        Dictionary with region analysis
+    """
+    if not elements:
+        return {"message": "No region elements found"}
+    
+    result = {}
+    
+    # Region types
+    types = Counter()
+    sizes = []
+    metadata_keys = set()
+    
+    for element in elements:
+        # Type
+        region_type = getattr(element, 'type', 'unknown')
+        types[region_type] += 1
+        
+        # Size
+        width = getattr(element, 'width', 0)
+        height = getattr(element, 'height', 0)
+        if width and height:
+            sizes.append(width * height)
+        
+        # Metadata keys
+        if hasattr(element, 'metadata') and element.metadata:
+            metadata_keys.update(element.metadata.keys())
+    
+    # Type breakdown
+    if types:
+        result['types'] = dict(types.most_common())
+    
+    # Size statistics
+    if sizes:
+        result['size_stats'] = {
+            'min_area': f"{min(sizes):.0f} sq pts",
+            'max_area': f"{max(sizes):.0f} sq pts",
+            'avg_area': f"{sum(sizes)/len(sizes):.0f} sq pts"
+        }
+    
+    # Metadata
+    if metadata_keys:
+        result['metadata_keys'] = sorted(list(metadata_keys))
+    
+    return result
+
+
+def _analyze_typography(elements: List["Element"]) -> Dict[str, Any]:
+    """Analyze typography patterns in text elements."""
+    fonts = Counter()
+    sizes = Counter()
+    styles = {'bold': 0, 'italic': 0}
+    colors = Counter()
+    
+    for element in elements:
+        # Font family - use TextElement's font_family property for cleaner names
+        font_family = getattr(element, 'font_family', None)
+        fontname = getattr(element, 'fontname', 'Unknown')
+        display_font = font_family if font_family and font_family != fontname else fontname
+        if display_font:
+            fonts[display_font] += 1
+        
+        # Size
+        size = getattr(element, 'size', None)
+        if size:
+            # Round to nearest 0.5
+            rounded_size = round(size * 2) / 2
+            sizes[f"{rounded_size}pt"] += 1
+        
+        # Styles
+        if getattr(element, 'bold', False):
+            styles['bold'] += 1
+        if getattr(element, 'italic', False):
+            styles['italic'] += 1
+        
+        # Color - use TextElement's color property
+        color = getattr(element, 'color', None)
+        if color:
+            if isinstance(color, (tuple, list)):
+                if color == (0, 0, 0) or color == (0.0, 0.0, 0.0):
+                    colors['black'] += 1
+                elif color == (1, 1, 1) or color == (1.0, 1.0, 1.0):
+                    colors['white'] += 1
+                else:
+                    colors['other'] += 1
+            else:
+                colors[str(color)] += 1
+    
+    result = {}
+    
+    # Fonts
+    if fonts:
+        result['fonts'] = dict(fonts.most_common(10))
+    
+    # Sizes (as horizontal table)
+    if sizes:
+        result['sizes'] = dict(sizes.most_common())
+    
+    # Styles
+    style_list = []
+    if styles['bold']:
+        style_list.append(f"{styles['bold']} bold")
+    if styles['italic']:
+        style_list.append(f"{styles['italic']} italic")
+    if style_list:
+        result['styles'] = ", ".join(style_list)
+    
+    # Colors
+    if colors and len(colors) > 1:  # Only show if there are multiple colors
+        result['colors'] = dict(colors.most_common())
+    
+    return result
+
+
+def _analyze_ocr_quality(elements: List["Element"]) -> Dict[str, Any]:
+    """Analyze OCR quality metrics."""
+    confidences = []
+    
+    for element in elements:
+        confidence = getattr(element, 'confidence', None)
+        if confidence is not None:
+            confidences.append(confidence)
+    
+    if not confidences:
+        return {}
+    
+    result = {}
+    
+    # Basic stats
+    result['confidence_stats'] = {
+        'mean': f"{sum(confidences)/len(confidences):.2f}",
+        'min': f"{min(confidences):.2f}",
+        'max': f"{max(confidences):.2f}"
+    }
+    
+    # Threshold analysis with ASCII bars
+    thresholds = [
+        ('99%+', 0.99),
+        ('95%+', 0.95), 
+        ('90%+', 0.90),
+    ]
+    
+    element_count = len(elements)
+    threshold_bars = {}
+    
+    for label, threshold in thresholds:
+        count = sum(1 for c in confidences if c >= threshold)
+        percentage = count / element_count
+        
+        # Create ASCII bar (40 characters wide)
+        filled_chars = int(percentage * 40)
+        empty_chars = 40 - filled_chars
+        bar = '█' * filled_chars + '░' * empty_chars
+        
+        # Format: "95%+ (32/43) 74%: `████████████████████████████████░░░░░░░░`"
+        threshold_bars[f"{label} ({count}/{element_count}) {percentage:.0%}"] = f"`{bar}`"
+    
+    result['quality_distribution'] = threshold_bars
+    
+    # Show lowest quality items
+    element_confidences = []
+    for element in elements:
+        confidence = getattr(element, 'confidence', None)
+        if confidence is not None:
+            # Get text content for display
+            text = getattr(element, 'text', '').strip()
+            if text:
+                # Truncate long text
+                display_text = text[:50] + "..." if len(text) > 50 else text
+                element_confidences.append((confidence, display_text))
+    
+    if element_confidences:
+        # Sort by confidence (lowest first) and take bottom 10
+        lowest_quality = sorted(element_confidences, key=lambda x: x[0])[:10]
+        if lowest_quality:
+            lowest_items = {}
+            for i, (confidence, text) in enumerate(lowest_quality, 1):
+                lowest_items[f"#{i}"] = f"**{confidence:.2f}**: {text}"
+            result['lowest_scoring'] = lowest_items
+    
+    return result 

natural_pdf/describe/mixin.py

@@ -0,0 +1,84 @@
+"""
+Mixin for describe functionality.
+"""
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from natural_pdf.describe.summary import ElementSummary, InspectionSummary
+
+
+class DescribeMixin:
+    """
+    Mixin providing describe functionality for pages, collections, and regions.
+    
+    Classes that inherit from this mixin get:
+    - .describe() method for high-level summaries
+    - .inspect() method for detailed tabular views (collections only)
+    """
+    
+    def describe(self) -> "ElementSummary":
+        """
+        Describe this object with type-specific analysis.
+        
+        Returns:
+            ElementSummary with analysis appropriate for the object type
+        """
+        from natural_pdf.describe import describe_page, describe_collection, describe_region, describe_element
+        
+        # Determine the appropriate describe function based on class type
+        class_name = self.__class__.__name__
+        
+        if class_name == 'Page':
+            return describe_page(self)
+        elif class_name == 'ElementCollection':
+            return describe_collection(self)
+        elif class_name == 'Region':
+            return describe_region(self)
+        else:
+            # Check if it's an individual element (inherits from Element base class)
+            from natural_pdf.elements.base import Element
+            if isinstance(self, Element):
+                return describe_element(self)
+            
+            # Fallback - try to determine based on available methods/attributes
+            if hasattr(self, 'get_elements') and hasattr(self, 'width') and hasattr(self, 'height'):
+                # Looks like a page or region
+                if hasattr(self, 'number'):
+                    return describe_page(self)  # Page
+                else:
+                    return describe_region(self)  # Region
+            elif hasattr(self, '__iter__') and hasattr(self, '__len__'):
+                # Looks like a collection
+                return describe_collection(self)
+            else:
+                # Unknown type - create a basic summary
+                from natural_pdf.describe.summary import ElementSummary
+                data = {
+                    "object_type": class_name,
+                    "message": f"Describe not fully implemented for {class_name}"
+                }
+                return ElementSummary(data, f"{class_name} Summary")
+
+
+class InspectMixin:
+    """
+    Mixin providing inspect functionality for collections.
+    
+    Classes that inherit from this mixin get:
+    - .inspect() method for detailed tabular element views
+    """
+    
+    def inspect(self, limit: int = 30) -> "InspectionSummary":
+        """
+        Inspect elements with detailed tabular view.
+        
+        Args:
+            limit: Maximum elements per type to show (default: 30)
+            
+        Returns:
+            InspectionSummary with element tables showing coordinates,
+            properties, and other details for each element
+        """
+        from natural_pdf.describe import inspect_collection
+        return inspect_collection(self, limit=limit) 

natural_pdf/describe/summary.py

@@ -0,0 +1,186 @@
+"""
+Summary objects for describe functionality.
+"""
+
+from typing import Any, Dict, List, Union
+
+
+class ElementSummary:
+    """
+    Container for element summary data with markdown rendering.
+    
+    Automatically renders as markdown in Jupyter notebooks and provides
+    access to underlying data as dictionaries.
+    """
+    
+    def __init__(self, data: Dict[str, Any], title: str = "Summary"):
+        """
+        Initialize summary with data and optional title.
+        
+        Args:
+            data: Dictionary containing summary sections
+            title: Title for the summary display
+        """
+        self.data = data
+        self.title = title
+    
+    def __str__(self) -> str:
+        """String representation as markdown."""
+        return self._to_markdown()
+    
+    def __repr__(self) -> str:
+        """Repr as markdown for better display."""
+        return self._to_markdown()
+    
+    def _repr_markdown_(self) -> str:
+        """Jupyter notebook markdown rendering."""
+        return self._to_markdown()
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Return underlying data as dictionary."""
+        return self.data.copy()
+    
+    def _to_markdown(self) -> str:
+        """Convert data to markdown format."""
+        lines = [f"## {self.title}", ""]
+        
+        for section_name, section_data in self.data.items():
+            lines.extend(self._format_section(section_name, section_data))
+            lines.append("")  # Empty line between sections
+        
+        return "\n".join(lines).rstrip()
+    
+    def _format_section(self, name: str, data: Any) -> List[str]:
+        """Format a single section as markdown."""
+        # Use bold text instead of headers for more compact display
+        section_title = name.replace('_', ' ').title()
+        
+        if isinstance(data, dict):
+            lines = [f"**{section_title}**:"]
+            lines.extend(self._format_dict(data, indent="  "))
+        elif isinstance(data, list):
+            lines = [f"**{section_title}**: {', '.join(str(item) for item in data)}"]
+        else:
+            lines = [f"**{section_title}**: {data}"]
+        
+        return lines
+    
+    def _format_dict(self, data: Dict[str, Any], indent: str = "") -> List[str]:
+        """Format dictionary as markdown list."""
+        lines = []
+        
+        for key, value in data.items():
+            key_display = key.replace('_', ' ')
+            
+            if isinstance(value, dict):
+                # Nested dict - always format as list items
+                lines.append(f"{indent}- **{key_display}**:")
+                for subkey, subvalue in value.items():
+                    subkey_display = subkey.replace('_', ' ')
+                    if isinstance(subvalue, dict):
+                        # Another level of nesting
+                        lines.append(f"{indent}  - **{subkey_display}**:")
+                        for subsubkey, subsubvalue in subvalue.items():
+                            subsubkey_display = subsubkey.replace('_', ' ')
+                            lines.append(f"{indent}    - {subsubkey_display}: {subsubvalue}")
+                    else:
+                        lines.append(f"{indent}  - {subkey_display}: {subvalue}")
+            elif isinstance(value, list):
+                if len(value) <= 5:
+                    value_str = ", ".join(str(v) for v in value)
+                    lines.append(f"{indent}- **{key_display}**: {value_str}")
+                else:
+                    lines.append(f"{indent}- **{key_display}**: {len(value)} items")
+            else:
+                lines.append(f"{indent}- **{key_display}**: {value}")
+        
+        return lines
+    
+    def _format_list(self, data: List[Any]) -> List[str]:
+        """Format list as markdown."""
+        lines = []
+        for item in data:
+            if isinstance(item, dict):
+                # Could be table rows
+                lines.append(f"- {item}")
+            else:
+                lines.append(f"- {item}")
+        return lines
+    
+
+    
+    def _format_horizontal_table(self, title: str, data: Dict[str, Any]) -> List[str]:
+        """Format dict as horizontal table."""
+        headers = list(data.keys())
+        values = list(data.values())
+        
+        # Create table
+        header_row = "| " + " | ".join(headers) + " |"
+        separator = "|" + "|".join("------" for _ in headers) + "|"
+        value_row = "| " + " | ".join(str(v) for v in values) + " |"
+        
+        return [
+            f"- **{title}**:",
+            "",
+            header_row,
+            separator, 
+            value_row,
+            ""
+        ]
+
+
+class InspectionSummary(ElementSummary):
+    """
+    Summary for element inspection with tabular data.
+    """
+    
+    def _format_section(self, name: str, data: Any) -> List[str]:
+        """Format inspection section with element tables."""
+        section_title = name.replace('_', ' ').title()
+        
+        if isinstance(data, dict) and 'elements' in data:
+            # This is an element table section - use ### header for inspect
+            elements = data['elements']
+            lines = [f"### {section_title}"]
+            if elements:
+                lines.extend(self._format_element_table(elements, data.get('columns', [])))
+                # Add note if truncated
+                if 'note' in data:
+                    lines.append(f"_{data['note']}_")
+            else:
+                lines.append("No elements found.")
+        else:
+            # Regular section formatting
+            lines = [f"**{section_title}**: {data}"]
+        
+        return lines
+    
+    def _format_element_table(self, elements: List[Dict[str, Any]], columns: List[str]) -> List[str]:
+        """Format elements as markdown table."""
+        if not elements or not columns:
+            return ["No elements to display."]
+        
+        lines = [""]  # Empty line before table
+        
+        # Table header
+        header_row = "| " + " | ".join(columns) + " |"
+        separator = "|" + "|".join("------" for _ in columns) + "|"
+        lines.extend([header_row, separator])
+        
+        # Table rows
+        for element in elements:
+            row_values = []
+            for col in columns:
+                value = element.get(col, "")
+                if value is None:
+                    value = ""
+                elif isinstance(value, float):
+                    value = str(int(round(value)))
+                elif isinstance(value, str) and len(value) > 50:
+                    value = value[:50] + "..."
+                row_values.append(str(value))
+            
+            row = "| " + " | ".join(row_values) + " |"
+            lines.append(row)
+        
+        return lines 

natural_pdf/elements/base.py

@@ -8,6 +8,7 @@ from PIL import Image
 
 # Import selector parsing functions
 from natural_pdf.selectors.parser import parse_selector, selector_to_filter_func
+from natural_pdf.describe.mixin import DescribeMixin
 
 if TYPE_CHECKING:
     from natural_pdf.core.page import Page
@@ -412,7 +413,7 @@ class DirectionalMixin:
         return new_region
 
 
-class Element(DirectionalMixin):
+class Element(DirectionalMixin, DescribeMixin):
     """
     Base class for all PDF elements.
 

natural_pdf/elements/collections.py

@@ -30,6 +30,7 @@ from tqdm.auto import tqdm
 from natural_pdf.analyzers.shape_detection_mixin import ShapeDetectionMixin
 from natural_pdf.classification.manager import ClassificationManager
 from natural_pdf.classification.mixin import ClassificationMixin
+from natural_pdf.describe.mixin import DescribeMixin, InspectMixin
 from natural_pdf.collections.mixins import ApplyMixin, DirectionalCollectionMixin
 from natural_pdf.core.pdf import PDF
 from natural_pdf.elements.base import Element
@@ -71,7 +72,14 @@ P = TypeVar("P", bound="Page")
 
 
 class ElementCollection(
-    Generic[T], ApplyMixin, ExportMixin, DirectionalCollectionMixin, MutableSequence
+    Generic[T],
+    ApplyMixin,
+    ExportMixin,
+    ClassificationMixin,
+    DirectionalCollectionMixin,
+    DescribeMixin,
+    InspectMixin,
+    MutableSequence,
 ):
     """
     Collection of PDF elements with batch operations.
@@ -1795,6 +1803,8 @@ class ElementCollection(
         )
 
 
+
+
 class PageCollection(Generic[P], ApplyMixin, ShapeDetectionMixin):
     """
     Represents a collection of Page objects, often from a single PDF document.

natural_pdf/elements/region.py

@@ -15,6 +15,7 @@ from natural_pdf.classification.manager import ClassificationManager  # Keep for
 
 # --- Classification Imports --- #
 from natural_pdf.classification.mixin import ClassificationMixin
+from natural_pdf.describe.mixin import DescribeMixin
 from natural_pdf.elements.base import DirectionalMixin
 from natural_pdf.elements.text import TextElement  # ADDED IMPORT
 from natural_pdf.extraction.mixin import ExtractionMixin  # Import extraction mixin
@@ -49,7 +50,7 @@ except ImportError:
 logger = logging.getLogger(__name__)
 
 
-class Region(DirectionalMixin, ClassificationMixin, ExtractionMixin, ShapeDetectionMixin):
+class Region(DirectionalMixin, ClassificationMixin, ExtractionMixin, ShapeDetectionMixin, DescribeMixin):
     """
     Represents a rectangular region on a page.
     """
@@ -2962,3 +2963,5 @@ class Region(DirectionalMixin, ClassificationMixin, ExtractionMixin, ShapeDetect
                 )
 
         return text_element
+
+

{natural_pdf-0.1.16.dist-info → natural_pdf-0.1.17.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: natural-pdf
-Version: 0.1.16
+Version: 0.1.17
 Summary: A more intuitive interface for working with PDFs
 Author-email: Jonathan Soma <jonathan.soma@gmail.com>
 License-Expression: MIT

{natural_pdf-0.1.16.dist-info → natural_pdf-0.1.17.dist-info}/RECORD

@@ -25,14 +25,19 @@ natural_pdf/collections/pdf_collection.py,sha256=HLlyakM--23ZOeHDPucoM6Tw3yUyMXm
 natural_pdf/core/__init__.py,sha256=QC8H4M3KbXwMFiQORZ0pdPlzx1Ix6oKKQSS7Ib2KEaA,38
 natural_pdf/core/element_manager.py,sha256=_UdXu51sLi6STzc8Pj4k8R721G3yJixXDLuRHn3hmr8,25731
 natural_pdf/core/highlighting_service.py,sha256=_kQUS6_BBvsLBuSZloFrVag6jN90KzHa0ULyGBjufSs,36955
-natural_pdf/core/page.py,sha256=ciwBf-SoI431SJjp2VRfLxdtqgO2L6p044kXXjlNtjo,118231
+natural_pdf/core/page.py,sha256=i3DriIQwoO4RuSrkrCXv44Dz8OL9KXPa2y4GhsD1y18,118324
 natural_pdf/core/pdf.py,sha256=bAoGPiKIrFaebLwULMT-9VkHQ_wkE_zNl4hlbMLk-2w,69325
+natural_pdf/describe/__init__.py,sha256=B3zjuHjFI_dFuBLgXR1Q4v7c72fVDyk84d2hs0H4KV8,561
+natural_pdf/describe/base.py,sha256=7USCFIl4mI5b15LTVkwvhAn_mngMwhwxCnVYaZz5Vdc,16842
+natural_pdf/describe/elements.py,sha256=BOkz2wDhGh6P8NOm6pSNxitgmVokLTISztaFhrxMcdw,12717
+natural_pdf/describe/mixin.py,sha256=U0x6v8r57KQb8qC3VVo64hvhfXQWsti8vdKBM7AXnMo,3116
+natural_pdf/describe/summary.py,sha256=dPtjrn6fQ8nL0F74RITX2vXlDX7ZgaX9JQPnJB-S_XQ,6735
 natural_pdf/elements/__init__.py,sha256=S8XeiNWJ1WcgnyYKdYV1yxQlAxCCO3FfITT8MQwNbyk,41
-natural_pdf/elements/base.py,sha256=tEyCInUc6wxbUtnXVaBa21Qpr591Sgu4yi7tKxWb-3U,39607
-natural_pdf/elements/collections.py,sha256=_lWL-W-RKlYikkGJU66dskGCZ8-7WfMyUx2G0IgjhlQ,121965
+natural_pdf/elements/base.py,sha256=IlAeyzV66xMrxVx9U3ocGPekzGUBJgKkAiJ5kpvCSAg,39675
+natural_pdf/elements/collections.py,sha256=vgVZsVC3xxRF2S5KW7L0JKa-NSUFnqURk50NtvlwbcM,122113
 natural_pdf/elements/line.py,sha256=300kSFBDUBIudfeQtH_tzW9gTYRgRKUDPiTABw6J-BE,4782
 natural_pdf/elements/rect.py,sha256=kiVa3e377ZnqIOXc89d9ZSY4EcmDxtccdtUw-HOQzpw,3796
-natural_pdf/elements/region.py,sha256=nCXyI0vq9-MIQ4Zk90q5Nn-U6gDGv22NY6ime6qG1MY,123330
+natural_pdf/elements/region.py,sha256=hBklYKcXJWyxayu9todYQOZ-d9KVDtqeV-CIt9IcSn8,123400
 natural_pdf/elements/text.py,sha256=13HvVZGinj2Vm_fFCAnqi7hohtoKvnpCp3VCfkpeAbc,11146
 natural_pdf/export/mixin.py,sha256=L1q3MIEFWuvie4j4_EmW7GT3NerbZ1as0XMUoqTS7gM,5083
 natural_pdf/exporters/__init__.py,sha256=7MnvRLLQdwtg-ULu-8uK8C84GsKiJamyhRw_GgWhw7k,151
@@ -85,8 +90,8 @@ natural_pdf/utils/text_extraction.py,sha256=z6Jhy11pakYCsEpkvh8ldw6DkUFsYF1hCL9Y
 natural_pdf/utils/visualization.py,sha256=30pRWQdsRJh2pSObh-brKVsFgC1n8tHmSrta_UDnVPw,8989
 natural_pdf/widgets/__init__.py,sha256=QTVaUmsw__FCweFYZebwPssQxxUFUMd0wpm_cUbGZJY,181
 natural_pdf/widgets/viewer.py,sha256=2VUY1TzWMDe9I-IVNOosKZ2LaqpjLB62ftMAdk-s6_8,24952
-natural_pdf-0.1.16.dist-info/licenses/LICENSE,sha256=9zfwINwJlarbDmdh6iJV4QUG54QSJlSAUcnC1YiC_Ns,1074
-natural_pdf-0.1.16.dist-info/METADATA,sha256=ncvnNI_PubS4q4v29OKp5UXyanEZNVWqsCanu-xGCOA,6753
-natural_pdf-0.1.16.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-natural_pdf-0.1.16.dist-info/top_level.txt,sha256=Cyw1zmNDlUZfb5moU-WUWGprrwH7ln_8LDGdmMHF1xI,17
-natural_pdf-0.1.16.dist-info/RECORD,,
+natural_pdf-0.1.17.dist-info/licenses/LICENSE,sha256=9zfwINwJlarbDmdh6iJV4QUG54QSJlSAUcnC1YiC_Ns,1074
+natural_pdf-0.1.17.dist-info/METADATA,sha256=yGeusUaYx_R_aRl0lUnAHVfBav9Zw43MXDYcB3b6BcA,6753
+natural_pdf-0.1.17.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+natural_pdf-0.1.17.dist-info/top_level.txt,sha256=Cyw1zmNDlUZfb5moU-WUWGprrwH7ln_8LDGdmMHF1xI,17
+natural_pdf-0.1.17.dist-info/RECORD,,