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

natural_pdf/vision/similarity.py

@@ -0,0 +1,321 @@
+"""Visual similarity matching using perceptual hashing"""
+
+from dataclasses import dataclass
+from typing import Callable, List, Optional, Tuple, Union
+
+import numpy as np
+from PIL import Image
+from tqdm.auto import tqdm
+
+
+@dataclass
+class MatchCandidate:
+    """Candidate match during sliding window search"""
+
+    bbox: Tuple[float, float, float, float]
+    hash_value: int
+    confidence: float
+
+
+def compute_phash(image: Image.Image, hash_size: int = 8, blur_radius: float = 0) -> int:
+    """
+    Compute perceptual hash of an image using DCT.
+
+    Args:
+        image: PIL Image to hash
+        hash_size: Size of the hash (8 = 64 bit hash)
+        blur_radius: Optional blur to apply before hashing (makes more tolerant)
+
+    Returns:
+        Integer hash value
+    """
+    # Convert to grayscale
+    if image.mode != "L":
+        image = image.convert("L")
+
+    # Optional blur to reduce sensitivity to minor variations
+    if blur_radius > 0:
+        from PIL import ImageFilter
+
+        image = image.filter(ImageFilter.GaussianBlur(radius=blur_radius))
+
+    # Resize to 32x32 (4x the hash size for DCT)
+    highfreq_factor = 4
+    img_size = hash_size * highfreq_factor
+    image = image.resize((img_size, img_size), Image.Resampling.LANCZOS)
+
+    # Convert to numpy array
+    pixels = np.array(image, dtype=np.float32)
+
+    # Apply DCT
+    from scipy.fftpack import dct
+
+    dct_coef = dct(dct(pixels, axis=0), axis=1)
+
+    # Keep top-left 8x8 (low frequencies)
+    dct_low = dct_coef[:hash_size, :hash_size]
+
+    # Compute median excluding the DC component
+    dct_low_no_dc = dct_low.flatten()[1:]  # Skip first element (DC)
+    median = np.median(dct_low_no_dc)
+
+    # Create binary hash
+    diff = dct_low.flatten() > median
+
+    # Convert to integer
+    return sum(2**i for i, v in enumerate(diff) if v)
+
+
+def hamming_distance(hash1: int, hash2: int, hash_size: int = 64) -> int:
+    """Calculate Hamming distance between two hashes"""
+    # XOR and count set bits
+    xor = hash1 ^ hash2
+    return bin(xor).count("1")
+
+
+def hash_similarity(hash1: int, hash2: int, hash_size: int = 64) -> float:
+    """Calculate similarity score between two hashes (0-1)"""
+    distance = hamming_distance(hash1, hash2, hash_size)
+    return 1.0 - (distance / hash_size)
+
+
+class VisualMatcher:
+    """Handles visual similarity matching using perceptual hashing"""
+
+    def __init__(self, hash_size: int = 12):
+        self.hash_size = hash_size
+        self.hash_bits = hash_size * hash_size
+        self._cache = {}
+
+    def _get_search_scales(self, sizes: Optional[Union[float, Tuple, List]]) -> List[float]:
+        """
+        Convert various size input formats to a list of scales to search.
+
+        Args:
+            sizes: Can be:
+                - None: just 1.0
+                - float: ±percentage (e.g., 0.2 = 80%-120%)
+                - tuple(min, max): range with smart logarithmic steps
+                - tuple(min, max, step): explicit step size
+                - list: exact sizes to use
+
+        Returns:
+            List of scale factors to search
+        """
+        if sizes is None:
+            return [1.0]
+
+        # List of exact sizes
+        if isinstance(sizes, list):
+            return sorted(sizes)
+
+        # Single float: ±percentage
+        if isinstance(sizes, (int, float)):
+            if sizes <= 0:
+                return [1.0]
+            # Convert to min/max range
+            min_scale = max(0.1, 1.0 - sizes)
+            max_scale = 1.0 + sizes
+            # Use tuple logic below
+            sizes = (min_scale, max_scale)
+
+        # Tuple handling
+        if isinstance(sizes, tuple):
+            if len(sizes) == 2:
+                min_scale, max_scale = sizes
+                if min_scale >= max_scale:
+                    return [min_scale]
+
+                # Smart defaults with logarithmic spacing
+                # Calculate range ratio to determine number of steps
+                ratio = max_scale / min_scale
+
+                if ratio <= 1.5:  # Small range (e.g., 0.8-1.2)
+                    num_steps = 5
+                elif ratio <= 3.0:  # Medium range (e.g., 0.5-1.5)
+                    num_steps = 7
+                else:  # Large range (e.g., 0.5-2.0)
+                    num_steps = 9
+
+                # Generate logarithmically spaced scales
+                log_min = np.log(min_scale)
+                log_max = np.log(max_scale)
+                log_scales = np.linspace(log_min, log_max, num_steps)
+                scales = np.exp(log_scales).tolist()
+
+                # Ensure 1.0 is included if in range
+                if min_scale <= 1.0 <= max_scale and 1.0 not in scales:
+                    # Find closest scale and replace with 1.0
+                    closest_idx = np.argmin([abs(s - 1.0) for s in scales])
+                    scales[closest_idx] = 1.0
+
+                return scales
+
+            elif len(sizes) == 3:
+                # Explicit (min, max, step)
+                min_scale, max_scale, step = sizes
+                scales = []
+                current = min_scale
+                while current <= max_scale:
+                    scales.append(current)
+                    current += step
+                # Ensure max is included if close
+                if scales[-1] < max_scale and (max_scale - scales[-1]) < step * 0.1:
+                    scales[-1] = max_scale
+                return scales
+
+        raise ValueError(f"Invalid sizes format: {sizes}")
+
+    def find_matches_in_image(
+        self,
+        template: Image.Image,
+        target: Image.Image,
+        template_hash: Optional[int] = None,
+        confidence_threshold: float = 0.6,
+        step_factor: float = 0.1,
+        sizes: Optional[Union[float, Tuple, List]] = None,
+        show_progress: bool = True,
+        progress_callback: Optional[Callable[[], None]] = None,
+    ) -> List[MatchCandidate]:
+        """
+        Find all matches of template in target image using sliding window.
+
+        Args:
+            template: Template image to search for
+            target: Target image to search in
+            template_hash: Pre-computed hash of template (optional)
+            confidence_threshold: Minimum similarity score (0-1)
+            step_factor: Step size as fraction of template size
+            sizes: Size variations to search. Can be:
+                   - float: ±percentage (e.g., 0.2 = 80%-120%)
+                   - tuple(min, max): search range with smart logarithmic steps
+                   - tuple(min, max, step): explicit step size
+                   - list: exact sizes to try (e.g., [0.8, 1.0, 1.2])
+            show_progress: Show progress bar for sliding window search
+            progress_callback: Optional callback function to call for each window checked
+
+        Returns:
+            List of MatchCandidate objects
+        """
+        matches = []
+
+        # Compute template hash if not provided
+        if template_hash is None:
+            template_hash = compute_phash(template, self.hash_size)
+
+        template_w, template_h = template.size
+        target_w, target_h = target.size
+
+        # Determine scales to search
+        scales = self._get_search_scales(sizes)
+
+        # Calculate total iterations for progress bar
+        total_iterations = 0
+        if show_progress and not progress_callback:
+            for scale in scales:
+                scaled_w = int(template_w * scale)
+                scaled_h = int(template_h * scale)
+                if scaled_w <= target_w and scaled_h <= target_h:
+                    step_x = max(1, int(scaled_w * step_factor))
+                    step_y = max(1, int(scaled_h * step_factor))
+                    x_steps = len(range(0, target_w - scaled_w + 1, step_x))
+                    y_steps = len(range(0, target_h - scaled_h + 1, step_y))
+                    total_iterations += x_steps * y_steps
+
+        # Setup progress bar if needed (only if no callback provided)
+        progress_bar = None
+        if show_progress and not progress_callback and total_iterations > 0:
+            progress_bar = tqdm(total=total_iterations, desc="Scanning", unit="window", leave=False)
+
+        # Search at each scale
+        for scale in scales:
+            # Scale template size
+            scaled_w = int(template_w * scale)
+            scaled_h = int(template_h * scale)
+
+            if scaled_w > target_w or scaled_h > target_h:
+                continue
+
+            # Calculate step size
+            step_x = max(1, int(scaled_w * step_factor))
+            step_y = max(1, int(scaled_h * step_factor))
+
+            # Sliding window search
+            for y in range(0, target_h - scaled_h + 1, step_y):
+                for x in range(0, target_w - scaled_w + 1, step_x):
+                    # Extract window
+                    window = target.crop((x, y, x + scaled_w, y + scaled_h))
+
+                    # Resize to template size if scaled
+                    if scale != 1.0:
+                        window = window.resize((template_w, template_h), Image.Resampling.LANCZOS)
+
+                    # Compute hash and similarity
+                    window_hash = compute_phash(window, self.hash_size)
+                    similarity = hash_similarity(template_hash, window_hash, self.hash_bits)
+
+                    if similarity >= confidence_threshold:
+                        # Convert back to target image coordinates
+                        bbox = (x, y, x + scaled_w, y + scaled_h)
+                        matches.append(MatchCandidate(bbox, window_hash, similarity))
+
+                    # Update progress
+                    if progress_bar:
+                        progress_bar.update(1)
+                    elif progress_callback:
+                        progress_callback()
+
+        # Close progress bar
+        if progress_bar:
+            progress_bar.close()
+
+        # Remove overlapping matches (keep highest confidence)
+        return self._filter_overlapping_matches(matches)
+
+    def _filter_overlapping_matches(
+        self, matches: List[MatchCandidate], overlap_threshold: float = 0.5
+    ) -> List[MatchCandidate]:
+        """Remove overlapping matches, keeping the highest confidence ones"""
+        if not matches:
+            return matches
+
+        # Sort by confidence (highest first)
+        sorted_matches = sorted(matches, key=lambda m: m.confidence, reverse=True)
+        filtered = []
+
+        for candidate in sorted_matches:
+            # Check if this overlaps significantly with any already selected match
+            keep = True
+            for selected in filtered:
+                overlap = self._calculate_overlap(candidate.bbox, selected.bbox)
+                if overlap > overlap_threshold:
+                    keep = False
+                    break
+
+            if keep:
+                filtered.append(candidate)
+
+        return filtered
+
+    def _calculate_overlap(self, bbox1: Tuple, bbox2: Tuple) -> float:
+        """Calculate intersection over union (IoU) for two bboxes"""
+        x1_min, y1_min, x1_max, y1_max = bbox1
+        x2_min, y2_min, x2_max, y2_max = bbox2
+
+        # Calculate intersection
+        intersect_xmin = max(x1_min, x2_min)
+        intersect_ymin = max(y1_min, y2_min)
+        intersect_xmax = min(x1_max, x2_max)
+        intersect_ymax = min(y1_max, y2_max)
+
+        if intersect_xmax < intersect_xmin or intersect_ymax < intersect_ymin:
+            return 0.0
+
+        intersect_area = (intersect_xmax - intersect_xmin) * (intersect_ymax - intersect_ymin)
+
+        # Calculate union
+        area1 = (x1_max - x1_min) * (y1_max - y1_min)
+        area2 = (x2_max - x2_min) * (y2_max - y2_min)
+        union_area = area1 + area2 - intersect_area
+
+        return intersect_area / union_area if union_area > 0 else 0.0

