natural-pdf 0.2.17__tar.gz → 0.2.19__tar.gz

natural_pdf-0.2.19/CHECKBOX_DETECTION.md

@@ -0,0 +1,172 @@
+# Checkbox Detection in Natural PDF
+
+Natural PDF now includes built-in checkbox detection using computer vision models. This feature can automatically detect checkboxes in PDF documents and determine whether they are checked or unchecked.
+
+## Quick Start
+
+```python
+import natural_pdf as npdf
+
+# Load PDF and detect checkboxes
+pdf = npdf.PDF("form.pdf")
+checkboxes = pdf[0].detect_checkboxes()
+
+# Check results
+for cb in checkboxes:
+    print(f"Checkbox at {cb.bbox}: {'✓' if cb.is_checked else '✗'}")
+```
+
+## Features
+
+### 1. Basic Detection
+```python
+# Detect all checkboxes on a page
+checkboxes = page.detect_checkboxes()
+
+# Access checkbox properties
+checkbox = checkboxes[0]
+print(checkbox.is_checked)      # True/False
+print(checkbox.checkbox_state)  # "checked"/"unchecked"
+print(checkbox.confidence)      # Detection confidence (0-1)
+```
+
+### 2. Using Selectors
+```python
+# Find checked/unchecked boxes
+checked = page.find_all('checkbox:checked')
+unchecked = page.find_all('checkbox:unchecked')
+
+# All checkboxes
+all_checkboxes = page.find_all('checkbox')
+
+# By attributes (note: use is_checked, not checked)
+checked = page.find_all('checkbox[is_checked=true]')
+```
+
+### 3. Limited Detection
+When you know the expected number of checkboxes:
+```python
+# Get top 10 checkboxes by confidence
+checkboxes = page.detect_checkboxes(limit=10)
+```
+
+### 4. Multi-level Detection
+```python
+# Entire PDF
+all_checkboxes = pdf.detect_checkboxes()
+
+# Page collection
+pages = pdf[0:5]
+checkboxes = pages.detect_checkboxes()
+
+# Within a region
+region = page.find('text:contains("Options")').below()
+checkboxes = region.detect_checkboxes()
+```
+
+### 5. Visualization
+```python
+# Show detected checkboxes
+checkboxes.show()
+
+# Checkboxes display their state in repr
+print(checkboxes[0])
+# <Region type='checkbox' [checked] bbox=(100, 200, 120, 220)>
+```
+
+## Advanced Configuration
+
+### Custom Detection Options
+```python
+from natural_pdf.analyzers.checkbox import CheckboxOptions
+
+# Higher confidence threshold (default is 0.05)
+options = CheckboxOptions(confidence=0.5)
+checkboxes = page.detect_checkboxes(options=options)
+
+# Different resolution (default is 150 DPI)
+checkboxes = page.detect_checkboxes(resolution=300)
+
+# GPU acceleration
+checkboxes = page.detect_checkboxes(device='cuda')
+```
+
+### Custom Models
+```python
+# Use a different checkbox detection model
+options = CheckboxOptions(
+    model_repo="your-org/your-checkbox-model",
+    label_mapping={
+        "empty_box": "unchecked",
+        "ticked_box": "checked",
+    }
+)
+checkboxes = page.detect_checkboxes(options=options)
+```
+
+### Disable Text Filtering
+```python
+# If your checkboxes contain text for some reason
+checkboxes = page.detect_checkboxes(reject_with_text=False)
+
+# Or with options
+options = CheckboxOptions(reject_with_text=False)
+checkboxes = page.detect_checkboxes(options=options)
+```
+
+## Implementation Details
+
+- **Default Model**: Uses `wendys-llc/rtdetr-v2-r50-chkbx` RT-DETR model
+- **Low Confidence**: Default confidence is 0.02 (very low to catch all checkboxes)
+- **Resolution**: Renders at 150 DPI by default for efficiency
+- **No Overlaps**: Aggressive NMS rejects ANY overlapping detections
+- **Text Filtering**: Automatically rejects detections containing text (real checkboxes should be empty)
+- **Architecture**: Follows the same pattern as layout detection for consistency
+
+## Common Use Cases
+
+### Form Processing
+```python
+# Extract form checkbox states
+form_data = {}
+for cb in page.detect_checkboxes():
+    # Find nearby text label
+    label = cb.left('text').extract_text() or cb.above('text').extract_text()
+    form_data[label] = cb.is_checked
+```
+
+### Validation
+```python
+# Ensure all required checkboxes are checked
+required = ["Terms", "Privacy", "Age"]
+checkboxes = page.detect_checkboxes()
+
+for req in required:
+    cb = page.find(f'text:contains("{req}")').right('checkbox:first')
+    if not cb or not cb.is_checked:
+        print(f"Warning: {req} not checked!")
+```
+
+### Batch Processing
+```python
+# Process multiple forms
+for pdf_path in pdf_files:
+    pdf = npdf.PDF(pdf_path)
+    results = []
+
+    for page in pdf.pages:
+        checkboxes = page.detect_checkboxes(limit=20)
+        checked_count = len([cb for cb in checkboxes if cb.is_checked])
+        results.append({
+            'page': page.number,
+            'total': len(checkboxes),
+            'checked': checked_count
+        })
+```
+
+## Troubleshooting
+
+1. **No checkboxes detected**: Try lowering confidence threshold
+2. **Too many false positives**: Increase confidence threshold
+3. **Missing transformers**: Install with `pip install transformers torch`
+4. **Selector syntax**: Use `:checked`/`:unchecked` or `[is_checked=true]`

