natural-pdf 25.3.16__py3-none-any.whl

examples/highlight_all_example.py

@@ -0,0 +1,82 @@
+"""
+Example demonstrating the highlight_all feature of natural-pdf.
+"""
+import os
+import sys
+
+# Add the parent directory to the path to import the package
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))
+
+from natural_pdf import PDF
+
+def highlight_all_example(pdf_path):
+    """Demonstrates the highlight_all feature for quick visual inspection."""
+    # Open the PDF
+    with PDF(pdf_path) as pdf:
+        page = pdf.pages[0]
+        
+        print(f"PDF loaded: {pdf_path}")
+        print(f"PDF has {len(pdf)} pages")
+        
+        # Create an output directory for saving images
+        output_dir = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', 'output'))
+        os.makedirs(output_dir, exist_ok=True)
+        
+        # EXAMPLE 1: Highlight all elements on the page
+        print("\nEXAMPLE 1: Highlighting all elements")
+        print("-" * 60)
+        
+        # Count all element types first
+        element_counts = {
+            'Text': len(page.words),
+            'Characters': len(page.chars),
+            'Lines': len(page.lines),
+            'Rectangles': len(page.rects)
+        }
+        
+        for element_type, count in element_counts.items():
+            print(f"Found {count} {element_type.lower()}")
+        
+        # Highlight all elements
+        page.highlight_all()
+        
+        # Save the image with a legend using to_image
+        output_file = os.path.join(output_dir, "highlight_all.png")
+        page.to_image(path=output_file, show_labels=True)
+        print(f"Saved all highlighted elements to: {output_file}")
+        
+        # Clear highlights for the next example
+        page.clear_highlights()
+        
+        # EXAMPLE 2: Highlight only specific element types
+        print("\nEXAMPLE 2: Highlighting only specific element types")
+        print("-" * 60)
+        
+        # Highlight only text and lines
+        page.highlight_all(include_types=['text', 'line'])
+        
+        # Save the image with a legend using to_image
+        output_file = os.path.join(output_dir, "highlight_specific_types.png")
+        page.to_image(path=output_file, show_labels=True)
+        print(f"Saved with only text and lines highlighted to: {output_file}")
+        
+        print("\nEnd of highlight_all demonstration.")
+
+if __name__ == "__main__":
+    # Default to example PDF if no path is provided
+    if len(sys.argv) < 2:
+        # Use the example PDF in the pdfs directory
+        pdf_path = os.path.abspath(os.path.join(
+            os.path.dirname(__file__), '..', 'pdfs', '01-practice.pdf'))
+        if not os.path.exists(pdf_path):
+            print("Example PDF not found. Please provide a path to a PDF file.")
+            print("Usage: python highlight_all_example.py [path/to/file.pdf]")
+            sys.exit(1)
+    else:
+        pdf_path = sys.argv[1]
+        # Check if the file exists
+        if not os.path.exists(pdf_path):
+            print(f"File not found: {pdf_path}")
+            sys.exit(1)
+    
+    highlight_all_example(pdf_path)

examples/highlight_attributes_test.py