{natural_pdf-0.2.2.dist-info → natural_pdf-0.2.4.dist-info}/METADATA

@@ -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.dist-info → natural_pdf-0.2.4.dist-info}/RECORD

@@ -23,28 +23,28 @@ natural_pdf/analyzers/layout/yolo.py,sha256=2Iz2-WsMy--ftkZQ8j5PGqp_1fTD7Mskl2kN
 natural_pdf/classification/manager.py,sha256=BaqBL9GeMvYgoJsiQeI2J8aUKQ5Qxu_ELRvmCWquld8,22172
 natural_pdf/classification/mixin.py,sha256=CXygXXhe_qx1563SmIjiu4uSnZkxCkuRR4fGvLokS2w,9416
 natural_pdf/classification/results.py,sha256=5ha77CxK0GYwkBMJbvUBZkBjsL5GpOveIZDK9nO4j8I,3239
-natural_pdf/collections/mixins.py,sha256=u4KtnlUZZYQ74e0OXAniOv9RtuA6FhwBxsLMJLjdbpQ,5169
+natural_pdf/collections/mixins.py,sha256=Se2C5AcpP9B5E0d0pIrey6-f_P32tAXTK4M7666MNj0,5688
 natural_pdf/core/__init__.py,sha256=QC8H4M3KbXwMFiQORZ0pdPlzx1Ix6oKKQSS7Ib2KEaA,38
 natural_pdf/core/element_manager.py,sha256=DRZvntd99wjXy6KeDjCq5uRhjMftZop9QklOZqlUH8M,55349