{natural_pdf-0.2.17 → natural_pdf-0.2.19}/CLAUDE.md

@@ -96,3 +96,4 @@ Natural PDF is a Python library for intelligent PDF document processing that com
 ### Environment and Tooling
 - Always use the virtual environment in .venv
 - Use uv when possible for efficient package management
+- Don't create new PDFs for testing, just use pdfs/01-practice.pdf.

{natural_pdf-0.2.17/natural_pdf.egg-info → natural_pdf-0.2.19}/PKG-INFO

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

{natural_pdf-0.2.17 → natural_pdf-0.2.19}/docs/element-selection/index.md

@@ -117,6 +117,7 @@ These are powerful filters that let you find elements based on their content or
 | Pseudo-Class          | Example                           | What It Finds |
 |-----------------------|-----------------------------------|---------------|
 | `:contains('text')` | `text:contains('Report')`       | Elements containing specific text |
+| `:closest('text')`  | `text:closest('Invoice Date')`    | Fuzzy text matching (great for OCR errors) |
 | `:bold`               | `text:bold`                       | Bold text (detected automatically) |
 | `:italic`             | `text:italic`                     | Italic text |
 | `:strike`             | `text:strike`                     | Struck-through text |
@@ -187,6 +188,34 @@ page.find_all('text:contains("INS-\\w+")', regex=True)
 page.find_all('text:contains("jungle health")', regex=True, case=False)
 ```
 
+### Fuzzy Text Matching for OCR Errors
+
+When working with OCR'd PDFs, text recognition isn't always perfect. The `:closest()` pseudo-class helps you find text even when it contains errors:
+
+```python
+# Find "Invoice Date" even if OCR read it as "Invice Date" or "Invoice Dat"
+page.find('text:closest("Invoice Date")')
+
+# Specify a similarity threshold (0.0 to 1.0)
+# 0.8 = 80% similar
+page.find_all('text:closest("Date of Review@0.8")')
+
+# Default threshold is 0.0 - returns all text sorted by similarity
+# Exact substring matches always come first
+all_sorted = page.find_all('text:closest("Durham")')
+```
+
+The `:closest()` selector is particularly useful for:
+- OCR errors like "rn" read as "m" (Durharn → Durham)
+- Missing punctuation (Date: → Date)
+- Character confusion (l/I, 0/O)
+- Partial matches when you're not sure of the exact text
+
+```python
+# Combine with other selectors for more precision
+page.find('text:closest("Total Amount@0.7")[size>12]')
+```
+
 ## Working with Groups of Elements
 
 `find_all()` returns an `ElementCollection` - like a list, but with PDF-specific superpowers.
@@ -221,6 +250,22 @@ service_headings = headings.filter(lambda heading: 'Service' in heading.extract_
 headings.extract_text()
 ```
 
+### Applying Functions to Collections
+
+The `.apply()` method lets you transform each element in a collection. It preserves the collection type even when results are empty:
+
+```python
+# Apply a function to each element
+uppercase_texts = texts.apply(lambda t: t.extract_text().upper())
+
+# Navigate from each element - returns an ElementCollection
+regions_below = headings.apply(lambda h: h.below())
+
+# Even empty results maintain the collection type
+empty_collection = page.find_all('nonexistent').apply(lambda x: x.expand(10))
+# Returns ElementCollection([]) not []
+```
+
 *Note: `.highest()`, `.lowest()`, etc. will complain if your collection spans multiple pages.*
 
 ## Finding Elements with Statistical Properties

