natural-pdf 25.3.16__py3-none-any.whl

examples/layout_coordinate_debug.py

@@ -0,0 +1,258 @@
+"""
+Debug script to investigate coordinate differences between YOLO and TATR models.
+
+This script visualizes the regions detected by both models and logs all coordinate 
+transformations to help diagnose the issue with YOLO's regions being too narrow.
+"""
+import os
+import sys
+import logging
+import numpy as np
+try:
+    from PIL import Image, ImageDraw, ImageFont
+except ImportError:
+    from PIL import Image, ImageDraw
+    ImageFont = None
+import argparse
+
+# Add project root to path
+sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from natural_pdf import PDF, configure_logging
+from natural_pdf.elements.collections import ElementCollection
+
+# Set up logging
+configure_logging(level=logging.DEBUG)
+layout_logger = logging.getLogger("natural_pdf.analyzers.layout")
+layout_logger.setLevel(logging.DEBUG)
+
+# Create a file handler for detailed logs
+file_handler = logging.FileHandler("layout_debug.log")
+file_handler.setLevel(logging.DEBUG)
+formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+file_handler.setFormatter(formatter)
+layout_logger.addHandler(file_handler)
+
+def debug_detection_coordinates(pdf_path, page_num=0, output_dir="output"):
+    """Debug layout detection coordinates for both YOLO and TATR models."""
+    os.makedirs(output_dir, exist_ok=True)
+    
+    # Open PDF 
+    pdf = PDF(pdf_path)
+    page = pdf.pages[page_num]
+    
+    # Get original page dimensions for reference
+    page_width = page.width
+    page_height = page.height
+    print(f"Page dimensions: {page_width} x {page_height}")
+    
+    # Monkey patch the core analyze_layout method to add logging
+    original_analyze_layout = type(page).analyze_layout
+    
+    def debug_analyze_layout(self, *args, **kwargs):
+        """Wrapped analyze_layout method with debug logging."""
+        model_type = kwargs.get('model', 'yolo')
+        print(f"\n=== Running layout analysis with {model_type.upper()} model ===")
+        
+        # Add logging for image to PDF coordinate conversion
+        old_convert_to_regions = None
+        try:
+            from natural_pdf.analyzers.document_layout import convert_to_regions
+            old_convert_to_regions = convert_to_regions
+            
+            def debug_convert_to_regions(page, detections, scale_factor=1.0):
+                """Monkey patched version with detailed logging."""
+                print(f"Converting {len(detections)} detections with scale factor {scale_factor}")
+                
+                # Create a detailed log for each detection
+                for i, det in enumerate(detections):
+                    bbox = det['bbox']
+                    x_min, y_min, x_max, y_max = bbox
+                    width = x_max - x_min
+                    height = y_max - y_min
+                    
+                    pdf_x0 = x_min * scale_factor
+                    pdf_y0 = y_min * scale_factor
+                    pdf_x1 = x_max * scale_factor
+                    pdf_y1 = y_max * scale_factor
+                    
+                    print(f"Detection #{i+1} ({det['class']}):")
+                    print(f"  Raw bbox: {bbox}")
+                    print(f"  Image dimensions: {width:.2f} x {height:.2f}")
+                    print(f"  PDF coords: ({pdf_x0:.2f}, {pdf_y0:.2f}, {pdf_x1:.2f}, {pdf_y1:.2f})")
+                    print(f"  PDF dimensions: {pdf_x1-pdf_x0:.2f} x {pdf_y1-pdf_y0:.2f}")
+                    print(f"  Image-to-PDF ratio: width={scale_factor:.4f}, height={scale_factor:.4f}")
+                
+                # Call the original function
+                return old_convert_to_regions(page, detections, scale_factor)
+                
+            # Replace the function
+            from natural_pdf.analyzers import document_layout
+            document_layout.convert_to_regions = debug_convert_to_regions
+        
+        except ImportError:
+            print("Could not monkey patch convert_to_regions")
+        
+        # Call the original method
+        result = original_analyze_layout(self, *args, **kwargs)
+        
+        # Restore the original function
+        if old_convert_to_regions:
+            from natural_pdf.analyzers import document_layout
+            document_layout.convert_to_regions = old_convert_to_regions
+        
+        return result
+    
+    # Apply the monkey patch
+    type(page).analyze_layout = debug_analyze_layout
+    
+    # Run YOLO model layout detection
+    page.analyze_layout(model="yolo")
+    
+    # Get regions and save visualization
+    yolo_regions = page.find_all('region[model=yolo]')
+    print(f"YOLO detected {len(yolo_regions)} regions")
+    
+    # Highlight YOLO regions 
+    page.clear_highlights()
+    for region in yolo_regions:
+        # Get region dimensions
+        width = region.width
+        height = region.height
+        region.highlight(label=f"{region.region_type} ({width:.1f}x{height:.1f})")
+    
+    # Save YOLO visualization
+    page.to_image(labels=True).save(os.path.join(output_dir, "yolo_regions.png"))
+    
+    # Create detailed summary of YOLO regions
+    with open(os.path.join(output_dir, "yolo_regions.txt"), "w") as f:
+        for i, region in enumerate(yolo_regions):
+            f.write(f"Region #{i+1} ({region.region_type}):\n")
+            f.write(f"  Bbox: ({region.x0:.2f}, {region.top:.2f}, {region.x1:.2f}, {region.bottom:.2f})\n")
+            f.write(f"  Dimensions: {region.width:.2f} x {region.height:.2f}\n")
+            f.write(f"  Confidence: {region.confidence:.4f}\n")
+            f.write(f"  % of page width: {(region.width / page_width) * 100:.2f}%\n\n")
+    
+    # Clear existing layout regions
+    page._regions['detected'] = []
+    
+    # Run TATR model layout detection
+    page.analyze_layout(model="tatr")
+    
+    # Get regions and save visualization
+    tatr_regions = page.find_all('region[model=tatr]')
+    print(f"TATR detected {len(tatr_regions)} regions")
+    
+    # Highlight TATR regions
+    page.clear_highlights()
+    for region in tatr_regions:
+        # Get region dimensions
+        width = region.width
+        height = region.height
+        region.highlight(label=f"{region.region_type} ({width:.1f}x{height:.1f})")
+    
+    # Save TATR visualization
+    page.to_image(labels=True).save(os.path.join(output_dir, "tatr_regions.png"))
+    
+    # Create detailed summary of TATR regions
+    with open(os.path.join(output_dir, "tatr_regions.txt"), "w") as f:
+        for i, region in enumerate(tatr_regions):
+            f.write(f"Region #{i+1} ({region.region_type}):\n")
+            f.write(f"  Bbox: ({region.x0:.2f}, {region.top:.2f}, {region.x1:.2f}, {region.bottom:.2f})\n")
+            f.write(f"  Dimensions: {region.width:.2f} x {region.height:.2f}\n")
+            f.write(f"  Confidence: {region.confidence:.4f}\n")
+            f.write(f"  % of page width: {(region.width / page_width) * 100:.2f}%\n\n")
+    
+    # Create a side-by-side comparison image
+    # Get page base image
+    page_image = page.to_image(resolution=150)
+    
+    # Create a combined image
+    combined_width = page_image.width * 2 + 20  # Add some padding
+    combined_height = page_image.height + 50  # Add space for title
+    combined = Image.new('RGB', (combined_width, combined_height), (255, 255, 255))
+    
+    # Add titles
+    try:
+        font = ImageFont.truetype("Arial", 16)
+    except:
+        font = None
+    
+    draw = ImageDraw.Draw(combined)
+    draw.text((page_image.width // 2, 20), "YOLO Model", fill=(0, 0, 0), font=font)
+    draw.text((page_image.width * 3 // 2 + 20, 20), "TATR Model", fill=(0, 0, 0), font=font)
+    
+    # Add images side by side
+    try:
+        yolo_img = Image.open(os.path.join(output_dir, "yolo_regions.png"))
+        tatr_img = Image.open(os.path.join(output_dir, "tatr_regions.png"))
+    except:
+        print("Warning: Could not load images for side-by-side comparison. Continuing...")
+        return
+    
+    # Resize if needed
+    if yolo_img.height != page_image.height or yolo_img.width != page_image.width:
+        yolo_img = yolo_img.resize((page_image.width, page_image.height))
+    if tatr_img.height != page_image.height or tatr_img.width != page_image.width:
+        tatr_img = tatr_img.resize((page_image.width, page_image.height))
+        
+    combined.paste(yolo_img, (0, 50))
+    combined.paste(tatr_img, (page_image.width + 20, 50))
+    
+    combined.save(os.path.join(output_dir, "model_comparison.png"))
+    
+    # Create a document comparing page dimensions to detected region dimensions
+    with open(os.path.join(output_dir, "dimension_analysis.txt"), "w") as f:
+        f.write(f"Page dimensions: {page_width:.2f} x {page_height:.2f}\n\n")
+        
+        # YOLO region stats
+        f.write("=== YOLO Model Regions ===\n")
+        if yolo_regions:
+            yolo_widths = [r.width for r in yolo_regions]
+            yolo_width_pcts = [(r.width / page_width) * 100 for r in yolo_regions]
+            
+            f.write(f"Total regions: {len(yolo_regions)}\n")
+            f.write(f"Average width: {sum(yolo_widths) / len(yolo_widths):.2f}\n")
+            f.write(f"Average width as % of page: {sum(yolo_width_pcts) / len(yolo_width_pcts):.2f}%\n")
+            f.write(f"Min width: {min(yolo_widths):.2f} ({min(yolo_width_pcts):.2f}%)\n")
+            f.write(f"Max width: {max(yolo_widths):.2f} ({max(yolo_width_pcts):.2f}%)\n\n")
+        else:
+            f.write("No regions detected\n\n")
+            
+        # TATR region stats
+        f.write("=== TATR Model Regions ===\n")
+        if tatr_regions:
+            tatr_widths = [r.width for r in tatr_regions]
+            tatr_width_pcts = [(r.width / page_width) * 100 for r in tatr_regions]
+            
+            f.write(f"Total regions: {len(tatr_regions)}\n")
+            f.write(f"Average width: {sum(tatr_widths) / len(tatr_widths):.2f}\n")
+            f.write(f"Average width as % of page: {sum(tatr_width_pcts) / len(tatr_width_pcts):.2f}%\n")
+            f.write(f"Min width: {min(tatr_widths):.2f} ({min(tatr_width_pcts):.2f}%)\n")
+            f.write(f"Max width: {max(tatr_widths):.2f} ({max(tatr_width_pcts):.2f}%)\n\n")
+        else:
+            f.write("No regions detected\n\n")
+        
+        # If both have regions, compare them
+        if yolo_regions and tatr_regions:
+            # Calculate average width ratio
+            avg_yolo_width = sum(yolo_widths) / len(yolo_widths)
+            avg_tatr_width = sum(tatr_widths) / len(tatr_widths)
+            width_ratio = avg_tatr_width / avg_yolo_width if avg_yolo_width > 0 else 0
+            
+            f.write("=== Comparison ===\n")
+            f.write(f"TATR avg width / YOLO avg width = {width_ratio:.4f}\n")
+            f.write(f"YOLO is {100 * (1 - 1/width_ratio):.2f}% narrower than TATR on average\n")
+    
+    print(f"\nDebug information saved to {output_dir} directory")
+    print(f"See 'layout_debug.log' for detailed process logging")
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Debug layout detection coordinate differences")
+    parser.add_argument("pdf_path", help="Path to the PDF file to analyze")
+    parser.add_argument("--page", type=int, default=0, help="Page number to analyze (0-indexed)")
+    parser.add_argument("--output", default="output", help="Output directory for debug files")
+    
+    args = parser.parse_args()
+    
+    debug_detection_coordinates(args.pdf_path, page_num=args.page, output_dir=args.output)

examples/layout_highlight_test.py

@@ -0,0 +1,77 @@
+"""
+Test the improved highlight_all behavior with layout regions.
+
+This example demonstrates how the updated highlight_all method properly 
+highlights layout regions by model and type.
+"""
+import os
+import sys
+import argparse
+
+# Add the parent directory to the Python path
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))
+from natural_pdf import PDF
+
+# Get the current directory of this script
+script_dir = os.path.dirname(os.path.realpath(__file__))
+# Get the parent directory (project root)
+root_dir = os.path.dirname(script_dir)
+# Default PDF path
+default_pdf = os.path.join(root_dir, "pdfs", "01-practice.pdf")
+
+# Set up argument parser
+parser = argparse.ArgumentParser(description="Layout highlighting test")
+parser.add_argument("pdf_path", nargs="?", default=default_pdf, help="Path to a PDF file")
+parser.add_argument("--page", type=int, default=0, help="Page number to analyze (0-based)")
+args = parser.parse_args()
+
+print(f"Testing layout highlighting on: {args.pdf_path}")
+print(f"Page: {args.page}")
+
+# Load the PDF
+pdf = PDF(args.pdf_path)
+page = pdf.pages[args.page]
+
+# First, let's show the regular highlight_all without layout regions
+print("Creating image with standard highlight_all (no layout regions)...")
+page.clear_highlights()
+page.highlight_all()
+output_path = os.path.join(root_dir, "output", "standard_highlight_all.png")
+page.to_image(path=output_path, show_labels=True)
+print(f"Saved to {output_path}")
+
+# Now run layout analysis with YOLO
+print("\nRunning YOLO layout analysis...")
+page.analyze_layout(model="yolo", confidence=0.2)
+print(f"Found {len(page.detected_layout_regions)} YOLO layout regions")
+
+# Create an image with highlight_all including layout regions
+print("Creating image with highlight_all including YOLO layout regions...")
+page.clear_highlights()
+page.highlight_all(include_layout_regions=True)
+output_path = os.path.join(root_dir, "output", "highlight_all_with_yolo.png")
+page.to_image(path=output_path, show_labels=True)
+print(f"Saved to {output_path}")
+
+# Now run table structure analysis with TATR and append to existing regions
+print("\nRunning TATR table structure analysis...")
+page.analyze_layout(model="tatr", confidence=0.3, existing="append")
+print(f"Found {len(page.detected_layout_regions)} total layout regions (YOLO + TATR)")
+
+# Create an image with highlight_all including all layout regions
+print("Creating image with highlight_all including all layout regions...")
+page.clear_highlights()
+page.highlight_all(include_layout_regions=True)
+output_path = os.path.join(root_dir, "output", "highlight_all_with_all_layouts.png")
+page.to_image(path=output_path, show_labels=True)
+print(f"Saved to {output_path}")
+
+# Compare with the original highlight_layout method
+print("\nCreating image with highlight_layout method for comparison...")
+page.clear_highlights()
+page.highlight_layout()
+output_path = os.path.join(root_dir, "output", "highlight_layout_method.png")
+page.to_image(path=output_path, show_labels=True)
+print(f"Saved to {output_path}")
+
+print("\nDone!")

examples/logging_example.py

@@ -0,0 +1,70 @@
+"""
+Example demonstrating the logging system in Natural PDF.
+"""
+import os
+import sys
+import logging
+from pathlib import Path
+
+# Add the project directory to the path to import the library
+sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+from natural_pdf import configure_logging, PDF
+
+def main():
+    # Basic setup with INFO level
+    print("=== Configuring logging at INFO level ===")
+    configure_logging(level=logging.INFO)
+    
+    # Create a PDF
+    pdf_path = "./pdfs/01-practice.pdf"
+    if not os.path.exists(pdf_path):
+        # Try another file if the first one doesn't exist
+        pdf_path = list(Path("./pdfs").glob("*.pdf"))[0]
+    
+    print(f"\nLoading PDF with standard logging: {pdf_path}")
+    pdf = PDF(pdf_path)
+    
+    # OCR with default settings (should log OCR engine initialization)
+    print("\nExtracting text with OCR")
+    text = pdf.pages[0].extract_text(ocr=True)
+    print(f"Extracted {len(text)} characters")
+    
+    # Switch to DEBUG level
+    print("\n=== Configuring logging at DEBUG level ===")
+    configure_logging(level=logging.DEBUG)
+    
+    # Try layout detection (generates more detailed logs)
+    print("\nRunning layout detection with DEBUG logging")
+    regions = pdf.pages[0].analyze_layout(
+        model="paddle",
+        model_params={"detect_text": True, "verbose": True}
+    )
+    print(f"Found {len(regions)} regions")
+    
+    # Try logging to a file
+    print("\n=== Logging to a file ===")
+    log_file = os.path.join("output", "natural_pdf.log")
+    os.makedirs(os.path.dirname(log_file), exist_ok=True)
+    
+    # Create a file handler with custom formatter
+    file_handler = logging.FileHandler(log_file, mode='w')  # 'w' mode to overwrite any existing file
+    formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+    file_handler.setFormatter(formatter)
+    
+    # Configure logging with the file handler
+    configure_logging(level=logging.DEBUG, handler=file_handler)
+    
+    # Force a few log events
+    logger = logging.getLogger("natural_pdf")
+    logger.debug("This is a debug message written to the log file")
+    logger.info("This is an info message written to the log file")
+    logger.warning("This is a warning message written to the log file")
+    
+    # Run another OCR operation to log to the file
+    print(f"Running OCR with logging to {log_file}")
+    text = pdf.pages[0].extract_text(ocr=True)
+    
+    print(f"\nDone! Check {log_file} for detailed logs.")
+
+if __name__ == "__main__":
+    main()

examples/ocr_comprehensive.py

@@ -0,0 +1,193 @@
+"""
+Comprehensive OCR example.
+
+This example demonstrates the full range of OCR capabilities
+in natural-pdf, including:
+1. Multiple configuration formats
+2. Auto mode
+3. Region-specific OCR
+4. Selector filtering by source and confidence
+5. Visualization of OCR results
+"""
+import os
+import sys
+from pathlib import Path
+
+# Add parent directory to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from natural_pdf import PDF
+
+# Get the current directory of this script
+script_dir = os.path.dirname(os.path.realpath(__file__))
+# Get the parent directory (project root)
+root_dir = os.path.dirname(script_dir)
+# Default PDF path (replace with a scanned document path for better results)
+default_pdf = os.path.join(root_dir, "pdfs", "HARRY ROQUE_redacted.pdf")
+# Output directory
+output_dir = os.path.join(root_dir, "output")
+os.makedirs(output_dir, exist_ok=True)
+
+print("Comprehensive OCR Example")
+print("========================")
+
+# 1. Demonstrate different OCR configuration formats
+print("\n1. Different OCR configuration formats")
+
+# Simple flag
+pdf_simple = PDF(default_pdf, ocr=True)
+print("  - Simple flag (ocr=True): OCR enabled with defaults")
+
+# Auto mode
+pdf_auto = PDF(default_pdf, ocr="auto")
+print("  - Auto mode (ocr='auto'): OCR applied only when needed")
+
+# Language list
+pdf_langs = PDF(default_pdf, ocr=["en"])
+print("  - Language list (ocr=['en']): English language OCR")
+
+# Detailed config with detection parameters
+pdf_detailed = PDF(default_pdf, ocr={
+    "enabled": True,
+    "engine": "easyocr",
+    "languages": ["en"],
+    "min_confidence": 0.6,
+    "paragraph": False,
+    # Text detection parameters for CRAFT
+    "detection_params": {
+        "text_threshold": 0.1,  # Lower threshold to detect more text (default is 0.7)
+        "low_text": 0.3,        # Lower threshold for text box filtering (default is 0.4)
+        "link_threshold": 0.3,  # Lower threshold for link between text (default is 0.4)
+        "canvas_size": 2560,    # Maximum image size
+        "mag_ratio": 1.5        # Image magnification ratio (increase for better detection)
+    },
+    # Optional recognition parameters
+    "recognition_params": {
+        "decoder": "greedy",
+        "batch_size": 4,
+        "contrast_ths": 0.05    # Lower contrast threshold
+    }
+})
+print("  - Detailed config: Custom parameters including text_threshold=0.1")
+
+# 2. Auto mode demonstration
+print("\n2. Auto mode OCR")
+pdf = PDF(default_pdf, ocr="auto")
+page = pdf.pages[0]
+
+# Extract text with auto OCR
+text = page.extract_text()
+print(f"  - Auto mode extracted {len(text)} characters")
+print(f"  - First 100 chars: {text[:100]}...")
+
+# 3. Explicit OCR application
+print("\n3. Explicit OCR application")
+ocr_elements = page.apply_ocr()
+print(f"  - Found {len(ocr_elements)} OCR elements")
+print("  - Sample OCR elements:")
+for i, elem in enumerate(ocr_elements[:3]):
+    print(f"    {i+1}. '{elem.text}' (confidence: {elem.confidence:.2f})")
+
+# 4. OCR with confidence filtering
+print("\n4. OCR confidence filtering")
+high_conf = page.find_all('text[source=ocr][confidence>=0.8]')
+print(f"  - Found {len(high_conf)} high-confidence OCR elements")
+low_conf = page.find_all('text[source=ocr][confidence<0.6]')
+print(f"  - Found {len(low_conf)} low-confidence OCR elements")
+
+# 5. Content-based OCR filtering
+print("\n5. Content-based OCR filtering")
+contains_a = page.find_all('text[source=ocr]:contains("a")')
+print(f"  - Found {len(contains_a)} OCR elements containing 'a'")
+
+# 6. Region-specific OCR
+print("\n6. Region-specific OCR")
+# Create a region - adjust coordinates if needed for your document
+region = page.create_region(100, 100, 400, 200)
+region_elems = region.apply_ocr()
+print(f"  - Applied OCR to region, found {len(region_elems)} elements")
+region_text = region.extract_text()
+print(f"  - Region text: '{region_text[:50]}...'")
+
+# 7. OCR visualization
+print("\n7. OCR visualization")
+# Clear any existing highlights
+page.clear_highlights()
+
+# Highlight all OCR elements with confidence displayed
+print("  - Highlighting all OCR elements with confidence scores")
+for elem in ocr_elements:
+    # Color coding based on confidence - using integer RGB values (0-255)
+    if elem.confidence >= 0.8:
+        color = (0, 204, 0, 76)  # Green for high confidence
+    elif elem.confidence >= 0.6:
+        color = (230, 230, 0, 76)  # Yellow for medium confidence
+    else:
+        color = (204, 0, 0, 76)  # Red for low confidence
+        
+    elem.highlight(label=f"OCR ({elem.confidence:.2f})", color=color)
+
+# Save the image
+output_path = os.path.join(output_dir, "ocr_confidence_visualization.png")
+page.to_image(path=output_path, show_labels=True)
+print(f"  - Saved visualization to {output_path}")
+
+# 8. Demonstrate override at extraction time
+print("\n8. OCR override at extraction time")
+text_default = page.extract_text()
+print(f"  - Default extraction: {len(text_default)} characters")
+
+text_override = page.extract_text(ocr={
+    "languages": ["en"],
+    "min_confidence": 0.4  # Lower threshold
+})
+print(f"  - Override extraction (min_confidence=0.4): {len(text_override)} characters")
+
+# 9. OCR element properties
+print("\n9. OCR element properties")
+if ocr_elements:
+    elem = ocr_elements[0]
+    print(f"  - Source: {elem.source}")
+    print(f"  - Confidence: {elem.confidence:.2f}")
+    print(f"  - Text: '{elem.text}'")
+    print(f"  - Bounding box: {elem.bbox}")
+    print(f"  - Font (default for OCR): {elem.fontname}")
+
+# 10. Compare OCR with lower text_threshold to detect more text
+print("\n10. Comparing OCR with different text_threshold values")
+page.clear_highlights()
+
+# First with default text_threshold (0.7)
+print("  - Running OCR with default text_threshold (0.7)")
+default_elements = page.extract_ocr_elements(ocr={
+    "languages": ["en"],
+    "detection_params": {
+        "text_threshold": 0.7  # Default value
+    }
+})
+print(f"  - Found {len(default_elements)} elements with default text_threshold")
+
+# Highlight with blue
+for elem in default_elements:
+    elem.highlight(label="Default threshold", color=(0, 0, 204, 76))
+
+# Now with lower text_threshold (0.1)
+print("  - Running OCR with lower text_threshold (0.1)")
+low_threshold_elements = page.extract_ocr_elements(ocr={
+    "languages": ["en"],
+    "detection_params": {
+        "text_threshold": 0.1  # Lower value to detect more text
+    }
+})
+print(f"  - Found {len(low_threshold_elements)} elements with text_threshold=0.1")
+
+# Highlight with red
+for elem in low_threshold_elements:
+    elem.highlight(label="Lower threshold (0.1)", color=(204, 0, 0, 76))
+
+# Save comparative visualization
+output_path = os.path.join(output_dir, "ocr_threshold_comparison.png")
+page.to_image(path=output_path, show_labels=True)
+print(f"  - Saved threshold comparison to {output_path}")
+
+print("\nDone!")

examples/ocr_debug_example.py

@@ -0,0 +1,87 @@
+"""
+OCR Debug Report Example
+
+This example demonstrates the OCR debugging feature, which generates an interactive
+HTML report for analyzing and correcting OCR results.
+"""
+import os
+import sys
+from pathlib import Path
+
+# Get the parent directory (project root)
+project_root = Path(__file__).absolute().parent.parent
+sys.path.insert(0, str(project_root))
+
+from natural_pdf import PDF
+
+# Output directory
+output_dir = os.path.join(project_root, "output")
+os.makedirs(output_dir, exist_ok=True)
+
+# Default PDF path (a scanned document)
+pdf_path = os.path.join(project_root, "pdfs", "HARRY ROQUE_redacted.pdf")
+fallback_pdf = os.path.join(project_root, "pdfs", "needs-ocr.pdf")
+
+# Use the first available PDF
+if os.path.exists(pdf_path):
+    print(f"Using PDF: {pdf_path}")
+elif os.path.exists(fallback_pdf):
+    pdf_path = fallback_pdf
+    print(f"Using PDF: {pdf_path}")
+else:
+    print("No suitable PDF found. Please provide a scanned PDF.")
+    sys.exit(1)
+
+# OCR Debug Example
+print("\nOCR Debug Report Example")
+print("=======================")
+
+# Load PDF with OCR enabled
+print("\n1. Loading PDF with OCR enabled")
+pdf = PDF(
+    pdf_path, 
+    ocr={
+        "enabled": True,  # Enable OCR
+        "languages": ["en"],
+        "min_confidence": 0.3,  # Lower threshold to get more results
+    },
+    # Try PaddleOCR first, which often gives better results for Asian languages
+    ocr_engine="paddleocr"
+)
+
+# Run OCR on the first page
+print("\n2. Running OCR on the first page")
+page = pdf.pages[0]
+ocr_elements = page.extract_ocr_elements()
+print(f"Found {len(ocr_elements)} OCR text elements")
+
+# Generate a debug report for a single page
+print("\n3. Generating OCR debug report for a single page")
+page_report_path = os.path.join(output_dir, "ocr_debug_page.html")
+page.debug_ocr(page_report_path)
+print(f"Saved page debug report to: {page_report_path}")
+
+# Generate a debug report for multiple pages 
+print("\n4. Generating OCR debug report for multiple pages")
+pdf_report_path = os.path.join(output_dir, "ocr_debug_full.html")
+pdf.debug_ocr(pdf_report_path)
+print(f"Saved full PDF debug report to: {pdf_report_path}")
+
+# Generate a debug report for a page range
+print("\n5. Generating OCR debug report for a page range")
+if len(pdf.pages) > 1:
+    page_range_report_path = os.path.join(output_dir, "ocr_debug_range.html")
+    page_range = pdf.pages[0:min(3, len(pdf.pages))]
+    page_range.debug_ocr(page_range_report_path)
+    print(f"Saved page range debug report to: {page_range_report_path}")
+else:
+    print("PDF has only one page, skipping page range example")
+
+print("\nDone! The debug reports have been saved to the output directory.")
+print("You can open them in a web browser to interactively review the OCR results.")
+print("The reports allow you to:")
+print("- Filter results by confidence score")
+print("- Search for specific text")
+print("- Sort results by different criteria")
+print("- Edit/correct OCR text")
+print("- Export corrected text as JSON for further processing")