@@ -0,0 +1,114 @@
+"""
+Demonstrate highlighting with attributes displayed.
+
+This example shows how to display element attributes like confidence scores
+directly on the highlighting, using the include_attrs parameter.
+"""
+import os
+import sys
+import argparse
+from typing import List
+
+# 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="Highlight attributes example")
+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 attribute display on: {args.pdf_path}")
+print(f"Page: {args.page}")
+
+# Load the PDF
+pdf = PDF(args.pdf_path)
+page = pdf.pages[args.page]
+
+# Test 1: Standard highlight without attributes
+print("\nTest 1: Standard layout highlighting (no attributes)")
+page.clear_highlights()
+page.analyze_layout(model="yolo", confidence=0.2)
+page.analyze_layout(model="tatr", confidence=0.2, existing="append")
+page.highlight_layout()
+output_path = os.path.join(root_dir, "output", "highlight_no_attrs.png")
+page.to_image(path=output_path, show_labels=True)
+print(f"Saved to {output_path}")
+
+# Test 2: Highlight with confidence and model attributes
+print("\nTest 2: Layout highlighting with explicit confidence and model attributes")
+page.clear_highlights()
+for region in page.detected_layout_regions:
+    # Use a simplified label since details will be shown on the highlight
+    label = f"{region.region_type}"
+    # Explicitly show confidence and model directly on the highlight
+    region.highlight(
+        label=label,
+        include_attrs=['confidence', 'model']
+    )
+output_path = os.path.join(root_dir, "output", "highlight_with_attrs.png")
+page.to_image(path=output_path, show_labels=True)
+print(f"Saved to {output_path}")
+
+# Test 3: Use highlight_all with include_layout_regions=True (no attributes by default)
+print("\nTest 3: Using highlight_all with include_layout_regions=True (no attributes)")
+page.clear_highlights()
+page.highlight_all(
+    include_layout_regions=True,
+    include_types=['text'],
+    layout_confidence=0.2
+)
+output_path = os.path.join(root_dir, "output", "highlight_all_with_attrs.png")
+page.to_image(path=output_path, show_labels=True)
+print(f"Saved to {output_path}")
+
+# Test 4: Create a collection of regions and highlight with custom attributes
+print("\nTest 4: Highlight a collection with custom attributes")
+page.clear_highlights()
+
+# Create collections by region type
+from natural_pdf.elements.collections import ElementCollection
+
+# Get high confidence regions
+high_conf_regions = [r for r in page.detected_layout_regions if hasattr(r, 'confidence') and r.confidence >= 0.8]
+if high_conf_regions:
+    high_conf_collection = ElementCollection(high_conf_regions)
+    high_conf_collection.highlight(
+        label="High Confidence",
+        color=(0, 1, 0, 0.3),  # Green for high confidence
+        include_attrs=['region_type', 'confidence', 'model']
+    )
+
+# Get medium confidence regions
+med_conf_regions = [r for r in page.detected_layout_regions if hasattr(r, 'confidence') and 0.5 <= r.confidence < 0.8]
+if med_conf_regions:
+    med_conf_collection = ElementCollection(med_conf_regions)
+    med_conf_collection.highlight(
+        label="Medium Confidence",
+        color=(1, 1, 0, 0.3),  # Yellow for medium confidence
+        include_attrs=['region_type', 'confidence', 'model']
+    )
+
+# Get low confidence regions
+low_conf_regions = [r for r in page.detected_layout_regions if hasattr(r, 'confidence') and r.confidence < 0.5]
+if low_conf_regions:
+    low_conf_collection = ElementCollection(low_conf_regions)
+    low_conf_collection.highlight(
+        label="Low Confidence",
+        color=(1, 0, 0, 0.3),  # Red for low confidence
+        include_attrs=['region_type', 'confidence', 'model']
+    )
+
+output_path = os.path.join(root_dir, "output", "highlight_by_confidence.png")
+page.to_image(path=output_path, show_labels=True)
+print(f"Saved to {output_path}")
+
+print("\nDone!")

examples/highlight_confidence_display.py