{natural_pdf-0.2.17 → natural_pdf-0.2.19}/docs/layout-analysis/index.md

@@ -207,6 +207,64 @@ regions = page.analyze_layout(engine="gemini", options=options)
 - The client must be compatible with the OpenAI API (see the `openai` Python package).
 - This feature is intended for advanced users who need LLM-based layout analysis.
 
+## Using Judge for Visual Classification
+
+Natural PDF includes a `Judge` class that can learn to classify visual elements like checkboxes. This is particularly useful after layout detection when you need to determine the state of detected elements.
+
+### Example: Checkbox Classification
+
+```python
+from natural_pdf import Judge
+
+# Create a judge for checkbox classification
+judge = Judge("form_checkboxes", labels=["checked", "unchecked"])
+
+# Train with examples
+checked_region = page.find("text=Acceptable").left(width=20)
+unchecked_region = page.find("text=Deficient").left(width=20)
+
+judge.add(checked_region, "checked")
+judge.add(unchecked_region, "unchecked")
+
+# Classify new checkboxes
+new_checkbox = page.find("text=At-Risk").left(width=20)
+result = judge.decide(new_checkbox)
+print(f"Checkbox is: {result.label} (confidence: {result.score:.2f})")
+
+# Find which checkbox is selected among multiple options
+checkboxes = [
+    page.find("text=Option A").left(width=20),
+    page.find("text=Option B").left(width=20),
+    page.find("text=Option C").left(width=20)
+]
+selected = judge.pick("checked", checkboxes, labels=["Option A", "Option B", "Option C"])
+print(f"Selected: {selected.label}")
+```
+
+### Key Features of Judge
+
+1. **Simple Training**: Requires minimal examples (even just one per class)
+2. **Robust to Imbalance**: Uses Youden's J weights and prior correction
+3. **Interactive Teaching**: Use `judge.teach()` in Jupyter for labeling
+4. **Visual Inspection**: Use `judge.inspect()` to see predictions on training data
+5. **Persistence**: Save/load trained judges with `judge.save()` and `Judge.load()`
+
+### Advanced Usage
+
+```python
+# Adjust prior if you expect more checked boxes
+judge = Judge("checkboxes", labels=["checked", "unchecked"], target_prior=0.7)
+
+# Interactive teaching in Jupyter
+judge.teach()  # Use arrow keys to label examples
+
+# Visual inspection with previews
+judge.inspect(preview=True)  # Shows HTML table with images
+
+# Count checkboxes by type
+checked_count = judge.count("checked", checkbox_regions)
+```
+
 ## Next Steps
 
 Layout analysis provides regions that you can use for:
@@ -214,3 +272,4 @@ Layout analysis provides regions that you can use for:
 - [Table Extraction](../tables/index.ipynb): Especially powerful with TATR regions.
 - [Text Extraction](../text-extraction/index.ipynb): Extract text only from specific region types (e.g., paragraphs).
 - [Document QA](../document-qa/index.ipynb): Focus question answering on specific detected regions.
+- Visual Classification: Use Judge to classify detected elements (checkboxes, signatures, etc.)

{natural_pdf-0.2.17 → natural_pdf-0.2.19}/docs/quick-reference/index.md

@@ -40,6 +40,8 @@ data = table_region.extract_table()
 page.find('text:contains("Invoice")')           # Contains text
 page.find('text:contains("total")', case=False) # Case insensitive
 page.find('text:contains("\\d+")', regex=True)  # Regex pattern
