natural-pdf 0.2.11__py3-none-any.whl → 0.2.13__py3-none-any.whl

natural_pdf/elements/region.py

@@ -45,6 +45,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
 
 # Import viewer widget support
 from natural_pdf.widgets.viewer import _IPYWIDGETS_AVAILABLE, InteractiveViewerWidget
@@ -80,6 +81,7 @@ class Region(
     ExtractionMixin,
     ShapeDetectionMixin,
     DescribeMixin,
+    VisualSearchMixin,
     Visualizable,
 ):
     """Represents a rectangular region on a page.
@@ -1270,7 +1272,8 @@ class Region(
         # 3. Get Relevant Exclusions (overlapping this region)
         apply_exclusions_flag = kwargs.get("apply_exclusions", apply_exclusions)
         exclusion_regions = []
-        if apply_exclusions_flag and self._page._exclusions:
+        if apply_exclusions_flag:
+            # Always call _get_exclusion_regions to get both page and PDF level exclusions
             all_page_exclusions = self._page._get_exclusion_regions(
                 include_callable=True, debug=debug
             )
@@ -1281,10 +1284,11 @@ class Region(
             exclusion_regions = overlapping_exclusions
             if debug:
                 logger.debug(
-                    f"Region {self.bbox}: Applying {len(exclusion_regions)} overlapping exclusions."
+                    f"Region {self.bbox}: Found {len(all_page_exclusions)} total exclusions, "
+                    f"{len(exclusion_regions)} overlapping this region."
                 )
         elif debug:
-            logger.debug(f"Region {self.bbox}: Not applying exclusions.")
+            logger.debug(f"Region {self.bbox}: Not applying exclusions (apply_exclusions=False).")
 
         # 4. Spatially Filter Characters using Utility
         # Pass self as the target_region for precise polygon checks etc.
@@ -1690,7 +1694,21 @@ class Region(
         else:
             filtered_page = base_plumber_page
 
-        cropped = filtered_page.crop(self.bbox)
+        # Ensure bbox is within pdfplumber page bounds
+        page_bbox = filtered_page.bbox
+        clipped_bbox = (
+            max(self.bbox[0], page_bbox[0]),  # x0
+            max(self.bbox[1], page_bbox[1]),  # y0
+            min(self.bbox[2], page_bbox[2]),  # x1
+            min(self.bbox[3], page_bbox[3]),  # y1
+        )
+
+        # Only crop if the clipped bbox is valid (has positive width and height)
+        if clipped_bbox[2] > clipped_bbox[0] and clipped_bbox[3] > clipped_bbox[1]:
+            cropped = filtered_page.crop(clipped_bbox)
+        else:
+            # If the region is completely outside the page bounds, return empty list
+            return []
 
         # Extract all tables from the cropped area
         tables = cropped.extract_tables(table_settings)
@@ -1784,7 +1802,21 @@ class Region(
             filtered_page = base_plumber_page
 
         # Now crop the (possibly filtered) page to the region bbox
-        cropped = filtered_page.crop(self.bbox)
+        # Ensure bbox is within pdfplumber page bounds
+        page_bbox = filtered_page.bbox
+        clipped_bbox = (
+            max(self.bbox[0], page_bbox[0]),  # x0
+            max(self.bbox[1], page_bbox[1]),  # y0
+            min(self.bbox[2], page_bbox[2]),  # x1
+            min(self.bbox[3], page_bbox[3]),  # y1
+        )
+
+        # Only crop if the clipped bbox is valid (has positive width and height)
+        if clipped_bbox[2] > clipped_bbox[0] and clipped_bbox[3] > clipped_bbox[1]:
+            cropped = filtered_page.crop(clipped_bbox)
+        else:
+            # If the region is completely outside the page bounds, return empty table
+            return []
 
         # Extract the single largest table from the cropped area
         table = cropped.extract_table(table_settings)

natural_pdf/vision/__init__.py

@@ -1,7 +1,6 @@
 """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"]
+__all__ = ["VisualMatcher", "compute_phash", "VisualSearchMixin"]

natural_pdf/vision/mixin.py