@@ -0,0 +1,122 @@
+"""
+Demonstrate the enhanced confidence display feature.
+
+This example shows how confidence scores are displayed by default
+and also demonstrates customizing the attributes displayed.
+"""
+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="Confidence display example")
+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"Demonstrating confidence display on: {args.pdf_path}")
+print(f"Page: {args.page}")
+
+# Load the PDF
+pdf = PDF(args.pdf_path)
+page = pdf.pages[args.page]
+
+# Run layout analysis
+print("\nRunning layout analysis...")
+page.analyze_layout(model="yolo", confidence=0.1)  # Use low confidence to show a range of values
+regions = page.detected_layout_regions
+print(f"Found {len(regions)} layout regions")
+
+# Example 1: Basic highlighting without attributes
+print("\nExample 1: Basic highlighting (no attributes)")
+page.clear_highlights()
+# Regular highlighting without showing confidence
+for region in regions:
+    region.highlight(label=region.region_type)
+
+output_path = os.path.join(root_dir, "output", "basic_highlighting.png")
+page.to_image(path=output_path, show_labels=True)
+print(f"Saved to {output_path}")
+
+# Example 2: Explicitly adding confidence
+print("\nExample 2: Explicitly showing confidence")
+page.clear_highlights()
+for region in regions:
+    region.highlight(
+        label=region.region_type,
+        include_attrs=['confidence']
+    )
+output_path = os.path.join(root_dir, "output", "explicit_confidence_display.png")
+page.to_image(path=output_path, show_labels=True)
+print(f"Saved to {output_path}")
+
+# Example 3: Show confidence values with different colors based on confidence level
+print("\nExample 3: Color-coded by confidence level")
+page.clear_highlights()
+
+# Group regions by confidence
+high_conf = [r for r in regions if r.confidence >= 0.8]
+med_conf = [r for r in regions if 0.5 <= r.confidence < 0.8]
+low_conf = [r for r in regions if 0.2 <= r.confidence < 0.5]
+very_low_conf = [r for r in regions if r.confidence < 0.2]
+
+print(f"  High confidence (>=0.8): {len(high_conf)} regions")
+print(f"  Medium confidence (0.5-0.8): {len(med_conf)} regions")
+print(f"  Low confidence (0.2-0.5): {len(low_conf)} regions")
+print(f"  Very low confidence (<0.2): {len(very_low_conf)} regions")
+
+# Highlight each group with appropriate color
+from natural_pdf.elements.collections import ElementCollection
+if high_conf:
+    ElementCollection(high_conf).highlight(
+        label="High Confidence",
+        color=(0, 0.8, 0, 0.3),  # Green
+        include_attrs=['confidence']  # Show the confidence values
+    )
+if med_conf:
+    ElementCollection(med_conf).highlight(
+        label="Medium Confidence",
+        color=(0.8, 0.8, 0, 0.3),  # Yellow
+        include_attrs=['confidence']  # Show the confidence values
+    )
+if low_conf:
+    ElementCollection(low_conf).highlight(
+        label="Low Confidence",
+        color=(0.8, 0.4, 0, 0.3),  # Orange
+        include_attrs=['confidence']  # Show the confidence values
+    )
+if very_low_conf:
+    ElementCollection(very_low_conf).highlight(
+        label="Very Low Confidence",
+        color=(0.8, 0, 0, 0.3),  # Red
+        include_attrs=['confidence']  # Show the confidence values
+    )
+
+output_path = os.path.join(root_dir, "output", "confidence_color_coded.png")
+page.to_image(path=output_path, show_labels=True)
+print(f"Saved to {output_path}")
+
+# Example 4: Show multiple attributes (confidence + type)
+print("\nExample 4: Showing multiple attributes (confidence, region_type)")
+page.clear_highlights()
+for region in regions:
+    region.highlight(
+        include_attrs=['confidence', 'region_type'],
+        color=(0, 0.5, 0.8, 0.3)  # Blue
+    )
+output_path = os.path.join(root_dir, "output", "multiple_attributes_display.png")
+page.to_image(path=output_path, show_labels=False)  # No legend needed
+print(f"Saved to {output_path}")
+
+print("\nDone!")

examples/highlight_demo.py

@@ -0,0 +1,110 @@
+"""
+Demo script to show highlight color cycling behavior.
+"""
+
+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 highlight_demo():
+    # Get PDF path
+    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}")
+    
+    # Create output directory
+    output_dir = Path(__file__).parent / "highlight_demo_output"
+    output_dir.mkdir(exist_ok=True)
+    
+    # Load PDF
+    pdf = PDF(pdf_path)
+    page = pdf.pages[0]
+    
+    # Demo 1: Default behavior - consistent color without label
+    print("Demo 1: Default behavior - consistent color without label")
+    texts = page.find_all('text')[:5]  # Get first 5 text elements for demo
+    
+    # Highlight each element individually
+    for i, text in enumerate(texts):
+        text.highlight()  # No label - should use consistent color (yellow)
+    
+    # Save result
+    page.save(str(output_dir / "demo1_default_no_label.png"), labels=True)
+    page.clear_highlights()
+    
+    # Demo 2: With cycle_colors=True - different colors without label
+    print("Demo 2: With cycle_colors=True - different colors without label")
+    
+    # Highlight each element individually with cycling
+    for i, text in enumerate(texts):
+        text.highlight(cycle_colors=True)  # No label but with cycling
+    
+    # Save result
+    page.save(str(output_dir / "demo2_cycling_no_label.png"), labels=True)
+    page.clear_highlights()
+    
+    # Demo 3: With labels - different colors for different labels
+    print("Demo 3: With labels - different colors for different labels")
+    
+    # Highlight each element with a unique label
+    for i, text in enumerate(texts):
+        text.highlight(label=f"Element {i+1}")  # Different labels
+    
+    # Save result
+    page.save(str(output_dir / "demo3_with_labels.png"), labels=True)
+    page.clear_highlights()
+    
+    # Demo 4: With same label - same color
+    print("Demo 4: With same label - same color")
+    
+    # Highlight all with the same label
+    for i, text in enumerate(texts):
+        text.highlight(label="Group A")  # Same label - should use same color
+    
+    # Save result
+    page.save(str(output_dir / "demo4_same_label.png"), labels=True)
+    page.clear_highlights()
+    
+    # Demo 5: Using highlight_all with default settings
+    print("Demo 5: Using highlight_all with default settings")
+    
+    # Highlight all elements by type
+    page.highlight_all()  # Default: cycle_colors=True
+    
+    # Save result
+    page.save(str(output_dir / "demo5_highlight_all_default.png"), labels=True)
+    page.clear_highlights()
+    
+    # Demo 6: Using highlight_all with cycle_colors=False
+    print("Demo 6: Using highlight_all with cycle_colors=False")
+    
+    # Highlight all elements by type without cycling
+    page.highlight_all(cycle_colors=False)
+    
+    # Save result
+    page.save(str(output_dir / "demo6_highlight_all_no_cycling.png"), labels=True)
+    page.clear_highlights()
+    
+    print(f"Results saved to {output_dir}/")
+
+
+if __name__ == "__main__":
+    highlight_demo()

