natural-pdf 0.1.40__py3-none-any.whl → 0.2.0__py3-none-any.whl

natural_pdf/core/render_spec.py

@@ -0,0 +1,335 @@
+"""Unified rendering infrastructure for natural-pdf.
+
+This module provides the core components for the unified image generation system:
+- RenderSpec: Data structure describing what to render
+- Visualizable: Mixin providing show/render/export methods
+"""
+
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Dict, List, Literal, Optional, Tuple, Union
+
+if TYPE_CHECKING:
+    from PIL import Image as PIL_Image
+
+    from natural_pdf.core.page import Page
+    from natural_pdf.elements.base import Element
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class RenderSpec:
+    """Specification for rendering a single page or region.
+
+    This is the core data structure that unifies all rendering operations.
+    Every visual object in natural-pdf converts its display requirements
+    into one or more RenderSpecs, which are then processed by the
+    unified rendering pipeline.
+
+    Attributes:
+        page: The page to render
+        crop_bbox: Optional bounding box (x0, y0, x1, y1) to crop to
+        highlights: List of highlight specifications, each containing:
+            - bbox or polygon: The geometry to highlight
+            - color: Optional color for the highlight
+            - label: Optional label text
+            - element: Optional reference to the source element
+    """
+
+    page: "Page"
+    crop_bbox: Optional[Tuple[float, float, float, float]] = None
+    highlights: List[Dict[str, Any]] = field(default_factory=list)
+
+    def add_highlight(
+        self,
+        bbox: Optional[Tuple[float, float, float, float]] = None,
+        polygon: Optional[List[Tuple[float, float]]] = None,
+        color: Optional[Union[str, Tuple[int, int, int]]] = None,
+        label: Optional[str] = None,
+        element: Optional["Element"] = None,
+    ) -> None:
+        """Add a highlight to this render spec.
+
+        Args:
+            bbox: Bounding box to highlight
+            polygon: Polygon points to highlight (alternative to bbox)
+            color: Color for the highlight
+            label: Label text for the highlight
+            element: Source element reference
+        """
+        if bbox is None and polygon is None and element is not None:
+            # Extract geometry from element
+            if (
+                hasattr(element, "polygon")
+                and hasattr(element, "has_polygon")
+                and element.has_polygon
+            ):
+                polygon = element.polygon
+            elif hasattr(element, "bbox"):
+                bbox = element.bbox
+
+        if bbox is None and polygon is None:
+            raise ValueError("Must provide bbox, polygon, or element with geometry")
+
+        highlight = {
+            "bbox": bbox,
+            "polygon": polygon,
+            "color": color,
+            "label": label,
+            "element": element,
+        }
+        # Remove None values
+        highlight = {k: v for k, v in highlight.items() if v is not None}
+        self.highlights.append(highlight)
+
+
+class Visualizable:
+    """Mixin class providing unified show/render/export methods.
+
+    Classes that inherit from Visualizable need only implement
+    _get_render_specs() to gain full image generation capabilities.
+    """
+
+    def _get_render_specs(
+        self, mode: Literal["show", "render"] = "show", **kwargs
+    ) -> List[RenderSpec]:
+        """Get render specifications for this object.
+
+        This is the only method subclasses need to implement.
+        It should return a list of RenderSpec objects describing
+        what needs to be rendered.
+
+        Args:
+            mode: Rendering mode - 'show' includes highlights, 'render' is clean
+            **kwargs: Additional parameters from show/render methods
+
+        Returns:
+            List of RenderSpec objects
+        """
+        raise NotImplementedError(f"{self.__class__.__name__} must implement _get_render_specs()")
+
+    def _get_highlighter(self):
+        """Get the highlighting service for rendering.
+
+        This method should be overridden by classes that have
+        a different way of accessing the highlighter.
+        """
+        # Try common patterns
+        if hasattr(self, "_highlighter"):
+            return self._highlighter
+        elif hasattr(self, "page") and hasattr(self.page, "_highlighter"):
+            return self.page._highlighter
+        elif hasattr(self, "pages") and self.pages:
+            # For collections, use first page's highlighter
+            first_page = next(iter(self.pages))
+            if hasattr(first_page, "_highlighter"):
+                return first_page._highlighter
+
+        raise RuntimeError(
+            f"Cannot find HighlightingService for {self.__class__.__name__}. "
+            "Override _get_highlighter() to provide access."
+        )
+
+    def show(
+        self,
+        *,
+        # Basic rendering options
+        resolution: Optional[float] = None,
+        width: Optional[int] = None,
+        # Highlight options
+        color: Optional[Union[str, Tuple[int, int, int]]] = None,
+        labels: bool = True,
+        label_format: Optional[str] = None,
+        highlights: Optional[List[Dict[str, Any]]] = None,
+        legend_position: str = "right",
+        annotate: Optional[Union[str, List[str]]] = None,
+        # Layout options for multi-page/region
+        layout: Literal["stack", "grid", "single"] = "stack",
+        stack_direction: Literal["vertical", "horizontal"] = "vertical",
+        gap: int = 5,
+        columns: Optional[int] = None,  # For grid layout
+        # Cropping options
+        crop: Union[bool, Literal["content"]] = False,
+        crop_bbox: Optional[Tuple[float, float, float, float]] = None,
+        **kwargs,
+    ) -> Optional["PIL_Image"]:
+        """Generate a preview image with highlights.
+
+        This method is for interactive debugging and visualization.
+        Elements are highlighted to show what's selected or being worked with.
+
+        Args:
+            resolution: DPI for rendering (default from global settings)
+            width: Target width in pixels (overrides resolution)
+            color: Default highlight color
+            labels: Whether to show labels for highlights
+            label_format: Format string for labels (e.g., "Element {index}")
+            highlights: Additional highlight groups to show
+            legend_position: Position of legend/colorbar ('right', 'left', 'top', 'bottom')
+            annotate: Attribute name(s) to display on highlights (string or list)
+            layout: How to arrange multiple pages/regions
+            stack_direction: Direction for stack layout
+            gap: Pixels between stacked images
+            columns: Number of columns for grid layout
+            crop: Whether to crop (True, False, or 'content' for bbox of elements)
+            crop_bbox: Explicit crop bounds
+            **kwargs: Additional parameters passed to rendering
+
+        Returns:
+            PIL Image object or None if nothing to render
+        """
+        # Convert string to list if needed
+        if isinstance(annotate, str):
+            annotate = [annotate]
+
+        specs = self._get_render_specs(
+            mode="show",
+            color=color,
+            highlights=highlights,
+            crop=crop,
+            crop_bbox=crop_bbox,
+            annotate=annotate,
+            **kwargs,
+        )
+
+        if not specs:
+            logger.warning(f"{self.__class__.__name__}.show() generated no render specs")
+            return None
+
+        highlighter = self._get_highlighter()
+        return highlighter.unified_render(
+            specs=specs,
+            resolution=resolution,
+            width=width,
+            labels=labels,
+            label_format=label_format,
+            legend_position=legend_position,
+            layout=layout,
+            stack_direction=stack_direction,
+            gap=gap,
+            columns=columns,
+            **kwargs,
+        )
+
+    def render(
+        self,
+        *,
+        # Basic rendering options
+        resolution: Optional[float] = None,
+        width: Optional[int] = None,
+        # Layout options for multi-page/region
+        layout: Literal["stack", "grid", "single"] = "stack",
+        stack_direction: Literal["vertical", "horizontal"] = "vertical",
+        gap: int = 5,
+        columns: Optional[int] = None,
+        # Cropping options
+        crop: Union[bool, Literal["content"]] = False,
+        crop_bbox: Optional[Tuple[float, float, float, float]] = None,
+        **kwargs,
+    ) -> Optional["PIL_Image"]:
+        """Generate a clean image without highlights.
+
+        This method produces publication-ready images without
+        any debugging annotations or highlights.
+
+        Args:
+            resolution: DPI for rendering (default from global settings)
+            width: Target width in pixels (overrides resolution)
+            layout: How to arrange multiple pages/regions
+            stack_direction: Direction for stack layout
+            gap: Pixels between stacked images
+            columns: Number of columns for grid layout
+            crop: Whether to crop
+            crop_bbox: Explicit crop bounds
+            **kwargs: Additional parameters passed to rendering
+
+        Returns:
+            PIL Image object or None if nothing to render
+        """
+        specs = self._get_render_specs(mode="render", crop=crop, crop_bbox=crop_bbox, **kwargs)
+
+        if not specs:
+            logger.warning(f"{self.__class__.__name__}.render() generated no render specs")
+            return None
+
+        highlighter = self._get_highlighter()
+        return highlighter.unified_render(
+            specs=specs,
+            resolution=resolution,
+            width=width,
+            labels=False,  # Never show labels in render mode
+            layout=layout,
+            stack_direction=stack_direction,
+            gap=gap,
+            columns=columns,
+            **kwargs,
+        )
+
+    def export(
+        self,
+        path: Union[str, Path],
+        *,
+        # All the same options as render()
+        resolution: Optional[float] = None,
+        width: Optional[int] = None,
+        layout: Literal["stack", "grid", "single"] = "stack",
+        stack_direction: Literal["vertical", "horizontal"] = "vertical",
+        gap: int = 5,
+        columns: Optional[int] = None,
+        crop: Union[bool, Literal["content"]] = False,
+        crop_bbox: Optional[Tuple[float, float, float, float]] = None,
+        format: Optional[str] = None,
+        **kwargs,
+    ) -> None:
+        """Export a clean image to file.
+
+        This is a convenience method that renders and saves in one step.
+
+        Args:
+            path: Output file path
+            resolution: DPI for rendering
+            width: Target width in pixels
+            layout: How to arrange multiple pages/regions
+            stack_direction: Direction for stack layout
+            gap: Pixels between stacked images
+            columns: Number of columns for grid layout
+            crop: Whether to crop
+            crop_bbox: Explicit crop bounds
+            format: Image format (inferred from path if not specified)
+            **kwargs: Additional parameters passed to rendering
+        """
+        image = self.render(
+            resolution=resolution,
+            width=width,
+            layout=layout,
+            stack_direction=stack_direction,
+            gap=gap,
+            columns=columns,
+            crop=crop,
+            crop_bbox=crop_bbox,
+            **kwargs,
+        )
+
+        if image is None:
+            raise ValueError(f"No image generated by {self.__class__.__name__}.render()")
+
+        # Ensure path is a Path object
+        path = Path(path)
+
+        # Determine format
+        if format is None:
+            format = path.suffix.lstrip(".").upper()
+            if format == "JPG":
+                format = "JPEG"
+
+        # Save image
+        save_kwargs = {}
+        if format == "JPEG":
+            save_kwargs["quality"] = kwargs.get("quality", 95)
+        elif format == "PNG":
+            save_kwargs["compress_level"] = kwargs.get("compress_level", 6)
+
+        image.save(path, format=format, **save_kwargs)
+        logger.info(f"Exported {self.__class__.__name__} to {path}")