@@ -6,9 +6,6 @@ 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"""
@@ -21,11 +18,12 @@ class VisualSearchMixin:
         sizes: Optional[Union[float, Tuple, List]] = (0.8, 1.2),
         resolution: int = 72,
         hash_size: int = 20,
-        step_factor: float = 0.1,
+        step: Optional[int] = None,
+        method: str = "phash",
         max_per_page: Optional[int] = None,
         show_progress: bool = True,
         **kwargs,
-    ) -> MatchResults:
+    ) -> "MatchResults":
         """
         Find regions visually similar to the given example(s).
 
@@ -35,15 +33,19 @@ class VisualSearchMixin:
             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): search range with smart logarithmic steps (default: (0.8, 1.2))
                    - 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)
+            hash_size: Size of perceptual hash grid (default: 20)
+            step: Step size in pixels for sliding window
+            method: Matching algorithm - "phash" (default) or "template"
             max_per_page: Maximum matches to return per page
             show_progress: Show progress bar for multi-page searches (default: True)
-            **kwargs: Additional options
+            **kwargs: Additional options including:
+                mask_threshold: For both template and phash methods, pixels >= this value are masked.
+                               For template matching: pixels are ignored in matching (e.g., 0.95)
+                               For phash: pixels are replaced with median before hashing (e.g., 0.95)
 
         Returns:
             MatchResults collection
@@ -55,15 +57,25 @@ class VisualSearchMixin:
         if not isinstance(examples, list):
             examples = [examples]
 
+        from .similarity import VisualMatcher, compute_phash
+
         # Initialize matcher with specified hash size
         matcher = VisualMatcher(hash_size=hash_size)
 
         # Prepare templates
         templates = []
+        # Extract mask_threshold from kwargs for phash
+        mask_threshold = kwargs.get("mask_threshold")
+        mask_threshold_255 = (
+            int(mask_threshold * 255) if mask_threshold is not None and method == "phash" else None
+        )
+
         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)
+            template_hash = compute_phash(
+                example_image, hash_size=hash_size, mask_threshold=mask_threshold_255
+            )
             templates.append({"image": example_image, "hash": template_hash, "source": example})
 
         # Get pages to search based on the object type
@@ -76,6 +88,8 @@ class VisualSearchMixin:
             pages_to_search = self.pages
         elif hasattr(self, "number"):  # Single page
             pages_to_search = [self]
+        elif hasattr(self, "page") and hasattr(self, "bbox"):  # Region
+            pages_to_search = [self]
         else:
             raise TypeError(f"Cannot search in {type(self)}")
 
@@ -86,10 +100,16 @@ class VisualSearchMixin:
             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 search_obj in pages_to_search:
+                # Estimate image size based on object type
+                if hasattr(search_obj, "page") and hasattr(search_obj, "bbox"):
+                    # Region
+                    page_w = int(search_obj.width * resolution / 72.0)
+                    page_h = int(search_obj.height * resolution / 72.0)
+                else:
+                    # Page
+                    page_w = int(search_obj.width * resolution / 72.0)
+                    page_h = int(search_obj.height * resolution / 72.0)
 
                 for template_data in templates:
                     template_w, template_h = template_data["image"].size
@@ -99,11 +119,15 @@ class VisualSearchMixin:
                         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))
+                            # Determine step size
+                            if step is not None:
+                                actual_step = step
+                            else:
+                                # Default to 10% of template size
+                                actual_step = max(1, int(min(scaled_w, scaled_h) * 0.1))
+
+                            x_windows = len(range(0, page_w - scaled_w + 1, actual_step))
+                            y_windows = len(range(0, page_h - scaled_h + 1, actual_step))
                             total_operations += x_windows * y_windows
 
         # Search each page
@@ -124,9 +148,20 @@ class VisualSearchMixin:
                 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)
