natural-pdf 25.3.16__py3-none-any.whl

examples/paddleocr_example.py

@@ -0,0 +1,224 @@
+"""
+Example script demonstrating the PaddleOCR integration.
+"""
+import os
+import sys
+from PIL import Image
+import numpy as np
+
+# 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 PDF
+
+# Select a PDF file to test
+PDF_FILE = "./pdfs/HARRY ROQUE_redacted.pdf"
+if not os.path.exists(PDF_FILE):
+    PDF_FILE = "./pdfs/01-practice.pdf"  # Fallback to another file if needed
+
+def basic_paddleocr_example():
+    """Basic example using PaddleOCR integration."""
+    print("\n=== Basic PaddleOCR Example ===")
+    
+    # Create a PDF with the PaddleOCR engine
+    print("Creating PDF with PaddleOCR engine...")
+    pdf = PDF(
+        PDF_FILE, 
+        ocr={
+            "enabled": True,
+            "languages": ["en"],
+            "min_confidence": 0.5,
+        },
+        ocr_engine="paddleocr"
+    )
+    
+    # Get the first page
+    page = pdf.pages[0]
+    
+    # Extract OCR elements explicitly
+    print("\nExtracting OCR elements...")
+    ocr_elements = page.extract_ocr_elements()
+    print(f"Found {len(ocr_elements)} OCR text elements")
+    
+    # Print the first few elements
+    for i, element in enumerate(ocr_elements[:5]):
+        print(f"Element {i+1}: '{element.text}' (Confidence: {element.confidence:.2f})")
+    
+    # Extract text with OCR applied automatically
+    print("\nExtracting text with auto OCR...")
+    text = page.extract_text(ocr=True)
+    
+    # Print a snippet of the extracted text
+    print(f"Extracted text length: {len(text)}")
+    print(f"First 100 characters: {text[:100]}")
+    
+    # Clean up
+    pdf.close()
+    print("Basic PaddleOCR example complete")
+
+def advanced_paddleocr_example():
+    """Advanced example showing more PaddleOCR features."""
+    print("\n=== Advanced PaddleOCR Example ===")
+    
+    # Create a PDF with detailed PaddleOCR configuration
+    print("Creating PDF with detailed PaddleOCR configuration...")
+    pdf = PDF(
+        PDF_FILE, 
+        ocr={
+            "enabled": True,
+            "languages": ["en"],
+            "min_confidence": 0.3,  # Lower threshold to catch more text
+            "model_settings": {
+                # PaddleOCR-specific settings
+                "use_angle_cls": False,
+                "rec_batch_num": 6,
+                "cls": False,
+                "det_db_thresh": 0.3,
+                "det_db_box_thresh": 0.5,
+                "det_limit_side_len": 2000  # Support larger images
+            }
+        },
+        ocr_engine="paddleocr"
+    )
+    
+    # Create output directory for highlighted images
+    output_dir = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "output")
+    os.makedirs(output_dir, exist_ok=True)
+    
+    # Get the first page
+    page = pdf.pages[0]
+    
+    # Extract OCR elements
+    print("\nExtracting OCR elements with detailed configuration...")
+    ocr_elements = page.extract_ocr_elements()
+    print(f"Found {len(ocr_elements)} OCR text elements")
+    
+    # Highlight OCR elements with confidence scores
+    print("\nHighlighting OCR elements...")
+    for i, elem in enumerate(ocr_elements):
+        # Use different colors based on confidence
+        if elem.confidence >= 0.8:
+            color = (0, 1, 0, 0.3)  # Green for high confidence
+        elif elem.confidence >= 0.5:
+            color = (1, 1, 0, 0.3)  # Yellow for medium confidence
+        else:
+            color = (1, 0, 0, 0.3)  # Red for low confidence
+            
+        # Label includes confidence score
+        elem.highlight(
+            color=color,
+            label=f"OCR ({elem.confidence:.2f})"
+        )
+    
+    # Save highlighted page
+    highlight_path = os.path.join(output_dir, "paddleocr_highlights.png")
+    page.to_image(path=highlight_path, show_labels=True)
+    print(f"Saved highlighted image to {highlight_path}")
+    
+    # Filter OCR elements by confidence
+    high_confidence = [e for e in ocr_elements if e.confidence >= 0.7]
+    print(f"\nHigh confidence elements ({len(high_confidence)}): ")
+    for i, elem in enumerate(high_confidence[:3]):
+        print(f"  {i+1}. '{elem.text}' (Confidence: {elem.confidence:.2f})")
+    
+    # Clean up
+    pdf.close()
+    print("Advanced PaddleOCR example complete")
+
+def ocr_engine_comparison():
+    """Compare EasyOCR and PaddleOCR on the same document."""
+    print("\n=== OCR Engine Comparison ===")
+    
+    # Create output directory
+    output_dir = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "output")
+    os.makedirs(output_dir, exist_ok=True)
+    
+    # Test with EasyOCR
+    print("\nUsing EasyOCR...")
+    easy_pdf = PDF(
+        PDF_FILE, 
+        ocr={"enabled": True, "languages": ["en"]},
+        ocr_engine="easyocr"
+    )
+    page = easy_pdf.pages[0]
+    
+    # Time the OCR process
+    import time
+    start_time = time.time()
+    easy_elements = page.extract_ocr_elements()
+    easy_time = time.time() - start_time
+    print(f"EasyOCR found {len(easy_elements)} text elements in {easy_time:.2f} seconds")
+    
+    # Save a sample
+    with open(os.path.join(output_dir, "easyocr_sample.txt"), "w") as f:
+        for i, elem in enumerate(easy_elements[:20]):
+            f.write(f"{i+1}. '{elem.text}' (Confidence: {elem.confidence:.2f})\n")
+    
+    # Clean up
+    easy_pdf.close()
+    
+    # Test with PaddleOCR
+    print("\nUsing PaddleOCR...")
+    paddle_pdf = PDF(
+        PDF_FILE, 
+        ocr={"enabled": True, "languages": ["en"]},
+        ocr_engine="paddleocr"
+    )
+    page = paddle_pdf.pages[0]
+    
+    # Time the OCR process
+    start_time = time.time()
+    paddle_elements = page.extract_ocr_elements()
+    paddle_time = time.time() - start_time
+    print(f"PaddleOCR found {len(paddle_elements)} text elements in {paddle_time:.2f} seconds")
+    
+    # Save a sample
+    with open(os.path.join(output_dir, "paddleocr_sample.txt"), "w") as f:
+        for i, elem in enumerate(paddle_elements[:20]):
+            f.write(f"{i+1}. '{elem.text}' (Confidence: {elem.confidence:.2f})\n")
+    
+    # Clean up
+    paddle_pdf.close()
+    
+    # Compare results
+    print("\nComparison Results:")
+    print(f"EasyOCR: {len(easy_elements)} elements in {easy_time:.2f} seconds")
+    print(f"PaddleOCR: {len(paddle_elements)} elements in {paddle_time:.2f} seconds")
+    print(f"Speed difference: {(easy_time / paddle_time if paddle_time > 0 else 0):.2f}x")
+    
+    print("\nSample results saved to:")
+    print(f"  - {os.path.join(output_dir, 'easyocr_sample.txt')}")
+    print(f"  - {os.path.join(output_dir, 'paddleocr_sample.txt')}")
+    
+    print("OCR engine comparison complete")
+
+if __name__ == "__main__":
+    try:
+        # Check if PaddleOCR is available
+        import paddleocr
+        print("PaddleOCR is available, running examples...")
+        
+        # Get command line arguments if any
+        import sys
+        if len(sys.argv) > 1:
+            example = sys.argv[1].lower()
+            if example == "basic":
+                basic_paddleocr_example()
+            elif example == "advanced":
+                advanced_paddleocr_example()
+            elif example == "compare":
+                ocr_engine_comparison()
+            else:
+                print(f"Unknown example: {example}")
+                print("Available examples: basic, advanced, compare")
+        else:
+            # Run all examples
+            basic_paddleocr_example()
+            advanced_paddleocr_example()
+            ocr_engine_comparison()
+        
+    except ImportError:
+        print("PaddleOCR is not installed. Please install it with: pip install paddlepaddle paddleocr")
+    except Exception as e:
+        print(f"Error in PaddleOCR examples: {e}")
+        import traceback
+        traceback.print_exc()