-natural_pdf/core/highlighting_service.py,sha256=mhHEomIlHQM1lVmEcUMJ4xtHsvCRb3rMroW1d1Gqs-M,67942
-natural_pdf/core/page.py,sha256=M_V0IXahopIN45ENmvIm4m_WdnrjYECmXe7xhUQtjQI,142455
-natural_pdf/core/page_collection.py,sha256=coVUsp4uLR2GImLbuGFpBIYcU952eJLfBQNgTmkOSzU,52486
+natural_pdf/core/highlighting_service.py,sha256=7on8nErhi50CEH2L4XzGIZ6tIqZtMzmmFlp-2lmwnYE,68856
+natural_pdf/core/page.py,sha256=XrDePXZgXgB3w8hvxh4-EhPQnrwmw-0z-I_K24__OtY,142550
+natural_pdf/core/page_collection.py,sha256=hEeXs_fzB73XZ8ZkHz2kIuSgBYcVYydvGMMdGuB1rvw,52486
 natural_pdf/core/page_groupby.py,sha256=550ME6kd-h-2u75oUIIIqTYsmh8VvdQO1nXXioL8J6A,7378
-natural_pdf/core/pdf.py,sha256=q54DyhXwAS_zAmsBd3PsCezu1wyQOYmGmB3iKfP8gAM,101884
-natural_pdf/core/pdf_collection.py,sha256=8tM0qVWS1L5Hwv5cXuZ2X8znAYOjKmlERX62bksDlJU,30144
-natural_pdf/core/render_spec.py,sha256=SgT6bHR3yduZ_-JhFWRFmakUD74NPQJ8q1lY6iB3prQ,12916
+natural_pdf/core/pdf.py,sha256=Loe6sbQzBp9VDeIAuDS3zQmeDWvQMj5SWIQMky5bPDA,101964
+natural_pdf/core/pdf_collection.py,sha256=s3ogu4CEHrHMTRqQMJUKJZ-9Ii8b_B9dWbVLTFj0s7g,34992
+natural_pdf/core/render_spec.py,sha256=rLicaS9EPyojpJcjy2Lzn5DLWQwjrFyDJyRo7jbjdGU,14505
 natural_pdf/describe/__init__.py,sha256=kIV7ORmWWB1SAur7nK2aAwR-wHqSedhKfUsaUl4hG0A,586
 natural_pdf/describe/base.py,sha256=Of9WVo9XuShXoeyJr0RN2CpLhF_CeiOjazl-or53RKU,18173
 natural_pdf/describe/elements.py,sha256=JicXC9SJmmasqxalpCXA47-kVwv-6JnR3Xiu778aNHM,12634
 natural_pdf/describe/mixin.py,sha256=rkX14aGrSz7Jvxx8Rbxv3eSfbO-_29DipwpstrV2pDQ,3109
 natural_pdf/describe/summary.py,sha256=cfT4ZQkeatCDAOwWPwhtEVXisNgk6E57fAXAnoRysSU,7645
 natural_pdf/elements/__init__.py,sha256=ICNikmLeIEuSYypz-KnkBn8xR1hR7rge4hsa1KLkyWY,42