natural_pdf/describe/base.py

@@ -17,7 +17,7 @@ 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.element_collection import ElementCollection
     from natural_pdf.elements.region import Region
 
 logger = logging.getLogger(__name__)

natural_pdf/elements/__init__.py

@@ -1,3 +1,4 @@
 """
 Element classes for Natural PDF.
+
 """

natural_pdf/elements/base.py

@@ -2,11 +2,12 @@
 Base Element class for natural-pdf.
 """
 
-from typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuple, Union, overload
+from typing import TYPE_CHECKING, Any, Dict, List, Literal, Optional, Tuple, Union, overload
 
 from PIL import Image
 
 from natural_pdf.classification.mixin import ClassificationMixin
+from natural_pdf.core.render_spec import RenderSpec, Visualizable
 from natural_pdf.describe.mixin import DescribeMixin
 
 # Import selector parsing functions
@@ -15,7 +16,7 @@ from natural_pdf.selectors.parser import parse_selector, selector_to_filter_func
 if TYPE_CHECKING:
     from natural_pdf.classification.manager import ClassificationManager  # noqa: F401
     from natural_pdf.core.page import Page
-    from natural_pdf.elements.collections import ElementCollection
+    from natural_pdf.elements.element_collection import ElementCollection
     from natural_pdf.elements.region import Region
 
 
@@ -563,7 +564,56 @@ class DirectionalMixin:
         return matches[0]
 
 
-class Element(DirectionalMixin, ClassificationMixin, DescribeMixin):
+class HighlightableMixin:
+    """
+    Mixin that provides the highlighting protocol for elements.
+
+    This protocol enables ElementCollection.show() to work with mixed content
+    including FlowRegions and elements from multiple pages by providing a
+    standard way to get highlight specifications.
+    """
+
+    def get_highlight_specs(self) -> List[Dict[str, Any]]:
+        """
+        Get highlight specifications for this element.
+
+        Returns a list of dictionaries, each containing:
+        - page: The Page object to highlight on
+        - page_index: The 0-based index of the page
+        - bbox: The bounding box (x0, y0, x1, y1) to highlight
+        - polygon: Optional polygon coordinates for non-rectangular highlights
+        - element: Reference to the element being highlighted
+
+        For regular elements, this returns a single spec.
+        For FlowRegions, this returns specs for all constituent regions.
+
+        Returns:
+            List of highlight specification dictionaries
+        """
+        # Default implementation for regular elements
+        if not hasattr(self, "page") or self.page is None:
+            return []
+
+        if not hasattr(self, "bbox") or self.bbox is None:
+            return []
+
+        spec = {
+            "page": self.page,
+            "page_index": self.page.index if hasattr(self.page, "index") else 0,
+            "bbox": self.bbox,
+            "element": self,
+        }
+
+        # Add polygon if available
+        if hasattr(self, "polygon") and hasattr(self, "has_polygon") and self.has_polygon:
+            spec["polygon"] = self.polygon
+
+        return [spec]
+
+
+class Element(
+    DirectionalMixin, ClassificationMixin, DescribeMixin, HighlightableMixin, Visualizable
+):
     """Base class for all PDF elements.
 
     This class provides common properties and methods for all PDF elements,