examples/highlight_float_test.py

@@ -0,0 +1,71 @@
+"""
+Test script to verify highlighting with float colors.
+This is a simplified version of the test without OCR to test just the color handling.
+"""
+import os
+import sys
+
+# Add the parent directory to the path to import the package
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))
+
+from natural_pdf import PDF
+
+def main():
+    """Test that highlighting works with float colors."""
+    # Default to example PDF
+    pdf_path = os.path.abspath(os.path.join(
+        os.path.dirname(__file__), '..', 'pdfs', '01-practice.pdf'))
+    
+    if not os.path.exists(pdf_path):
+        print(f"Example PDF not found: {pdf_path}")
+        return
+        
+    # Create an output directory for saving images
+    output_dir = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', 'output'))
+    os.makedirs(output_dir, exist_ok=True)
+    
+    print(f"Testing highlighting with float colors...")
+        
+    # Open the PDF
+    with PDF(pdf_path) as pdf:
+        page = pdf.pages[0]
+        
+        # Get some text elements
+        elements = page.find_all('text')[:4]
+        
+        if len(elements) < 4:
+            print("Not enough text elements found in the PDF")
+            return
+            
+        # Test with various color formats
+        # Example 1: RGB float 0-1 with alpha
+        elements[0].highlight(
+            color=(0.0, 1.0, 0.0, 0.5),  # Green semi-transparent
+            label="Green Float"
+        )
+        
+        # Example 2: RGB float 0-1 without alpha
+        elements[1].highlight(
+            color=(1.0, 0.0, 0.0),  # Red
+            label="Red Float"
+        )
+        
+        # Example 3: Mixed integer and float
+        elements[2].highlight(
+            color=(0.5, 0.5, 255, 0.7),  # Mixed format
+            label="Mixed"
+        )
+        
+        # Example 4: Integer RGB with alpha
+        elements[3].highlight(
+            color=(0, 0, 255, 100),  # Blue
+            label="Blue Integer"
+        )
+        
+        # Save the highlighted image
+        highlight_file = os.path.join(output_dir, "highlight_float_test.png")
+        page.to_image(path=highlight_file, show_labels=True)
+        print(f"Saved to: {highlight_file}")
+        
+if __name__ == "__main__":
+    main()

examples/highlight_test.py