+page.find('text:closest("Invoice Date")')       # Fuzzy match (OCR errors)
+page.find('text:closest("Total@0.8")')          # 80% similarity threshold
 ```
 
 ### Text Formatting

natural_pdf-0.2.19/example_checkbox_usage.py

@@ -0,0 +1,55 @@
+"""Example usage of checkbox detection in Natural PDF."""
+
+import natural_pdf as npdf
+
+# Load a PDF
+pdf = npdf.PDF("pdfs/01-practice.pdf")
+page = pdf[0]
+
+# Basic checkbox detection
+print("=== Basic Checkbox Detection ===")
+checkboxes = page.detect_checkboxes()
+print(f"Found {len(checkboxes)} checkboxes")
+
+# Show what was found
+for i, cb in enumerate(checkboxes[:3]):
+    print(f"\nCheckbox {i}:")
+    print(f"  State: {'Checked' if cb.is_checked else 'Unchecked'}")
+    print(f"  Confidence: {cb.confidence:.2f}")
+    print(f"  Position: {cb.bbox}")
+
+# Using selectors to filter checkboxes
+print("\n=== Using Selectors ===")
+checked = page.find_all("checkbox:checked")
+unchecked = page.find_all("checkbox:unchecked")
+print(f"Checked boxes: {len(checked)}")
+print(f"Unchecked boxes: {len(unchecked)}")
+
+# Limit detection when you know expected count
+print("\n=== Limited Detection ===")
+# If you know there should be 10 checkboxes on a form
+limited_checkboxes = page.detect_checkboxes(limit=10)
+print(f"Found top {len(limited_checkboxes)} checkboxes by confidence")
+
+# Multi-page detection
+print("\n=== Multi-page Detection ===")
+all_checkboxes = pdf.detect_checkboxes(show_progress=False)
+print(f"Total checkboxes in PDF: {len(all_checkboxes)}")
+
+# Visualize checkboxes
+print("\n=== Visualization ===")
+print("Showing detected checkboxes...")
+checkboxes.show()
+
+# Advanced: Using custom options
+print("\n=== Advanced Options ===")
+from natural_pdf.analyzers.checkbox import CheckboxOptions
+
+# Higher confidence threshold
+options = CheckboxOptions(confidence=0.5)
+high_conf_checkboxes = page.detect_checkboxes(options=options)
+print(f"High confidence checkboxes: {len(high_conf_checkboxes)}")
+
+# GPU acceleration if available
+gpu_checkboxes = page.detect_checkboxes(device="cuda")
+print(f"GPU-detected checkboxes: {len(gpu_checkboxes)}")

{natural_pdf-0.2.17 → natural_pdf-0.2.19}/natural_pdf/__init__.py

@@ -66,6 +66,7 @@ class Options:
         self.layout = ConfigSection(
             directional_offset=0.01,  # Offset in points when using directional methods
             auto_multipage=False,  # Whether directional methods span pages by default
+            directional_within=None,  # Region to constrain directional operations to
         )
 
 
@@ -126,6 +127,9 @@ from natural_pdf.elements.region import Region
 from natural_pdf.flows.flow import Flow
 from natural_pdf.flows.region import FlowRegion
 
+# Judge for visual classification
+from natural_pdf.judge import Decision, Judge, JudgeError, PickResult
+
 # Search options (if extras installed)
 try:
     from natural_pdf.search.search_options import (
@@ -165,6 +169,10 @@ __all__ = [
     "Flow",
     "FlowRegion",
     "Guides",
+    "Judge",
+    "Decision",
+    "PickResult",
+    "JudgeError",
     "TextSearchOptions",
     "MultiModalSearchOptions",
     "BaseSearchOptions",

natural_pdf-0.2.19/natural_pdf/analyzers/checkbox/__init__.py

@@ -0,0 +1,6 @@
+"""Checkbox detection analyzers for natural-pdf."""
+
+from .checkbox_manager import CheckboxManager
+from .checkbox_options import CheckboxOptions, RTDETRCheckboxOptions
+
+__all__ = ["CheckboxManager", "CheckboxOptions", "RTDETRCheckboxOptions"]

natural_pdf-0.2.19/natural_pdf/analyzers/checkbox/base.py

@@ -0,0 +1,265 @@
+"""Base class for checkbox detection engines."""
+
+import logging
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Set
+
+from PIL import Image
+
+from .checkbox_options import CheckboxOptions
+
+logger = logging.getLogger(__name__)
+
+
+class CheckboxDetector(ABC):
+    """Abstract base class for checkbox detection engines.
+
+    This class defines the standard interface that all checkbox detection engines
+    must implement in natural-pdf. Checkbox detectors analyze document images to
+    identify checkboxes and their states (checked/unchecked).
+
+    Subclasses must implement:
+    - detect(): Core checkbox detection for a single image
+    - is_available(): Check if engine dependencies are installed
+    - _load_model_from_options(): Load and configure the detection model
+    - _get_cache_key(): Generate cache keys for model instances
+
+    Attributes:
+        logger: Logger instance for the specific detector.
+        _model_cache: Dictionary cache for loaded model instances.
+    """
+
+    def __init__(self):
+        """Initialize the base checkbox detector."""
+        self.logger = logging.getLogger(f"{__name__}.{self.__class__.__name__}")
+        self.logger.info(f"Initializing {self.__class__.__name__}")
+        self._model_cache: Dict[str, Any] = {}  # Cache for initialized models
+
+    @abstractmethod
+    def detect(self, image: Image.Image, options: CheckboxOptions) -> List[Dict[str, Any]]:
+        """
+        Detect checkboxes in a given PIL Image.
+
+        Args:
+            image: PIL Image of the page/region to analyze.
+            options: Instance of CheckboxOptions with configuration.
+
+        Returns:
+            List of detection dictionaries with:
+            - 'bbox': Tuple[float, float, float, float] - (x0, y0, x1, y1) relative to image
+            - 'class': str - Original class name from model (e.g., 'checkbox', 'checked_checkbox')
+            - 'normalized_class': str - Always 'checkbox'
+            - 'is_checked': bool - Whether checkbox is checked
+            - 'checkbox_state': str - 'checked' or 'unchecked'
+            - 'confidence': float - Confidence score (0.0-1.0)
+            - 'model': str - Name of the model used
+            - 'source': str - Always 'checkbox'
+        """
+        raise NotImplementedError("Subclasses must implement this method")
+
+    @classmethod
+    @abstractmethod
+    def is_available(cls) -> bool:
+        """
+        Check if the detector's dependencies are installed and usable.
+
+        Returns:
+            True if the detector is available, False otherwise.
+        """
+        raise NotImplementedError("Subclasses must implement this method")
+
+    def _get_cache_key(self, options: CheckboxOptions) -> str:
+        """
+        Generate a cache key for model loading based on relevant options.
+
+        Args:
+            options: The options dataclass instance.
+
+        Returns:
+            A string cache key.
+        """
+        # Base key includes device, subclasses should add model specifics
+        device_key = str(options.device).lower()
+        return f"{self.__class__.__name__}_{device_key}"
+
+    def _get_model(self, options: CheckboxOptions) -> Any:
+        """
+        Get or initialize the underlying model based on options, using caching.
+        """
+        cache_key = self._get_cache_key(options)
+        if cache_key not in self._model_cache:
+            self.logger.info(f"Loading model for cache key: {cache_key}")
+            try:
+                # Ensure dependencies are met before loading
+                if not self.is_available():
+                    raise RuntimeError(f"{self.__class__.__name__} dependencies are not met.")
+                self._model_cache[cache_key] = self._load_model_from_options(options)
+                self.logger.info(f"Model loaded successfully for key: {cache_key}")
+            except Exception as e:
+                self.logger.error(f"Failed to load model for key {cache_key}: {e}", exc_info=True)
+                # Remove potentially corrupted cache entry
+                self._model_cache.pop(cache_key, None)
+                raise
+        else:
+            self.logger.debug(f"Using cached model for key: {cache_key}")
+        return self._model_cache[cache_key]
+
+    @abstractmethod
+    def _load_model_from_options(self, options: CheckboxOptions) -> Any:
+        """
+        Load and configure the detection model based on provided options.
+
+        Args:
+            options: The options dataclass instance.
+
+        Returns:
+            The loaded model object(s).
+        """
+        raise NotImplementedError("Subclasses must implement _load_model_from_options")
+
+    def _map_label_to_state(self, label: str, options: CheckboxOptions) -> tuple[bool, str]:
+        """
+        Map model output label to checkbox state.
+
+        Args:
+            label: Raw label from model (e.g., 'checked_checkbox', '1')
+            options: Options containing label mapping
+
+        Returns:
+            Tuple of (is_checked: bool, state: str)
+        """
+        # Normalize label
+        normalized_label = str(label).lower().strip()
+
+        # Check mapping
+        if normalized_label in options.label_mapping:
+            state = options.label_mapping[normalized_label]
+            is_checked = state == "checked"
+            return is_checked, state
+
+        # Default heuristic if not in mapping
+        if any(term in normalized_label for term in ["checked", "tick", "filled", "1"]):
+            return True, "checked"
+        else:
+            return False, "unchecked"
+
+    def _apply_nms(
+        self, detections: List[Dict[str, Any]], iou_threshold: float
+    ) -> List[Dict[str, Any]]:
+        """
+        Apply non-maximum suppression to remove overlapping detections.
+        For checkboxes, we reject ANY meaningful overlap.
+
+        Args:
+            detections: List of detection dictionaries
+            iou_threshold: IoU threshold for suppression (ignored for checkboxes - we use stricter rules)
+
+        Returns:
+            Filtered list of detections
+        """
+        if not detections:
+            return detections
+
+        # Sort by confidence (descending), then by area (ascending) to prefer smaller boxes
+        def sort_key(det):
+            bbox = det["bbox"]
+            area = (bbox[2] - bbox[0]) * (bbox[3] - bbox[1])
+            return (-det["confidence"], area)
+
+        sorted_detections = sorted(detections, key=sort_key)
+
+        keep = []
+        for i, det in enumerate(sorted_detections):
+            should_keep = True
+            det_bbox = det["bbox"]
+
+            for kept_det in keep:
+                kept_bbox = kept_det["bbox"]
+
+                # Check for ANY overlap at all
+                if self._boxes_overlap(det_bbox, kept_bbox):
+                    should_keep = False
+                    logger.debug(f"Rejecting box {det_bbox} due to overlap with {kept_bbox}")
+                    break
+
+            if should_keep:
+                keep.append(det)
+                logger.debug(f"Keeping box {det_bbox} with confidence {det['confidence']}")
+
+        logger.info(f"NMS: Reduced {len(detections)} detections to {len(keep)}")
+        return keep
+
+    def _boxes_overlap(self, box1: tuple, box2: tuple) -> bool:
+        """Check if two boxes have any overlap at all."""
+        x1_min, y1_min, x1_max, y1_max = box1
+        x2_min, y2_min, x2_max, y2_max = box2
+
+        # Check if boxes are separated
+        if x1_max <= x2_min or x2_max <= x1_min:
+            return False
+        if y1_max <= y2_min or y2_max <= y1_min:
+            return False
+
+        # If we get here, boxes overlap
+        return True
+
+    def _compute_intersection_ratio(self, box1: tuple, box2: tuple) -> float:
+        """
+        Compute intersection ratio relative to the smaller box.
+        This is more aggressive than IoU for checkbox detection.
+        """
+        x1_min, y1_min, x1_max, y1_max = box1
+        x2_min, y2_min, x2_max, y2_max = box2
+
+        # Intersection
+        inter_xmin = max(x1_min, x2_min)
+        inter_ymin = max(y1_min, y2_min)
+        inter_xmax = min(x1_max, x2_max)
+        inter_ymax = min(y1_max, y2_max)
+
+        if inter_xmax < inter_xmin or inter_ymax < inter_ymin:
+            return 0.0
+
+        inter_area = (inter_xmax - inter_xmin) * (inter_ymax - inter_ymin)
+
+        # Areas of both boxes
+        area1 = (x1_max - x1_min) * (y1_max - y1_min)
+        area2 = (x2_max - x2_min) * (y2_max - y2_min)
+
+        # Ratio relative to smaller box
+        smaller_area = min(area1, area2)
+        if smaller_area == 0:
+            return 0.0
+
+        return inter_area / smaller_area
+
+    def _compute_iou(self, box1: tuple, box2: tuple) -> float:
+        """Compute IoU between two boxes."""
+        x1_min, y1_min, x1_max, y1_max = box1
+        x2_min, y2_min, x2_max, y2_max = box2
+
+        # Intersection
+        inter_xmin = max(x1_min, x2_min)
+        inter_ymin = max(y1_min, y2_min)
+        inter_xmax = min(x1_max, x2_max)
+        inter_ymax = min(y1_max, y2_max)
+
+        if inter_xmax < inter_xmin or inter_ymax < inter_ymin:
+            return 0.0
+
+        inter_area = (inter_xmax - inter_xmin) * (inter_ymax - inter_ymin)
+
+        # Union
+        area1 = (x1_max - x1_min) * (y1_max - y1_min)
+        area2 = (x2_max - x2_min) * (y2_max - y2_min)
+        union_area = area1 + area2 - inter_area
+
+        if union_area == 0:
+            return 0.0
+
+        return inter_area / union_area
+
+    def __del__(self):
+        """Cleanup resources."""
+        self.logger.info(f"Cleaning up {self.__class__.__name__} resources.")
+        self._model_cache.clear()