@@ -1024,7 +1074,7 @@ class Element(DirectionalMixin, ClassificationMixin, DescribeMixin):
         label: str = "",
         color: Optional[Tuple[float, float, float]] = None,
         use_color_cycling: bool = True,
-        include_attrs: Optional[List[str]] = None,
+        annotate: Optional[List[str]] = None,
         existing: str = "append",
     ) -> "Element":
         """Highlight the element with the specified colour.
@@ -1042,7 +1092,7 @@ class Element(DirectionalMixin, ClassificationMixin, DescribeMixin):
             "label": label,
             "use_color_cycling": use_color_cycling,
             "element": self,  # Pass the element itself so attributes can be accessed
-            "include_attrs": include_attrs,
+            "annotate": annotate,
             "existing": existing,
         }
 
@@ -1056,84 +1106,67 @@ class Element(DirectionalMixin, ClassificationMixin, DescribeMixin):
 
         return self
 
-    def show(
+    def _get_render_specs(
         self,
-        resolution: Optional[float] = None,
-        labels: bool = True,
-        legend_position: str = "right",
-        color: Optional[Union[Tuple, str]] = "red",  # Default color for single element
+        mode: Literal["show", "render"] = "show",
+        color: Optional[Union[str, Tuple[int, int, int]]] = None,
+        highlights: Optional[List[Dict[str, Any]]] = None,
+        crop: Union[bool, Literal["content"]] = False,
+        crop_bbox: Optional[Tuple[float, float, float, float]] = None,
         label: Optional[str] = None,
-        width: Optional[int] = None,  # Add width parameter
-        crop: bool = False,  # NEW: Crop to element bounds before legend
-    ) -> Optional["Image.Image"]:
-        """
-        Show the page with only this element highlighted temporarily.
+        **kwargs,
+    ) -> List[RenderSpec]:
+        """Get render specifications for this element.
 
         Args:
-            resolution: Resolution in DPI for rendering (default: uses global options, fallback to 144 DPI)
-            labels: Whether to include a legend for the highlight
-            legend_position: Position of the legend
-            color: Color to highlight this element (default: red)
-            label: Optional label for this element in the legend
-            width: Optional width for the output image in pixels
-            crop: If True, crop the rendered image to this element's
-                        bounding box before legends/overlays are added.
+            mode: Rendering mode - 'show' includes highlights, 'render' is clean
+            color: Color for highlighting this element in show mode
+            highlights: Additional highlight groups to show
+            crop: Whether to crop to element bounds
+            crop_bbox: Explicit crop bounds
+            label: Optional label for this element
+            **kwargs: Additional parameters
 
         Returns:
-            PIL Image of the page with only this element highlighted, or None if error.
+            List with single RenderSpec for this element's page
         """