-natural_pdf/elements/base.py,sha256=WUwYDzeeGNkr26lWKm8PqGlW9WQIPoteWYIpvlcxTrs,53939
-natural_pdf/elements/element_collection.py,sha256=uQoZ2GFCnru0LCiv5zr6wIu2IWgM0j2m44qjsJPNPbk,101340
+natural_pdf/elements/base.py,sha256=aj-eXOQQlhKv9lYeUlUs9aKNcUebtG_dqxURZHZVZ58,55509
+natural_pdf/elements/element_collection.py,sha256=slCUnOT04sNOTjSGgmhjcCKKPVPtdDPwU7PX1ebzGMw,101342
 natural_pdf/elements/image.py,sha256=zu-P2Y8fRoEXf6IeZU0EYRWsgZ6I_a5vy1FA3VXTGkQ,1424
 natural_pdf/elements/line.py,sha256=TFn7KXjPT_jUQyQyabU0F7XYU4dC-qadwodJMZF4DCU,3844
 natural_pdf/elements/rect.py,sha256=0lNkVkPkvbRbrFED856RXoUcTcDkeeOIs5xldKGAQT8,3324
-natural_pdf/elements/region.py,sha256=ClL2vxx2aVoAecaAlkUDZ2ygvUiP8oTa-xfIclm2Eg8,155286
+natural_pdf/elements/region.py,sha256=RxWidI7oNrdbuuj94SfdFXmcSDTfy89uGCeVMQvAfks,155591
 natural_pdf/elements/text.py,sha256=829uSJv9E-8cC6T6iR_Va7Xtv54pJoyRN78fq4NN1d4,20687
 natural_pdf/export/mixin.py,sha256=L1q3MIEFWuvie4j4_EmW7GT3NerbZ1as0XMUoqTS7gM,5083
 natural_pdf/exporters/__init__.py,sha256=QffoARekR6WzXEd05oxOytly4qPdBizuIF-SUkeFpig,643
