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

natural_pdf/elements/element_collection.py

@@ -1673,9 +1673,9 @@ class ElementCollection(
 
         Args:
             selector: CSS-like selector string
-            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
         """
         return self.apply(lambda element: element.find(selector, **kwargs))
@@ -1685,7 +1685,7 @@ class ElementCollection(
         self,
         *,
         text: str,
-        contains: str = "all",
+        overlap: str = "full",
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -1697,7 +1697,7 @@ class ElementCollection(
         self,
         selector: str,
         *,
-        contains: str = "all",
+        overlap: str = "full",
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -1709,7 +1709,7 @@ class ElementCollection(
         selector: Optional[str] = None,
         *,
         text: Optional[str] = None,
-        contains: str = "all",
+        overlap: str = "full",
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -1724,9 +1724,9 @@ class ElementCollection(
         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 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).
@@ -1748,7 +1748,7 @@ class ElementCollection(
                 found_in_element: "ElementCollection" = element.find_all(
                     selector=selector,
                     text=text,
-                    contains=contains,
+                    overlap=overlap,
                     apply_exclusions=apply_exclusions,
                     regex=regex,
                     case=case,

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)
@@ -1982,7 +1984,7 @@ class Region(
         self,
         *,
         text: str,
-        contains: str = "all",
+        overlap: str = "full",
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -1994,7 +1996,7 @@ class Region(
         self,
         selector: str,
         *,
-        contains: str = "all",
+        overlap: str = "full",
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -2006,7 +2008,7 @@ class Region(
         selector: Optional[str] = None,  # Now optional
         *,
         text: Optional[str] = None,  # New text parameter
-        contains: str = "all",  # New parameter for containment behavior
+        overlap: str = "full",  # How elements overlap with the region
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -2020,9 +2022,9 @@ class Region(
         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 the region: '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).
@@ -2035,7 +2037,7 @@ class Region(
         elements = self.find_all(
             selector=selector,
             text=text,
-            contains=contains,
+            overlap=overlap,
             apply_exclusions=apply_exclusions,
             regex=regex,
             case=case,
@@ -2048,7 +2050,7 @@ class Region(
         self,
         *,
         text: str,
-        contains: str = "all",
+        overlap: str = "full",
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -2060,7 +2062,7 @@ class Region(
         self,
         selector: str,
         *,
-        contains: str = "all",
+        overlap: str = "full",
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -2072,7 +2074,7 @@ class Region(
         selector: Optional[str] = None,  # Now optional
         *,
         text: Optional[str] = None,  # New text parameter
-        contains: str = "all",  # New parameter to control inside/overlap behavior
+        overlap: str = "full",  # How elements overlap with the region
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -2086,9 +2088,9 @@ class Region(
         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 the region: '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).
@@ -2104,10 +2106,10 @@ class Region(
         if selector is None and text is None:
             raise ValueError("Provide either 'selector' or 'text'.")
 
-        # Validate contains parameter
-        if contains not in ["all", "any", "center"]:
+        # Validate overlap parameter
+        if overlap not in ["full", "partial", "center"]:
             raise ValueError(
-                f"Invalid contains value: {contains}. Must be 'all', 'any', or 'center'"
+                f"Invalid overlap value: {overlap}. Must be 'full', 'partial', or 'center'"
             )
 
         # Construct selector if 'text' is provided
@@ -2142,7 +2144,7 @@ class Region(
             region_bbox = self.bbox
             matching_elements = []
 
-            if contains == "all":  # Fully inside (strict)
+            if overlap == "full":  # Fully inside (strict)
                 matching_elements = [
                     el
                     for el in potential_elements
@@ -2151,9 +2153,9 @@ class Region(
                     and el.x1 <= region_bbox[2]
                     and el.bottom <= region_bbox[3]
                 ]
-            elif contains == "any":  # Any overlap
+            elif overlap == "partial":  # Any overlap
                 matching_elements = [el for el in potential_elements if self.intersects(el)]
-            elif contains == "center":  # Center point inside
+            elif overlap == "center":  # Center point inside
                 matching_elements = [
                     el for el in potential_elements if self.is_element_center_inside(el)
                 ]

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/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)

natural_pdf/vision/results.py

@@ -0,0 +1,146 @@
+"""Match results for visual similarity search"""
+
+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:
+    from natural_pdf.core.page_collection import PageCollection
+    from natural_pdf.elements.element_collection import ElementCollection
+
+
+class Match(Region):
+    """A region that was found via visual similarity search"""
+
+    def __init__(self, page, bbox, confidence, source_example=None, metadata=None):
+        """
+        Initialize a Match object.
+
+        Args:
+            page: Page containing the match
+            bbox: Bounding box of the match
+            confidence: Similarity confidence (0-1)
+            source_example: The example/template that led to this match
+            metadata: Additional metadata about the match
+        """
+        super().__init__(page, bbox)
+        self.confidence = confidence
+        self.source_example = source_example
+        self.metadata = metadata or {}
+
+    @property
+    def pdf(self):
+        """Get the PDF containing this match"""
+        return self.page.pdf
+
+    def __repr__(self):
+        return f"<Match page={self.page.number} confidence={self.confidence:.2f} bbox={self.bbox}>"
+
+
+class MatchResults:
+    """Collection of Match objects with transformation methods"""
+
+    def __init__(self, matches: List[Match]):
+        """Initialize with list of Match objects"""
+        # Import here to avoid circular import
+        from natural_pdf.elements.element_collection import ElementCollection
+
+        # Create a base ElementCollection
+        self._collection = ElementCollection(matches)
+        self._matches = matches
+
+    def __len__(self):
+        return len(self._matches)
+
+    def __iter__(self):
+        return iter(self._matches)
+
+    def __getitem__(self, key):
+        return self._matches[key]
+
+    def filter(self, filter_func) -> "MatchResults":
+        """Filter matches by a function"""
+        filtered = [m for m in self if filter_func(m)]
+        return MatchResults(filtered)
+
+    def filter_by_confidence(self, min_confidence: float) -> "MatchResults":
+        """Filter matches by minimum confidence"""
+        return self.filter(lambda m: m.confidence >= min_confidence)
+
+    def pages(self):
+        """Get unique pages containing matches"""
+        # Import here to avoid circular import
+        from natural_pdf.core.page_collection import PageCollection
+
+        # Get unique pages while preserving order
+        seen = set()
+        unique_pages = []
+        for match in self:
+            if match.page not in seen:
+                seen.add(match.page)
+                unique_pages.append(match.page)
+
+        # Attach matches to each page
+        for page in unique_pages:
+            page._matches = MatchResults([m for m in self if m.page == page])
+
+        return PageCollection(unique_pages)
+
+    def pdfs(self):
+        """Get unique PDFs containing matches"""
+        # Import here to avoid circular import
+        from natural_pdf.core.pdf_collection import PDFCollection
+
+        # Get unique PDFs while preserving order
+        seen = set()
+        unique_pdfs = []
+        for match in self:
+            if match.pdf not in seen:
+                seen.add(match.pdf)
+                unique_pdfs.append(match.pdf)
+
+        # Attach matches to each PDF
+        for pdf in unique_pdfs:
+            pdf._matches = MatchResults([m for m in self if m.pdf == pdf])
+
+        return PDFCollection(unique_pdfs)
+
+    def group_by_page(self) -> Iterator[Tuple[Any, "MatchResults"]]:
+        """Group matches by page"""
+        from itertools import groupby
+
+        # Sort by PDF filename and page number
+        sorted_matches = sorted(self, key=lambda m: (getattr(m.pdf, "filename", ""), m.page.number))
+
+        for page, matches in groupby(sorted_matches, key=lambda m: m.page):
+            yield page, MatchResults(list(matches))
+
+    def sort_by_confidence(self, descending: bool = True) -> "MatchResults":
+        """Sort matches by confidence score"""
+        sorted_matches = sorted(self, key=lambda m: m.confidence, reverse=descending)
+        return MatchResults(sorted_matches)
+
+    def regions(self):
+        """Get all matches as an ElementCollection of regions"""
+        # Import here to avoid circular import
+        from natural_pdf.elements.element_collection import ElementCollection
+
+        # Matches are already Region objects, so just wrap them
+        return ElementCollection(list(self))
+
+    def show(self, **kwargs):
+        """Show all matches using ElementCollection.show()"""
+        # Get regions and show them
+        return self.regions().show(**kwargs)
+
+    def __repr__(self):
+        if len(self) == 0:
+            return "<MatchResults: empty>"
+        elif len(self) == 1:
+            return f"<MatchResults: 1 match>"
+        else:
+            conf_range = (
+                f"{min(m.confidence for m in self):.2f}-{max(m.confidence for m in self):.2f}"
+            )
+            return f"<MatchResults: {len(self)} matches, confidence {conf_range}>"