+        for page_idx, search_obj in enumerate(pages_to_search):
+            # Determine if we're searching in a page or a region
+            if hasattr(search_obj, "page") and hasattr(search_obj, "bbox"):
+                # This is a Region - render only the region area
+                region = search_obj
+                page = region.page
+                page_image = region.render(resolution=resolution, crop=True)
+                # Region offset for coordinate conversion
+                region_x0, region_y0 = region.x0, region.top
+            else:
+                # This is a Page - render the full page
+                page = search_obj
+                page_image = page.render(resolution=resolution)
+                region_x0, region_y0 = 0, 0
 
             # Convert page coordinates to image coordinates
             scale = resolution / 72.0  # PDF is 72 DPI
@@ -168,7 +203,8 @@ class VisualSearchMixin:
                     template_hash=template_hash,
                     confidence_threshold=confidence,
                     sizes=sizes,
-                    step_factor=step_factor,
+                    step=step,
+                    method=method,
                     show_progress=False,  # We handle progress ourselves
                     progress_callback=update_progress if progress_bar else None,
                     **kwargs,
@@ -180,10 +216,12 @@ class VisualSearchMixin:
 
                     # 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
+                    pdf_x0 = img_x0 / scale + region_x0
+                    pdf_y0 = img_y0 / scale + region_y0
+                    pdf_x1 = img_x1 / scale + region_x0
+                    pdf_y1 = img_y1 / scale + region_y0
+
+                    from .results import Match
 
                     # Create Match object
                     match = Match(
@@ -206,4 +244,6 @@ class VisualSearchMixin:
         if progress_bar:
             progress_bar.close()
 
+        from .results import MatchResults
+
         return MatchResults(all_matches)

natural_pdf/vision/results.py

@@ -2,7 +2,6 @@
 
 from typing import TYPE_CHECKING, Any, Iterator, List, Optional, Tuple
 
-# Import Region directly as it's a base class
 from natural_pdf.elements.region import Region
 
 if TYPE_CHECKING:
@@ -39,16 +38,41 @@ class Match(Region):
 
 
 class MatchResults:
-    """Collection of Match objects with transformation methods"""
+    """
+    Collection of Match objects with transformation methods.
+
+    Matches are automatically sorted by confidence (highest first), so:
+    - matches[0] is the best match
+    - Iteration yields matches from best to worst
+    - The .top(n) method returns the n best matches
+
+    Example:
+        >>> matches = page.find_similar(logo_region)
+        >>> print(f"Found {len(matches)} matches")
+        >>>
+        >>> # Best match
+        >>> best = matches[0]
+        >>> print(f"Best match confidence: {best.confidence:.3f}")
+        >>>
+        >>> # Top 5 matches
+        >>> for match in matches.top(5):
+        ...     print(f"Confidence: {match.confidence:.3f} at page {match.page.number}")
+        >>>
+        >>> # All matches above 90% confidence
+        >>> high_conf = matches.filter_by_confidence(0.9)
+    """
 
     def __init__(self, matches: List[Match]):
-        """Initialize with list of Match objects"""
+        """Initialize with list of Match objects, automatically sorted by confidence"""
         # Import here to avoid circular import
         from natural_pdf.elements.element_collection import ElementCollection
 
+        # Sort matches by confidence (highest first)
+        sorted_matches = sorted(matches, key=lambda m: m.confidence, reverse=True)
+
         # Create a base ElementCollection
-        self._collection = ElementCollection(matches)
-        self._matches = matches
+        self._collection = ElementCollection(sorted_matches)
+        self._matches = sorted_matches
 
     def __len__(self):
         return len(self._matches)
@@ -68,6 +92,26 @@ class MatchResults:
         """Filter matches by minimum confidence"""
         return self.filter(lambda m: m.confidence >= min_confidence)
 
+    def top(self, n: int) -> "MatchResults":
+        """
+        Get the top N matches with highest confidence.
+
+        Args:
+            n: Number of top matches to return
+
+        Returns:
+            New MatchResults with only the top N matches
+
+        Example:
+            >>> matches = page.find_similar(logo)
+            >>> best_5 = matches.top(5)
+            >>> for match in best_5:
+            ...     print(f"Confidence: {match.confidence:.3f}")
+        """
+        # Since matches are already sorted by confidence, just take first n
+        top_matches = self._matches[:n]
+        return MatchResults(top_matches)
+
     def pages(self):
         """Get unique pages containing matches"""
         # Import here to avoid circular import