examples/page_collection_example.py

@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+"""
+Example demonstrating the PageCollection functionality.
+
+This example shows how to:
+1. Access a specific range of pages using slicing
+2. Extract text from multiple pages
+3. Find elements across multiple pages
+4. Get sections that span across page boundaries
+
+Usage:
+    python examples/page_collection_example.py [path_to_pdf]
+"""
+
+import os
+import sys
+from pathlib import Path
+
+# Add the parent directory to the path so we can import the package
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from natural_pdf import PDF
+
+# Use the provided PDF path or a default
+pdf_path = sys.argv[1] if len(sys.argv) > 1 else "pdfs/Atlanta_Public_Schools_GA_sample.pdf"
+
+def main():
+    print(f"Opening {pdf_path}")
+    
+    with PDF(pdf_path) as pdf:
+        page_count = len(pdf)
+        print(f"PDF has {page_count} pages")
+        
+        # Example 1: Access a page range
+        if page_count >= 3:
+            print("\n1. Working with a range of pages:")
+            # Get pages 1-3 (0-indexed, so second, third, fourth pages)
+            page_range = pdf.pages[1:4]
+            print(f"  Selected {len(page_range)} pages: {[p.number for p in page_range.pages]}")
+            
+            # Extract text from the range
+            text = page_range.extract_text()
+            print(f"  Extracted {len(text)} characters of text from pages {[p.number for p in page_range.pages]}")
+            
+            # You can also slice a page collection
+            if len(page_range) > 1:
+                sub_range = page_range[0:2]
+                print(f"  Sub-range has {len(sub_range)} pages: {[p.number for p in sub_range.pages]}")
+        
+        # Example 2: Find elements across multiple pages
+        if page_count >= 2:
+            print("\n2. Finding elements across multiple pages:")
+            # Get the first two pages
+            two_pages = pdf.pages[0:2]
+            
+            # Find all text elements
+            text_elements = two_pages.find_all('text')
+            print(f"  Found {len(text_elements)} text elements across {len(two_pages)} pages")
+            
+            # Find the first heading-like element
+            heading = two_pages.find('text[size>=12]')
+            if heading:
+                print(f"  Found heading: '{heading.text}' on page {heading.page.number}")
+        
+        # Example 3: Get sections across pages
+        if page_count >= 2:
+            print("\n3. Getting sections across pages:")
+            # Get the first two pages
+            two_pages = pdf.pages[0:2]
+            
+            # Try to find headings or large text as section starts
+            sections = two_pages.get_sections(
+                start_selector='text[size>=12]',
+                new_section_on_page_break=False,  # Allow sections to continue across pages
+                boundary_inclusion='both'
+            )
+            
+            print(f"  Found {len(sections)} sections across {len(two_pages)} pages")
+            
+            # Print info about each section
+            for i, section in enumerate(sections):
+                print(f"  Section {i+1}:")
+                if hasattr(section, 'start_element') and section.start_element:
+                    print(f"    Starts with: '{section.start_element.text}'")
+                    print(f"    On page: {section.start_element.page.number}")
+                
+                text = section.extract_text()
+                print(f"    Contains {len(text)} characters of text")
+                
+                # Show a preview
+                preview = text[:50] + "..." if len(text) > 50 else text
+                print(f"    Preview: {preview}")
+            
+            # Show with page breaks as section boundaries
+            sections_with_breaks = two_pages.get_sections(
+                start_selector='text[size>=12]',
+                new_section_on_page_break=True,  # Force new sections at page boundaries
+                boundary_inclusion='both'
+            )
+            print(f"  With page breaks as boundaries: {len(sections_with_breaks)} sections")
+
+if __name__ == "__main__":
+    main()

