natural-pdf 0.2.2__py3-none-any.whl → 0.2.4__py3-none-any.whl

natural_pdf/collections/mixins.py

@@ -29,9 +29,22 @@ class DirectionalCollectionMixin:
         """Find regions to the right of all elements in this collection."""
         return self.apply(lambda element: element.right(**kwargs))
 
-    def expand(self, **kwargs) -> "ElementCollection":
-        """Expand all elements in this collection."""
-        return self.apply(lambda element: element.expand(**kwargs))
+    def expand(self, *args, **kwargs) -> "ElementCollection":
+        """Expand all elements in this collection.
+
+        Args:
+            *args: If a single positional argument is provided, expands all elements
+                   by that amount in all directions.
+            **kwargs: Keyword arguments for directional expansion (left, right, top, bottom, etc.)
+
+        Examples:
+            # Expand all elements by 5 pixels in all directions
+            collection.expand(5)
+
+            # Expand with different amounts in each direction
+            collection.expand(left=10, right=5, top=3, bottom=7)
+        """
+        return self.apply(lambda element: element.expand(*args, **kwargs))
 
 
 class ApplyMixin:

natural_pdf/core/highlighting_service.py

@@ -335,6 +335,7 @@ class HighlightContext:
         self.show_on_exit = show_on_exit
         self.highlight_groups = []
         self._color_manager = ColorManager()
+        self._exit_image = None  # Store image for Jupyter display
 
     def add(
         self,
@@ -421,6 +422,11 @@ class HighlightContext:
             )
             return None
 
+    @property
+    def image(self) -> Optional[Image.Image]:
+        """Get the last generated image (useful after context exit)."""
+        return self._exit_image
+
     def __enter__(self) -> "HighlightContext":
         """Enter the context."""
         return self
@@ -428,7 +434,25 @@ class HighlightContext:
     def __exit__(self, exc_type, exc_val, exc_tb):
         """Exit the context, optionally showing highlights."""
         if self.show_on_exit and not exc_type:
-            self.show()
+            self._exit_image = self.show()
+
+            # Check if we're in a Jupyter/IPython environment
+            try:
+                # Try to get IPython instance
+                from IPython import get_ipython
+
+                ipython = get_ipython()
+                if ipython is not None:
+                    # We're in IPython/Jupyter
+                    from IPython.display import display
+
+                    if self._exit_image is not None:
+                        display(self._exit_image)
+            except (ImportError, NameError):
+                # Not in Jupyter or IPython not available - that's OK
+                pass
+
+        # __exit__ must return False to not suppress exceptions
         return False
 
 

natural_pdf/core/page.py

@@ -78,6 +78,7 @@ 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
+from natural_pdf.vision.mixin import VisualSearchMixin
 from natural_pdf.widgets.viewer import _IPYWIDGETS_AVAILABLE, InteractiveViewerWidget
 
 # --- End Classification Imports --- #
@@ -101,6 +102,7 @@ class Page(
     ExtractionMixin,
     ShapeDetectionMixin,
     DescribeMixin,
+    VisualSearchMixin,
     Visualizable,
 ):
     """Enhanced Page wrapper built on top of pdfplumber.Page.
@@ -1976,7 +1978,7 @@ class Page(
         """Get all line elements on this page."""
         return self._element_mgr.lines
 
-    def highlight(
+    def add_highlight(
         self,
         bbox: Optional[Tuple[float, float, float, float]] = None,
         color: Optional[Union[Tuple, str]] = None,
@@ -1987,7 +1989,7 @@ class Page(
         existing: str = "append",
     ) -> "Page":
         """
-        Highlight a bounding box or the entire page.
+        Add a highlight to a bounding box or the entire page.
         Delegates to the central HighlightingService.
 
         Args:
@@ -2015,7 +2017,7 @@ class Page(
         )
         return self
 
