natural-pdf 0.2.2__tar.gz → 0.2.4__tar.gz

{natural_pdf-0.2.2/natural_pdf.egg-info → natural_pdf-0.2.4}/PKG-INFO

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

{natural_pdf-0.2.2 → natural_pdf-0.2.4}/docs/quick-reference/index.md

@@ -156,11 +156,25 @@ elements.show(color="red")                      # Single collection
 elements.show(color="blue", label="Headers")    # With label
 elements.show(group_by='type')                  # Color by type
 
-# Multiple collections together
+# Quick highlighting (one-liner)
+page.highlight(elements1, elements2, elements3)  # Multiple elements
+page.highlight(                                  # With custom colors
+    (elements1, 'red'),
+    (elements2, 'blue'),
+    (elements3, 'green')
+)
+
+# Multiple collections with context manager
 with page.highlights() as h:
     h.add(elements1, color="red", label="Type 1")
     h.add(elements2, color="blue", label="Type 2")
     h.show()
+
+# Auto-display in Jupyter/Colab
+with page.highlights(show=True) as h:
+    h.add(elements1, label="Headers")
+    h.add(elements2, label="Content")
+    # Displays automatically when exiting context
 ```
 
 ### Viewing

{natural_pdf-0.2.2 → natural_pdf-0.2.4}/docs/visual-debugging/index.md

@@ -83,6 +83,47 @@ with page.highlights() as h:
     h.show()
 ```
 
+### Jupyter/Colab Support
+
+In Jupyter notebooks and Google Colab, you can use `show=True` to automatically display the highlights when exiting the context:
+
+```python
+# Automatically displays the image in Jupyter/Colab
+with page.highlights(show=True) as h:
+    h.add(summary_elements, label='Summary')
+    h.add(date_elements, label='Date')
+    h.add(line_elements, label='Lines')
+    # No need to call h.show() - displays automatically!
+```
+
+### Quick Highlighting with `.highlight()`
+
+For simple highlighting tasks, use the `.highlight()` convenience method:
+
+```python
+# Highlight multiple elements in one line
+page.highlight(summary_elements, date_elements, line_elements)
+
+# With custom colors
+page.highlight(
+    (summary_elements, 'red'),
+    (date_elements, 'blue'),
+    (line_elements, 'green')
+)
+
+# With colors and labels
+page.highlight(
+    (summary_elements, 'red', 'Summary Text'),
+    (date_elements, 'blue', 'Date Fields'),
+    (line_elements, 'green', 'Separator Lines')
+)
+
+# Pass additional parameters like width or resolution
+page.highlight(summary_elements, date_elements, width=800, labels=True)
+```
+
+This method is particularly useful in Jupyter/Colab environments where the image displays automatically as the cell output.
+
 ## Customizing Multiple Highlights
 
 Customize the appearance of multiple highlights using the context manager:
@@ -133,7 +174,7 @@ content = title.below(height=200)
 content.show()
 ```
 
-Or look at just the region by itself
+Or look at just the region by itself:
 
 ```python
 # Find a title and create a region below it
@@ -144,6 +185,27 @@ content = title.below(height=200)
 content.show(crop=True)
 ```
 
+### Highlighting Multiple Regions
+
+The `.highlight()` method works with regions too:
+
+```python
+# Create multiple regions
+left = page.region(left=0, right=page.width/3, top=0, bottom=page.height)
+mid = page.region(left=page.width/3, right=page.width/3*2, top=0, bottom=page.height)
+right = page.region(left=page.width/3*2, right=page.width, top=0, bottom=page.height)
+
+# Highlight all three regions
+page.highlight(left, mid, right)
+
+# Or with custom colors
+page.highlight(
+    (left, 'red', 'Left Column'),
+    (mid, 'green', 'Middle Column'),
+    (right, 'blue', 'Right Column')
+)
+```
+
 ## Working with Text Styles
 
 Visualize text styles to understand the document structure:

{natural_pdf-0.2.2 → natural_pdf-0.2.4}/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-0.2.2 → natural_pdf-0.2.4}/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-0.2.2 → natural_pdf-0.2.4}/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-0.2.2 → natural_pdf-0.2.4}/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-0.2.2 → natural_pdf-0.2.4}/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-0.2.2 → natural_pdf-0.2.4}/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-0.2.2 → natural_pdf-0.2.4}/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)