examples/polygon_highlight_example.py

@@ -0,0 +1,83 @@
+"""
+Example showing the polygon highlighting capabilities for handling non-rectangular regions.
+
+This example demonstrates how polygon-based OCR results are handled and visualized,
+which is especially useful for skewed or rotated text in scanned documents.
+"""
+import os
+import sys
+from natural_pdf import PDF
+from natural_pdf.elements.region import Region
+from PIL import Image
+
+# 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 (using a document that needs OCR)
+default_pdf = os.path.join(root_dir, "pdfs", "needs-ocr.pdf")
+
+# Check for command line arguments
+pdf_path = sys.argv[1] if len(sys.argv) > 1 else default_pdf
+page_num = int(sys.argv[2]) if len(sys.argv) > 2 else 0
+
+print(f"Loading PDF: {pdf_path}")
+print(f"Using page: {page_num}")
+
+# Load the PDF with OCR enabled
+pdf = PDF(pdf_path, ocr=True)
+page = pdf.pages[page_num]
+
+# Create a simulated polygon region to show polygon highlighting
+print("Creating polygon region...")
+polygon_points = [
+    (100, 100),
+    (300, 150),
+    (250, 250),
+    (120, 200)
+]
+
+# Create a region with the polygon points
+region = Region(page, (100, 100, 300, 250), polygon=polygon_points)
+region.highlight(color=(1, 0, 0, 0.5), label="Polygon Region")
+
+# Also extract and highlight text using OCR, which will use polygon detection
+print("Running OCR on the page...")
+ocr_elements = page.apply_ocr()
+print(f"Found {len(ocr_elements)} OCR text elements")
+
+# Highlight OCR elements with different colors based on confidence
+print("Highlighting OCR elements...")
+for elem in ocr_elements:
+    if elem.confidence > 0.8:
+        color = (0, 0.8, 0, 0.3)  # Green for high confidence
+    elif elem.confidence > 0.5:
+        color = (1, 0.8, 0, 0.3)  # Yellow for medium confidence
+    else:
+        color = (0.8, 0, 0, 0.3)  # Red for low confidence
+        
+    elem.highlight(color=color)
+
+# Save the result
+output_path = os.path.join(root_dir, "output", "polygon_highlight_example.png")
+print(f"Saving highlighted image to {output_path}")
+page.to_image(path=output_path, show_labels=True)
+
+# Print some information about the elements
+print("\nPolygon support details:")
+
+# Check if any OCR elements have polygon data
+polygon_elements = [elem for elem in ocr_elements if hasattr(elem, 'has_polygon') and elem.has_polygon]
+print(f"- Found {len(polygon_elements)} elements with polygon data")
+
+# Display details of the first few polygon elements
+if polygon_elements:
+    for i, elem in enumerate(polygon_elements[:3]):
+        print(f"\nElement {i+1}:")
+        print(f"- Text: '{elem.text}'")
+        print(f"- Confidence: {elem.confidence:.2f}")
+        print(f"- Bounding box: {elem.bbox}")
+        print(f"- Polygon points: {elem.polygon[:2]}... ({len(elem.polygon)} points)")
+    
+    if len(polygon_elements) > 3:
+        print(f"... and {len(polygon_elements) - 3} more")