-        # Apply global options as defaults
-        import natural_pdf
-
-        if resolution is None:
-            if natural_pdf.options.image.resolution is not None:
-                resolution = natural_pdf.options.image.resolution
-            else:
-                resolution = 144  # Default resolution when none specified
-        if not hasattr(self, "page") or not self.page:
-            logger.warning(f"Cannot show element, missing 'page' attribute: {self}")
-            return None
-        if not hasattr(self.page, "_highlighter") or not self.page._highlighter:
-            logger.warning(f"Cannot show element, page lacks highlighter service: {self}")
-            return None
-
-        service = self.page._highlighter
-
-        # Determine the label if not provided
-        display_label = label if label is not None else f"{self.__class__.__name__}"
-
-        # Prepare temporary highlight data for just this element
-        temp_highlight_data = {
-            "page_index": self.page.index,
-            "bbox": self.bbox if not self.has_polygon else None,
-            "polygon": self.polygon if self.has_polygon else None,
-            "color": color,  # Use provided or default color
-            "label": display_label,
-            "use_color_cycling": False,  # Explicitly false for single preview
-        }
+        if not hasattr(self, "page") or self.page is None:
+            return []
+
+        spec = RenderSpec(page=self.page)
+
+        # Handle cropping
+        if crop_bbox:
+            spec.crop_bbox = crop_bbox
+        elif crop == "content" or crop is True:
+            # Crop to element bounds
+            if hasattr(self, "bbox") and self.bbox:
+                spec.crop_bbox = self.bbox
+
+        # Add highlight in show mode
+        if mode == "show":
+            # Use provided label or generate one
+            element_label = label if label is not None else self.__class__.__name__
+
+            spec.add_highlight(
+                element=self,
+                color=color or "red",  # Default red for single element
+                label=element_label,
+            )
 