-    def highlight_polygon(
+    def add_highlight_polygon(
         self,
         polygon: List[Tuple[float, float]],
         color: Optional[Union[Tuple, str]] = None,

natural_pdf/core/page_collection.py

@@ -259,7 +259,7 @@ class PageCollection(TextMixin, Generic[P], ApplyMixin, ShapeDetectionMixin, Vis
         self,
         *,
         text: str,
-        contains: str = "all",
+        overlap: str = "full",
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -271,7 +271,7 @@ class PageCollection(TextMixin, Generic[P], ApplyMixin, ShapeDetectionMixin, Vis
         self,
         selector: str,
         *,
-        contains: str = "all",
+        overlap: str = "full",
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -283,7 +283,7 @@ class PageCollection(TextMixin, Generic[P], ApplyMixin, ShapeDetectionMixin, Vis
         selector: Optional[str] = None,
         *,
         text: Optional[str] = None,
-        contains: str = "all",
+        overlap: str = "full",
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -297,9 +297,9 @@ class PageCollection(TextMixin, Generic[P], ApplyMixin, ShapeDetectionMixin, Vis
         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")
+            overlap: How to determine if elements overlap: 'full' (fully inside),
+                     'partial' (any overlap), or 'center' (center point inside).
+                     (default: "full")
             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).
@@ -313,7 +313,7 @@ class PageCollection(TextMixin, Generic[P], ApplyMixin, ShapeDetectionMixin, Vis
             element = page.find(
                 selector=selector,
                 text=text,
-                contains=contains,
+                overlap=overlap,
                 apply_exclusions=apply_exclusions,
                 regex=regex,
                 case=case,
@@ -328,7 +328,7 @@ class PageCollection(TextMixin, Generic[P], ApplyMixin, ShapeDetectionMixin, Vis
         self,
         *,
         text: str,
-        contains: str = "all",
+        overlap: str = "full",
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -340,7 +340,7 @@ class PageCollection(TextMixin, Generic[P], ApplyMixin, ShapeDetectionMixin, Vis
         self,
         selector: str,
         *,
-        contains: str = "all",
+        overlap: str = "full",
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -352,7 +352,7 @@ class PageCollection(TextMixin, Generic[P], ApplyMixin, ShapeDetectionMixin, Vis
         selector: Optional[str] = None,
         *,
         text: Optional[str] = None,
-        contains: str = "all",
+        overlap: str = "full",
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -366,9 +366,9 @@ class PageCollection(TextMixin, Generic[P], ApplyMixin, ShapeDetectionMixin, Vis
         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")
+            overlap: How to determine if elements overlap: 'full' (fully inside),
+                     'partial' (any overlap), or 'center' (center point inside).
+                     (default: "full")
             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).
@@ -383,7 +383,7 @@ class PageCollection(TextMixin, Generic[P], ApplyMixin, ShapeDetectionMixin, Vis
             elements = page.find_all(
                 selector=selector,
                 text=text,
-                contains=contains,
+                overlap=overlap,
                 apply_exclusions=apply_exclusions,
                 regex=regex,
                 case=case,

natural_pdf/core/pdf.py

@@ -42,6 +42,7 @@ from natural_pdf.ocr import OCRManager, OCROptions
 from natural_pdf.selectors.parser import parse_selector
 from natural_pdf.text_mixin import TextMixin
 from natural_pdf.utils.locks import pdf_render_lock
+from natural_pdf.vision.mixin import VisualSearchMixin
 
 if TYPE_CHECKING:
     from natural_pdf.elements.element_collection import ElementCollection
@@ -252,7 +253,9 @@ class _LazyPageList(Sequence):
 # --- End Lazy Page List Helper --- #
 
 
-class PDF(TextMixin, ExtractionMixin, ExportMixin, ClassificationMixin, Visualizable):
+class PDF(
+    TextMixin, ExtractionMixin, ExportMixin, ClassificationMixin, VisualSearchMixin, Visualizable
+):
     """Enhanced PDF wrapper built on top of pdfplumber.
 
     This class provides a fluent interface for working with PDF documents,

natural_pdf/core/pdf_collection.py

@@ -40,6 +40,7 @@ logger = logging.getLogger(__name__)
 from natural_pdf.core.pdf import PDF
 from natural_pdf.elements.region import Region
 from natural_pdf.export.mixin import ExportMixin
+from natural_pdf.vision.mixin import VisualSearchMixin
 
 # --- Search Imports ---
 try:
@@ -69,8 +70,8 @@ from natural_pdf.search.searchable_mixin import SearchableMixin  # Import the ne
 
 
 class PDFCollection(
-    SearchableMixin, ApplyMixin, ExportMixin, ShapeDetectionMixin
-):  # Add ExportMixin and ShapeDetectionMixin
+    SearchableMixin, ApplyMixin, ExportMixin, ShapeDetectionMixin, VisualSearchMixin
+):
     def __init__(
         self,
         source: Union[str, Iterable[Union[str, "PDF"]]],
@@ -258,8 +259,6 @@ class PDFCollection(
         return iter(self._pdfs)
 
     def __repr__(self) -> str:
-        # Removed search status
-        return f"<PDFCollection(count={len(self._pdfs)})>"
         return f"<PDFCollection(count={len(self._pdfs)})>"
 
     @property
@@ -267,6 +266,134 @@ class PDFCollection(
         """Returns the list of PDF objects held by the collection."""
         return self._pdfs
 
+    def show(self, limit: Optional[int] = 30, per_pdf_limit: Optional[int] = 10, **kwargs):
+        """
+        Display all PDFs in the collection with labels.
+
+        Each PDF is shown with its pages in a grid layout (6 columns by default),
+        and all PDFs are stacked vertically with labels.
+
+        Args:
+            limit: Maximum total pages to show across all PDFs (default: 30)
+            per_pdf_limit: Maximum pages to show per PDF (default: 10)
+            **kwargs: Additional arguments passed to each PDF's show() method
+                     (e.g., columns, exclusions, resolution, etc.)
+
+        Returns:
+            Displayed image in Jupyter or None
+        """
+        if not self._pdfs:
+            print("Empty collection")
+            return None
+
+        # Import here to avoid circular imports
+        import numpy as np
+        from PIL import Image, ImageDraw, ImageFont
+
+        # Calculate pages per PDF if total limit is set
+        if limit and not per_pdf_limit:
+            per_pdf_limit = max(1, limit // len(self._pdfs))
+
+        # Collect images from each PDF
+        all_images = []
+        total_pages_shown = 0
+
+        for pdf in self._pdfs:
+            if limit and total_pages_shown >= limit:
+                break
+
+            # Calculate limit for this PDF
+            pdf_limit = per_pdf_limit
+            if limit:
+                remaining = limit - total_pages_shown
+                pdf_limit = min(per_pdf_limit or remaining, remaining)
+
+            # Get PDF identifier
+            pdf_name = getattr(pdf, "filename", None) or getattr(pdf, "path", "Unknown")
+            if isinstance(pdf_name, Path):
+                pdf_name = pdf_name.name
+            elif "/" in str(pdf_name):
+                pdf_name = str(pdf_name).split("/")[-1]
+
+            # Render this PDF
+            try:
+                # Get render specs from the PDF
+                render_specs = pdf._get_render_specs(mode="show", max_pages=pdf_limit, **kwargs)
+
+                if not render_specs:
+                    continue
+
+                # Get the highlighter and render without displaying
+                highlighter = pdf._get_highlighter()
+                pdf_image = highlighter.unified_render(
+                    specs=render_specs,
+                    layout="grid" if len(render_specs) > 1 else "single",
+                    columns=6,
+                    **kwargs,
+                )
+
+                if pdf_image:
+                    # Add label above the PDF image
+                    label_height = 40
+                    label_bg_color = (240, 240, 240)
+                    label_text_color = (0, 0, 0)
+
+                    # Create new image with space for label
+                    width, height = pdf_image.size
+                    labeled_image = Image.new("RGB", (width, height + label_height), "white")
+
+                    # Draw label background
+                    draw = ImageDraw.Draw(labeled_image)
+                    draw.rectangle([0, 0, width, label_height], fill=label_bg_color)
+
+                    # Draw label text
+                    try:
+                        # Try to use a nice font if available
+                        font = ImageFont.truetype("Arial", 20)
+                    except:
+                        # Fallback to default font
+                        font = ImageFont.load_default()
+
+                    label_text = f"{pdf_name} ({len(pdf.pages)} pages)"
+                    draw.text((10, 10), label_text, fill=label_text_color, font=font)
+
+                    # Paste PDF image below label
+                    labeled_image.paste(pdf_image, (0, label_height))
+
+                    all_images.append(labeled_image)
+                    total_pages_shown += min(pdf_limit, len(pdf.pages))
+
+            except Exception as e:
+                logger.warning(f"Failed to render PDF {pdf_name}: {e}")
+                continue
+
+        if not all_images:
+            print("No PDFs could be rendered")
+            return None
+
+        # Combine all images vertically
+        if len(all_images) == 1:
+            combined = all_images[0]
+        else:
+            # Add spacing between PDFs
+            spacing = 20
+            total_height = sum(img.height for img in all_images) + spacing * (len(all_images) - 1)
+            max_width = max(img.width for img in all_images)
+
+            combined = Image.new("RGB", (max_width, total_height), "white")
+
+            y_offset = 0
+            for i, img in enumerate(all_images):
+                # Center images if they're narrower than max width
+                x_offset = (max_width - img.width) // 2
+                combined.paste(img, (x_offset, y_offset))
+                y_offset += img.height
+                if i < len(all_images) - 1:
+                    y_offset += spacing
+
+        # Return the combined image (Jupyter will display it automatically)
+        return combined
+
     @overload
     def find_all(
         self,

natural_pdf/core/render_spec.py

@@ -92,6 +92,50 @@ class Visualizable:
     _get_render_specs() to gain full image generation capabilities.
     """
 
+    def highlight(self, *elements, **kwargs):
+        """
+        Convenience method for highlighting elements in Jupyter/Colab.
+
+        This method creates a highlight context, adds the elements, and returns
+        the resulting image. It's designed for simple one-liner usage in notebooks.
+
+        Args:
+            *elements: Elements or element collections to highlight
+            **kwargs: Additional parameters passed to show()
+
+        Returns:
+            PIL Image with highlights
+
+        Example:
+            # Simple one-liner highlighting
+            page.highlight(left, mid, right)
+
+            # With custom colors
+            page.highlight(
+                (tables, 'blue'),
+                (headers, 'red'),
+                (footers, 'green')
+            )
+        """
+        from natural_pdf.core.highlighting_service import HighlightContext
+
+        # Create context and add elements
+        ctx = HighlightContext(self, show_on_exit=False)
+
+        for element in elements:
+            if isinstance(element, tuple) and len(element) == 2:
+                # Element with color: (element, color)
+                ctx.add(element[0], color=element[1])
+            elif isinstance(element, tuple) and len(element) == 3:
+                # Element with color and label: (element, color, label)
+                ctx.add(element[0], color=element[1], label=element[2])
+            else:
+                # Just element
+                ctx.add(element)
+
+        # Return the image directly
+        return ctx.show(**kwargs)
+
     def _get_render_specs(
         self, mode: Literal["show", "render"] = "show", **kwargs
     ) -> List[RenderSpec]:
@@ -142,7 +186,7 @@ class Visualizable:
         color: Optional[Union[str, Tuple[int, int, int]]] = None,
         labels: bool = True,
         label_format: Optional[str] = None,
-        highlights: Optional[List[Dict[str, Any]]] = None,
+        highlights: Optional[Union[List[Dict[str, Any]], bool]] = None,
         legend_position: str = "right",
         annotate: Optional[Union[str, List[str]]] = None,
         # Layout options for multi-page/region
@@ -167,7 +211,7 @@ class Visualizable:
             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
+            highlights: Additional highlight groups to show, or False to disable all highlights
             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 (defaults to 'grid' for multi-page, 'single' for single page)

natural_pdf/elements/base.py

@@ -429,8 +429,28 @@ class DirectionalMixin:
     def to_region(self):
         return self.expand()
 
+    @overload
+    def expand(self, amount: float) -> "Region":
+        """Expand in all directions by the same amount."""
+        ...
+
+    @overload
     def expand(
         self,
+        *,
+        left: float = 0,
+        right: float = 0,
+        top: float = 0,
+        bottom: float = 0,
+        width_factor: float = 1.0,
+        height_factor: float = 1.0,
+    ) -> "Region":
+        """Expand by different amounts in each direction."""
+        ...
+
+    def expand(
+        self,
+        amount: Optional[float] = None,
         left: float = 0,
         right: float = 0,
         top: float = 0,
@@ -442,6 +462,7 @@ class DirectionalMixin:
         Create a new region expanded from this element/region.
 
         Args:
+            amount: If provided as the first positional argument, expand all edges by this amount
             left: Amount to expand left edge (positive value expands leftwards)
             right: Amount to expand right edge (positive value expands rightwards)
             top: Amount to expand top edge (positive value expands upwards)
@@ -451,7 +472,20 @@ class DirectionalMixin:
 
         Returns:
             New expanded Region object
+
+        Examples:
+            # Expand 5 pixels in all directions
+            expanded = element.expand(5)
+
+            # Expand by different amounts in each direction
+            expanded = element.expand(left=10, right=5, top=3, bottom=7)
+
+            # Use width/height factors
+            expanded = element.expand(width_factor=1.5, height_factor=2.0)
         """
+        # If amount is provided as first positional argument, use it for all directions
+        if amount is not None:
+            left = right = top = bottom = amount
         # Start with current coordinates
         new_x0 = self.x0
         new_x1 = self.x1
@@ -1158,7 +1192,7 @@ class Element(
         self,
         mode: Literal["show", "render"] = "show",
         color: Optional[Union[str, Tuple[int, int, int]]] = None,
-        highlights: Optional[List[Dict[str, Any]]] = None,
+        highlights: Optional[Union[List[Dict[str, Any]], bool]] = None,
         crop: Union[bool, Literal["content"]] = False,
         crop_bbox: Optional[Tuple[float, float, float, float]] = None,
         label: Optional[str] = None,
@@ -1169,7 +1203,7 @@ class Element(
         Args:
             mode: Rendering mode - 'show' includes highlights, 'render' is clean
             color: Color for highlighting this element in show mode
-            highlights: Additional highlight groups to show
+            highlights: Additional highlight groups to show, or False to disable all highlights
             crop: Whether to crop to element bounds
             crop_bbox: Explicit crop bounds
             label: Optional label for this element
@@ -1191,19 +1225,23 @@ class Element(
             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,
-            )
+        # Add highlight in show mode (unless explicitly disabled with highlights=False)
+        if mode == "show" and highlights is not False:
+            # Only highlight this element if:
+            # 1. We're not cropping, OR
+            # 2. We're cropping but color was explicitly specified
+            if not crop or color is not None:
+                # 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,
+                )
 
-            # Add additional highlight groups if provided
-            if highlights:
+            # Add additional highlight groups if provided (and highlights is a list)
+            if highlights and isinstance(highlights, list):
                 for group in highlights:
                     group_elements = group.get("elements", [])
                     group_color = group.get("color", color)
@@ -1260,7 +1298,7 @@ class Element(
         self,
         *,
         text: str,
-        contains: str = "all",
+        overlap: str = "full",
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -1272,7 +1310,7 @@ class Element(
         self,
         selector: str,
         *,
-        contains: str = "all",
+        overlap: str = "full",
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -1284,7 +1322,7 @@ class Element(
         selector: Optional[str] = None,
         *,
         text: Optional[str] = None,
-        contains: str = "all",
+        overlap: str = "full",
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -1299,9 +1337,9 @@ class Element(
         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")
+            overlap: How to determine if elements overlap with this element: 'full' (fully inside),
+                     'partial' (any overlap), or 'center' (center point inside).
+                     (default: "full")
             apply_exclusions: Whether to apply 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).
@@ -1318,7 +1356,7 @@ class Element(
         return temp_region.find(
             selector=selector,
             text=text,
-            contains=contains,
+            overlap=overlap,
             apply_exclusions=apply_exclusions,
             regex=regex,
             case=case,
@@ -1330,7 +1368,7 @@ class Element(
         self,
         *,
         text: str,
-        contains: str = "all",
+        overlap: str = "full",
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -1342,7 +1380,7 @@ class Element(
         self,
         selector: str,
         *,
-        contains: str = "all",
+        overlap: str = "full",
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -1354,7 +1392,7 @@ class Element(
         selector: Optional[str] = None,
         *,
         text: Optional[str] = None,
-        contains: str = "all",
+        overlap: str = "full",
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -1369,9 +1407,9 @@ class Element(
         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")
+            overlap: How to determine if elements overlap with this element: 'full' (fully inside),
+                     'partial' (any overlap), or 'center' (center point inside).
+                     (default: "full")
             apply_exclusions: Whether to apply 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).
@@ -1388,7 +1426,7 @@ class Element(
         return temp_region.find_all(
             selector=selector,
             text=text,
-            contains=contains,
+            overlap=overlap,
             apply_exclusions=apply_exclusions,
             regex=regex,
             case=case,