examples/position_methods_example.py

@@ -0,0 +1,134 @@
+"""
+Example demonstrating positional methods in ElementCollection.
+"""
+
+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
+
+
+def main():
+    """Main entry point."""
+    # Get the PDF path from command line or use a default
+    if len(sys.argv) > 1:
+        pdf_path = sys.argv[1]
+    else:
+        # Look for any PDF in the examples directory or pdfs directory
+        example_dir = Path(__file__).parent
+        pdf_files = list(example_dir.glob("*.pdf"))
+        
+        if not pdf_files:
+            pdfs_dir = example_dir.parent / "pdfs"
+            if pdfs_dir.exists():
+                pdf_files = list(pdfs_dir.glob("*.pdf"))
+        
+        if pdf_files:
+            pdf_path = str(pdf_files[0])
+        else:
+            print("No PDF file found. Please provide a path to a PDF file.")
+            sys.exit(1)
+    
+    print(f"Using PDF: {pdf_path}")
+    
+    # Open the PDF
+    pdf = PDF(pdf_path)
+    page = pdf.pages[0]
+    
+    # Find different element types
+    lines = page.find_all('line')
+    rects = page.find_all('rect')
+    text = page.find_all('text')
+    
+    # Clear any existing highlights
+    page.clear_highlights()
+    
+    # Highlight the page corners for reference
+    page.create_region(0, 0, 10, 10).highlight(label="Top-Left Corner")
+    page.create_region(page.width-10, 0, page.width, 10).highlight(label="Top-Right Corner")
+    page.create_region(0, page.height-10, 10, page.height).highlight(label="Bottom-Left Corner")
+    page.create_region(page.width-10, page.height-10, page.width, page.height).highlight(label="Bottom-Right Corner")
+    
+    # Demonstrate line position methods
+    print(f"\nLines found: {len(lines)}")
+    if len(lines) > 0:
+        highest_line = lines.highest()
+        lowest_line = lines.lowest()
+        leftmost_line = lines.leftmost()
+        rightmost_line = lines.rightmost()
+        
+        print(f"Highest line: {highest_line.bbox}")
+        print(f"Lowest line: {lowest_line.bbox}")
+        print(f"Leftmost line: {leftmost_line.bbox}")
+        print(f"Rightmost line: {rightmost_line.bbox}")
+        
+        # Highlight the extreme lines
+        highest_line.highlight(label="Highest Line")
+        lowest_line.highlight(label="Lowest Line")
+        leftmost_line.highlight(label="Leftmost Line")
+        rightmost_line.highlight(label="Rightmost Line")
+    
+    # Demonstrate rectangle position methods
+    print(f"\nRectangles found: {len(rects)}")
+    if len(rects) > 0:
+        highest_rect = rects.highest()
+        lowest_rect = rects.lowest()
+        leftmost_rect = rects.leftmost()
+        rightmost_rect = rects.rightmost()
+        
+        print(f"Highest rectangle: {highest_rect.bbox}")
+        print(f"Lowest rectangle: {lowest_rect.bbox}")
+        print(f"Leftmost rectangle: {leftmost_rect.bbox}")
+        print(f"Rightmost rectangle: {rightmost_rect.bbox}")
+        
+        # Highlight the extreme rectangles
+        highest_rect.highlight(label="Highest Rectangle")
+        lowest_rect.highlight(label="Lowest Rectangle")
+        leftmost_rect.highlight(label="Leftmost Rectangle")
+        rightmost_rect.highlight(label="Rightmost Rectangle")
+    
+    # Demonstrate text position methods
+    print(f"\nText elements found: {len(text)}")
+    if len(text) > 0:
+        highest_text = text.highest()
+        lowest_text = text.lowest()
+        leftmost_text = text.leftmost()
+        rightmost_text = text.rightmost()
+        
+        print(f"Highest text: '{highest_text.text}' at {highest_text.bbox}")
+        print(f"Lowest text: '{lowest_text.text}' at {lowest_text.bbox}")
+        print(f"Leftmost text: '{leftmost_text.text}' at {leftmost_text.bbox}")
+        print(f"Rightmost text: '{rightmost_text.text}' at {rightmost_text.bbox}")
+        
+        # Highlight the extreme text elements
+        highest_text.highlight(label="Highest Text")
+        lowest_text.highlight(label="Lowest Text")
+        leftmost_text.highlight(label="Leftmost Text")
+        rightmost_text.highlight(label="Rightmost Text")
+    
+    # Create an output directory
+    output_dir = Path(__file__).parent / "position_output"
+    output_dir.mkdir(exist_ok=True)
+    
+    # Save the result
+    page.to_image(path=str(output_dir / "position_methods.png"), show_labels=True)
+    
+    # Demonstrate error handling for multi-page collections
+    if len(pdf.pages) > 1:
+        print("\nTesting multi-page error handling:")
+        multi_collection = pdf.pages.find_all('text')
+        try:
+            multi_collection.lowest()
+            print("ERROR: Should have raised ValueError for multi-page collection")
+        except ValueError as e:
+            print(f"Correctly raised ValueError: {e}")
+    
+    print("\nExample completed. Check 'position_output/position_methods.png' for the result.")
+
+
+if __name__ == "__main__":
+    main()