-        # Determine crop bbox
-        crop_bbox = self.bbox if crop else None
+            # Add additional highlight groups if provided
+            if highlights:
+                for group in highlights:
+                    group_elements = group.get("elements", [])
+                    group_color = group.get("color", color)
+                    group_label = group.get("label")
 
-        # Check if we actually got geometry data
-        if temp_highlight_data["bbox"] is None and temp_highlight_data["polygon"] is None:
-            logger.warning(f"Cannot show element, failed to get bbox or polygon: {self}")
-            return None
+                    for elem in group_elements:
+                        # Only add if element is on same page
+                        if hasattr(elem, "page") and elem.page == self.page:
+                            spec.add_highlight(element=elem, color=group_color, label=group_label)
 
-        # Use render_preview to show only this highlight
-        try:
-            return service.render_preview(
-                page_index=self.page.index,
-                temporary_highlights=[temp_highlight_data],
-                resolution=resolution,
-                width=width,  # Pass the width parameter
-                labels=labels,
-                legend_position=legend_position,
-                crop_bbox=crop_bbox,
-            )
-        except Exception as e:
-            logger.error(f"Error calling render_preview for element {self}: {e}", exc_info=True)
-            return None
+        return [spec]
 
     def save(
         self,
@@ -1346,22 +1379,14 @@ class Element(DirectionalMixin, ClassificationMixin, DescribeMixin):
             resolution = kwargs.get("resolution", 150)
             from natural_pdf.elements.region import Region  # Local import to avoid cycles
 
-            return self.expand().to_image(
+            # Use render() for clean image without highlights
+            return self.expand().render(
                 resolution=resolution,
-                include_highlights=False,
                 crop=True,
             )
         else:
             raise ValueError(f"Unsupported model_type for classification: {model_type}")
 
-    # ------------------------------------------------------------------
-    # Lightweight to_image proxy (vision models, previews, etc.)
-    # ------------------------------------------------------------------
-
-    def to_image(self, *args, **kwargs):  # type: ignore[override]
-        """Generate an image of this element by delegating to a temporary Region."""
-        return self.expand().to_image(*args, **kwargs)
-
     # ------------------------------------------------------------------
     # Unified analysis storage (maps to metadata["analysis"])
     # ------------------------------------------------------------------