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

{natural_pdf-0.2.3/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.3
+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.3 → 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.

{natural_pdf-0.2.3 → 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.3 → 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.3 → natural_pdf-0.2.4}/natural_pdf/core/render_spec.py

@@ -186,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
@@ -211,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-0.2.3 → natural_pdf-0.2.4}/natural_pdf/elements/base.py

@@ -1192,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,
@@ -1203,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
@@ -1225,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)

{natural_pdf-0.2.3 → natural_pdf-0.2.4}/natural_pdf/elements/region.py

@@ -221,7 +221,7 @@ class Region(
         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"]] = True,  # Default to True for regions
         crop_bbox: Optional[Tuple[float, float, float, float]] = None,
         **kwargs,
@@ -231,7 +231,7 @@ class Region(
         Args:
             mode: Rendering mode - 'show' includes highlights, 'render' is clean
             color: Color for highlighting this region 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 this region
             crop_bbox: Explicit crop bounds (overrides region bounds)
             **kwargs: Additional parameters
@@ -250,10 +250,12 @@ class Region(
             # Crop to this region's bounds
             spec.crop_bbox = self.bbox
 
-        # Add highlights in show mode
-        if mode == "show":
-            # Highlight this region
-            if color or mode == "show":  # Always highlight in show mode
+        # Add highlights in show mode (unless explicitly disabled with highlights=False)
+        if mode == "show" and highlights is not False:
+            # Only highlight this region if:
+            # 1. We're not cropping, OR
+            # 2. We're cropping but color was explicitly specified
+            if not crop or color is not None:
                 spec.add_highlight(
                     bbox=self.bbox,
                     polygon=self.polygon if self.has_polygon else None,
@@ -261,8 +263,8 @@ class Region(
                     label=self.label or self.name or "Region",
                 )
 
-            # 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:
                     elements = group.get("elements", [])
                     group_color = group.get("color", color)

natural_pdf-0.2.4/natural_pdf/vision/__init__.py

@@ -0,0 +1,7 @@
+"""Vision module for visual similarity and pattern matching"""
+
+from .mixin import VisualSearchMixin
+from .results import Match, MatchResults
+from .similarity import VisualMatcher, compute_phash
+
+__all__ = ["VisualMatcher", "compute_phash", "Match", "MatchResults", "VisualSearchMixin"]

natural_pdf-0.2.4/natural_pdf/vision/mixin.py

@@ -0,0 +1,209 @@
+"""Mixin to add visual similarity search to Page/PDF/PDFCollection"""
+
+from typing import List, Optional, Tuple, Union
+
+import numpy as np
+from PIL import Image
+from tqdm.auto import tqdm
+
+from .results import Match, MatchResults
+from .similarity import VisualMatcher, compute_phash
+
+
+class VisualSearchMixin:
+    """Add find_similar method to classes that include this mixin"""
+
+    def find_similar(
+        self,
+        examples: Union["Element", "Region", List[Union["Element", "Region"]]],
+        using: str = "vision",
+        confidence: float = 0.6,
+        sizes: Optional[Union[float, Tuple, List]] = (0.8, 1.2),
+        resolution: int = 72,
+        hash_size: int = 20,
+        step_factor: float = 0.1,
+        max_per_page: Optional[int] = None,
+        show_progress: bool = True,
+        **kwargs,
+    ) -> MatchResults:
+        """
+        Find regions visually similar to the given example(s).
+
+        Args:
+            examples: Single element/region or list of examples to search for
+            using: Search method - currently only 'vision' is supported
+            confidence: Minimum similarity score (0-1)
+            sizes: Size variations to search. Can be:
+                   - float: ±percentage (e.g., 0.2 = 80%-120%)
+                   - tuple(min, max): search range with smart logarithmic steps (default: (0.8, 1.0))
+                   - tuple(min, max, step): explicit step size
+                   - list: exact sizes to try (e.g., [0.8, 1.0, 1.2])
+            resolution: Resolution for image comparison (DPI) (default: 72)
+            hash_size: Size of perceptual hash grid (default: 12)
+            step_factor: Step size as fraction of template size (default: 0.1)
+            max_per_page: Maximum matches to return per page
+            show_progress: Show progress bar for multi-page searches (default: True)
+            **kwargs: Additional options
+
+        Returns:
+            MatchResults collection
+        """
+        if using != "vision":
+            raise NotImplementedError(f"using='{using}' not yet supported")
+
+        # Ensure examples is a list
+        if not isinstance(examples, list):
+            examples = [examples]
+
+        # Initialize matcher with specified hash size
+        matcher = VisualMatcher(hash_size=hash_size)
+
+        # Prepare templates
+        templates = []
+        for example in examples:
+            # Render the example region/element
+            example_image = example.render(resolution=resolution, crop=True)
+            template_hash = compute_phash(example_image, hash_size=hash_size)
+            templates.append({"image": example_image, "hash": template_hash, "source": example})
+
+        # Get pages to search based on the object type
+        if hasattr(self, "__class__") and self.__class__.__name__ == "PDFCollection":
+            # PDFCollection needs to iterate through all PDFs
+            pages_to_search = []
+            for pdf in self:
+                pages_to_search.extend(pdf.pages)
+        elif hasattr(self, "pages"):  # PDF
+            pages_to_search = self.pages
+        elif hasattr(self, "number"):  # Single page
+            pages_to_search = [self]
+        else:
+            raise TypeError(f"Cannot search in {type(self)}")
+
+        # Calculate total operations for progress bar
+        total_operations = 0
+        if show_progress:
+            # Get scales that will be searched
+            scales = matcher._get_search_scales(sizes)
+
+            # Pre-calculate for all pages and templates
+            for page in pages_to_search:
+                # Estimate page image size
+                page_w = int(page.width * resolution / 72.0)
+                page_h = int(page.height * resolution / 72.0)
+
+                for template_data in templates:
+                    template_w, template_h = template_data["image"].size
+
+                    for scale in scales:
+                        scaled_w = int(template_w * scale)
+                        scaled_h = int(template_h * scale)
+
+                        if scaled_w <= page_w and scaled_h <= page_h:
+                            step_x = max(1, int(scaled_w * step_factor))
+                            step_y = max(1, int(scaled_h * step_factor))
+
+                            x_windows = len(range(0, page_w - scaled_w + 1, step_x))
+                            y_windows = len(range(0, page_h - scaled_h + 1, step_y))
+                            total_operations += x_windows * y_windows
+
+        # Search each page
+        all_matches = []
+
+        # Create single progress bar for all operations
+        progress_bar = None
+        operations_done = 0
+        last_update = 0
+        update_frequency = max(1, total_operations // 1000)  # Update at most 1000 times
+
+        if show_progress and total_operations > 0:
+            progress_bar = tqdm(
+                total=total_operations,
+                desc="Searching",
+                unit="window",
+                miniters=update_frequency,  # Minimum iterations between updates
+                mininterval=0.1,  # Minimum time between updates (seconds)
+            )
+
+        for page_idx, page in enumerate(pages_to_search):
+            # Render the full page once
+            page_image = page.render(resolution=resolution)
+
+            # Convert page coordinates to image coordinates
+            scale = resolution / 72.0  # PDF is 72 DPI
+
+            page_matches = []
+
+            # Search for each template
+            for template_idx, template_data in enumerate(templates):
+                template_image = template_data["image"]
+                template_hash = template_data["hash"]
+
+                # Custom progress callback to update our main progress bar
+                def update_progress():
+                    nonlocal operations_done, last_update
+                    operations_done += 1
+
+                    # Only update progress bar every N operations to avoid overwhelming output
+                    if progress_bar and (
+                        operations_done - last_update >= update_frequency
+                        or operations_done == total_operations
+                    ):
+                        progress_bar.update(operations_done - last_update)
+                        last_update = operations_done
+
+                        # Update description with current page/template info
+                        if len(pages_to_search) > 1:
+                            progress_bar.set_description(
+                                f"Page {page.number}/{len(pages_to_search)}"
+                            )
+                        elif len(templates) > 1:
+                            progress_bar.set_description(
+                                f"Template {template_idx + 1}/{len(templates)}"
+                            )
+
+                # Find matches in this page - never show internal progress
+                candidates = matcher.find_matches_in_image(
+                    template_image,
+                    page_image,
+                    template_hash=template_hash,
+                    confidence_threshold=confidence,
+                    sizes=sizes,
+                    step_factor=step_factor,
+                    show_progress=False,  # We handle progress ourselves
+                    progress_callback=update_progress if progress_bar else None,
+                    **kwargs,
+                )
+
+                # Convert image coordinates back to PDF coordinates
+                for candidate in candidates:
+                    img_x0, img_y0, img_x1, img_y1 = candidate.bbox
+
+                    # Convert from image pixels to PDF points
+                    # No flipping needed! PDF coordinates map directly to PIL coordinates
+                    pdf_x0 = img_x0 / scale
+                    pdf_y0 = img_y0 / scale
+                    pdf_x1 = img_x1 / scale
+                    pdf_y1 = img_y1 / scale
+
+                    # Create Match object
+                    match = Match(
+                        page=page,
+                        bbox=(pdf_x0, pdf_y0, pdf_x1, pdf_y1),
+                        confidence=candidate.confidence,
+                        source_example=template_data["source"],
+                    )
+                    page_matches.append(match)
+
+            # Apply max_per_page limit if specified
+            if max_per_page and len(page_matches) > max_per_page:
+                # Sort by confidence and take top N
+                page_matches.sort(key=lambda m: m.confidence, reverse=True)
+                page_matches = page_matches[:max_per_page]
+
+            all_matches.extend(page_matches)
+
+        # Close progress bar
+        if progress_bar:
+            progress_bar.close()
+
+        return MatchResults(all_matches)