examples/region_boundary_test.py

@@ -0,0 +1,73 @@
+"""
+Test the modified region boundary logic with below() and above() method fixes.
+
+This example tests that the .below() and .above() methods correctly exclude
+the source element with the new 1-pixel offset.
+"""
+
+import os
+import sys
+import argparse
+
+# Add parent directory to path to run without installing
+sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from natural_pdf import PDF
+
+def main():
+    parser = argparse.ArgumentParser(description="Test region boundaries")
+    parser.add_argument("pdf_path", nargs="?", default="../pdfs/0500000US42001.pdf", 
+                      help="Path to PDF document")
+    args = parser.parse_args()
+    
+    print(f"Testing with PDF: {args.pdf_path}")
+    
+    # Open the PDF
+    pdf = PDF(args.pdf_path)
+    page = pdf.pages[0]
+    
+    # Find a text element to test with
+    title = page.find('text:contains("Price")')
+    if not title:
+        title = page.find('text:bold')
+        
+    if not title:
+        print("Couldn't find a suitable test element. Please provide a PDF with text elements.")
+        return
+    
+    print(f"Found element: '{title.text}' at position {title.bbox}")
+    
+    # Create region below the element
+    region_below = title.below(height=16, width="element")
+    
+    # Check if the element is in the region (it shouldn't be)
+    elements_in_region = region_below.find_all('text')
+    
+    # Print the region and elements found in it
+    print(f"\nRegion below: {region_below.bbox}")
+    print(f"Number of elements in region: {len(elements_in_region)}")
+    
+    # Check specifically if the source element is in the region
+    is_source_in_region = title in elements_in_region
+    print(f"Source element is in region: {is_source_in_region}")
+    
+    # Expand the region and check again
+    expanded_region = region_below.expand(right=40)
+    elements_in_expanded = expanded_region.find_all('text')
+    
+    print(f"\nExpanded region: {expanded_region.bbox}")
+    print(f"Number of elements in expanded region: {len(elements_in_expanded)}")
+    print(f"Elements text: {[e.text for e in elements_in_expanded]}")
+    
+    # Highlight the regions to visualize
+    title.highlight(color=(1, 0, 0, 0.3), label="Source")
+    region_below.highlight(color=(0, 1, 0, 0.3), label="Below")
+    expanded_region.highlight(color=(0, 0, 1, 0.3), label="Expanded")
+    
+    # Save the image
+    os.makedirs("output", exist_ok=True)
+    page.save_image("output/region_boundary_test.png")
+    print("\nSaved visualization to output/region_boundary_test.png")
+
+if __name__ == "__main__":
+    main()