@@ -100,9 +100,13 @@ natural_pdf/utils/packaging.py,sha256=TM0jafwS5yVbTGC-RMi4TyWunf9cUUo9h5J6rMzkT-
 natural_pdf/utils/reading_order.py,sha256=u7XyVZdKMPMK0CL1C7xFogKnZ92b0JKT068KFjQWe18,7437
 natural_pdf/utils/text_extraction.py,sha256=CCwPTmMoTgtQt2P00X_ADIf6ZGNfxvjCO9FO0_HqG40,13900
 natural_pdf/utils/visualization.py,sha256=zhZEHgYnZFuX7YxTHXF8Y3D97uHp2beTKMaC-JkCFwk,22364
+natural_pdf/vision/__init__.py,sha256=RymMY-3WLQBlOZ4Dx4MmL9UH6I65hNjkwUJ7ymO5JfM,287
+natural_pdf/vision/mixin.py,sha256=OJwBABr74TWxP5seTKUmGj5zE9mWsBP_UKWU-Pr8V9A,8720
+natural_pdf/vision/results.py,sha256=F2zXG3MVZIpOUvPkJHotOq6-9rFz68BaO_8pnSndlOs,5119
+natural_pdf/vision/similarity.py,sha256=YH8legN-t9uf1b_XULi4JLNDaRfPNKQwU1FZ4Qu08jY,11740
 natural_pdf/widgets/__init__.py,sha256=QTVaUmsw__FCweFYZebwPssQxxUFUMd0wpm_cUbGZJY,181
 natural_pdf/widgets/viewer.py,sha256=KW3JogdR2TMg2ECUMYp8hwd060hfg8EsYBWxb5IEzBY,24942
-natural_pdf-0.2.2.dist-info/licenses/LICENSE,sha256=9zfwINwJlarbDmdh6iJV4QUG54QSJlSAUcnC1YiC_Ns,1074
+natural_pdf-0.2.4.dist-info/licenses/LICENSE,sha256=9zfwINwJlarbDmdh6iJV4QUG54QSJlSAUcnC1YiC_Ns,1074
 optimization/memory_comparison.py,sha256=0i_foFSRmppj-fY069qjwH36s_zkx-1L2ASAAlepWzA,6541
 optimization/pdf_analyzer.py,sha256=HjrmTgu2qchxPeDckc5kjgxppGwd40UESrYS9Myj7pY,19352
 optimization/performance_analysis.py,sha256=JBXnR9hc7Ix7YCnt3EJPSpsyqIUgKsc7GEffQ_TDCBk,13033
@@ -119,8 +123,8 @@ tools/bad_pdf_eval/llm_enrich.py,sha256=mCh4KGi1HmIkzGjj5rrHz1Osd7sEX1IZ_FW08H1t
 tools/bad_pdf_eval/llm_enrich_with_retry.py,sha256=XUtPF1hUvqd3frDXT0wDTXoonuAivhjM5vgFdZ-tm0A,9373
 tools/bad_pdf_eval/reporter.py,sha256=e1g__mkSB4q02p3mGWOwMhvFs7F2HJosNBxup0-LkyU,400
 tools/bad_pdf_eval/utils.py,sha256=hR95XQ7qf7Cu6BdyX0L7ggGVx-ah5sK0jHWblTJUUic,4896
-natural_pdf-0.2.2.dist-info/METADATA,sha256=uLGyhgV-iSjcvpvaj9s8ArQUzg1UTAF6bPXTf4BuZSE,6959
-natural_pdf-0.2.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-natural_pdf-0.2.2.dist-info/entry_points.txt,sha256=1R_KMv7g60UBBpRqGfw7bppsMNGdayR-iJlb9ohEk_8,81
-natural_pdf-0.2.2.dist-info/top_level.txt,sha256=80t0F2ZeX4vN4Ke5iTflcOk_PN_0USn33ha3X6X86Ik,36
-natural_pdf-0.2.2.dist-info/RECORD,,
+natural_pdf-0.2.4.dist-info/METADATA,sha256=G1tmes61GVEt6zLeDISuJZgceLQywIU-uRspGA_90Q8,6959
+natural_pdf-0.2.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+natural_pdf-0.2.4.dist-info/entry_points.txt,sha256=1R_KMv7g60UBBpRqGfw7bppsMNGdayR-iJlb9ohEk_8,81
+natural_pdf-0.2.4.dist-info/top_level.txt,sha256=80t0F2ZeX4vN4Ke5iTflcOk_PN_0USn33ha3X6X86Ik,36
+natural_pdf-0.2.4.dist-info/RECORD,,