@@ -0,0 +1,147 @@
+"""
+Test script to verify highlighting with the same label uses the same color.
+"""
+import os
+import sys
+
+# Add the parent directory to the path to import the package
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))
+
+from natural_pdf import PDF
+
+def highlight_label_test(pdf_path):
+    """Test that highlighting colors are consistent for the same label."""
+    # Open the PDF
+    with PDF(pdf_path) as pdf:
+        page = pdf.pages[0]
+        
+        print(f"PDF loaded: {pdf_path}")
+        
+        # Create an output directory for saving images
+        output_dir = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', 'output'))
+        os.makedirs(output_dir, exist_ok=True)
+        
+        # Find bold text elements
+        headings = page.find_all('text:bold')
+        print(f"Found {len(headings)} bold headings")
+        
+        # Display the first few headings
+        for i, h in enumerate(headings[:5]):
+            print(f"  {i+1}. '{h.text}' at {h.bbox}")
+        
+        # Apply highlighting with a label
+        print("\nHighlighting bold headings...")
+        headings.highlight(label="Bold Headings")
+        
+        # Save the image
+        output_file = os.path.join(output_dir, "highlight_test.png")
+        page.save(output_file, labels=True)
+        print(f"Saved to: {output_file}")
+        
+        # Now let's test another case where we add elements individually
+        page.clear_highlights()
+        
+        print("\nTesting individual elements with same label...")
+        
+        # Find elements with different text
+        summary = page.find('text:contains("Summary:")')
+        site = page.find('text:contains("Site:")')
+        date = page.find('text:contains("Date:")')
+        
+        # Highlight them with the same label
+        print("Highlighting 'Summary:' with label 'Key Fields'")
+        summary.highlight(label="Key Fields")
+        
+        print("Highlighting 'Site:' with label 'Key Fields'")
+        site.highlight(label="Key Fields") 
+        
+        print("Highlighting 'Date:' with label 'Key Fields'")
+        date.highlight(label="Key Fields")
+        
+        # Save the image
+        output_file = os.path.join(output_dir, "highlight_test_individual.png")
+        page.save(output_file, labels=True)
+        print(f"Saved to: {output_file}")
+
+def highlight_color_test(pdf_path):
+    """Test highlighting with float and integer color values."""
+    print("\n=== Testing highlight with different color formats ===")
+    
+    # Create output directory
+    output_dir = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', 'output'))
+    os.makedirs(output_dir, exist_ok=True)
+    
+    # Open the PDF
+    with PDF(pdf_path) as pdf:
+        page = pdf.pages[0]
+        
+        # Clear any existing highlights
+        page.clear_highlights()
+        
+        # Test with integer colors (0-255)
+        text1 = page.find('text')
+        print(f"1. Using integer color (255, 0, 0, 128) for '{text1.text}'")
+        text1.highlight(color=(255, 0, 0, 128), label="Red (Integer)")
+        
+        # Test with float colors (0.0-1.0)
+        text2 = page.find_all('text')[5]
+        print(f"2. Using float color (0.0, 1.0, 0.0, 0.5) for '{text2.text}'")
+        text2.highlight(color=(0.0, 1.0, 0.0, 0.5), label="Green (Float)")
+        
+        # Test with partial float colors
+        text3 = page.find_all('text')[10]
+        print(f"3. Using mixed color (0.5, 0.5, 255, 0.7) for '{text3.text}'")
+        text3.highlight(color=(0.5, 0.5, 255, 0.7), label="Mixed")
+        
+        # Test with RGB only (no alpha)
+        text4 = page.find_all('text')[15]
+        print(f"4. Using RGB-only color (0.0, 0.0, 1.0) for '{text4.text}'")
+        text4.highlight(color=(0.0, 0.0, 1.0), label="Blue (No Alpha)")
+        
+        # Save the highlighted page
+        highlight_path = os.path.join(output_dir, "highlight_test_colors.png")
+        page.to_image(path=highlight_path, show_labels=True)
+        print(f"Saved highlighted image to {highlight_path}")
+        
+        # Also try individual highlighting to test each color format separately
+        for i, (text, color, label) in enumerate([
+            (text1, (255, 0, 0, 128), "Red"),
+            (text2, (0.0, 1.0, 0.0, 0.5), "Green"),
+            (text3, (0.5, 0.5, 255, 0.7), "Mixed"),
+            (text4, (0.0, 0.0, 1.0), "Blue")
+        ]):
+            page.clear_highlights()
+            text.highlight(color=color, label=label)
+            individual_path = os.path.join(output_dir, f"highlight_color_test_{i+1}.png")
+            page.to_image(path=individual_path, show_labels=True)
+            print(f"Saved individual highlight {i+1} to {individual_path}")
+        
+        print("Color highlight test complete")
+
+if __name__ == "__main__":
+    # Default to example PDF if no path is provided
+    if len(sys.argv) < 2:
+        # Use the example PDF in the pdfs directory
+        pdf_path = os.path.abspath(os.path.join(
+            os.path.dirname(__file__), '..', 'pdfs', '01-practice.pdf'))
+        if not os.path.exists(pdf_path):
+            print("Example PDF not found. Please provide a path to a PDF file.")
+            print("Usage: python highlight_test.py [path/to/file.pdf]")
+            sys.exit(1)
+    else:
+        pdf_path = sys.argv[1]
+        # Check if the file exists
+        if not os.path.exists(pdf_path):
+            print(f"File not found: {pdf_path}")
+            sys.exit(1)
+    
+    # Get the test name from arguments if provided
+    test_name = "all"
+    if len(sys.argv) >= 3:
+        test_name = sys.argv[2].lower()
+    
+    if test_name == "labels" or test_name == "all":
+        highlight_label_test(pdf_path)
+        
+    if test_name == "colors" or test_name == "all":
+        highlight_color_test(pdf_path)