natural-pdf 25.3.16__py3-none-any.whl

examples/__init__.py

@@ -0,0 +1,3 @@
+"""
+Examples for natural-pdf.
+"""

examples/another_exclusion_example.py

@@ -0,0 +1,20 @@
+"""
+Example demonstrating how to use exclusion zones in Natural PDF.
+"""
+
+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
+
+pdf = PDF('pdfs/Atlanta_Public_Schools_GA_sample.pdf')
+pdf.add_exclusion(lambda page: page.find('line').above())
+pdf.add_exclusion(lambda page: page.find_all('line')[-1].below())
+page = pdf.pages[2]
+page.find_all('text').highlight()
+page.save('test.png', labels=True)
+

examples/basic_usage.py

@@ -0,0 +1,190 @@
+"""
+Basic usage examples for 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 basic_example(pdf_path):
+    """Basic example using the main features."""
+    # Open the PDF
+    with PDF(pdf_path, reading_order=True) as pdf:
+        # Get basic information
+        print(f"PDF has {len(pdf)} pages")
+        
+        # First, display the PDF structure with simple text extraction
+        print("\nBASIC TEXT EXTRACTION:")
+        page_text = pdf.pages[0].extract_text()
+        print(page_text[:500] + "...")
+
+        print("\nWITH LAYOUT: ")
+        page_text = pdf.pages[0].extract_text(layout=True)
+        print(page_text[:2000] + "...")
+
+        # Direct demonstration of PDF features
+        print("\nDEMONSTRATING NATURAL PDF FEATURES:")
+        
+        page = pdf.pages[0]
+        
+        # 1. Display document structure
+        print("\n1. DOCUMENT STRUCTURE:")
+        
+        # Count different types of elements
+        print(f"  - {len(page.words)} words")
+        print(f"  - {len(page.lines)} lines")
+        print(f"  - {len(page.rects)} rectangles")
+        
+        # 2. Extract specific text using extract_text
+        print("\n2. EXTRACT TEXT FROM DOCUMENT:")
+        print(f"  Full document: {len(pdf.extract_text())} characters")
+        print(f"  First page: {len(page.extract_text())} characters")
+        
+        # 3. Find elements with specific properties
+        print("\n3. FIND ELEMENTS WITH SPECIFIC PROPERTIES:")
+        
+        # Find the thick horizontal line
+        thick_lines = pdf.find_all('line[width>=2]')
+        if thick_lines:
+            print(f"  Found thick line: {thick_lines[0].bbox}")
+        
+        # Find text with a specific pattern
+        site_text = [w for w in page.words if w.text.startswith("Site:")]
+        if site_text:
+            print(f"  Site info: {site_text[0].text}")
+        
+        # Display some example words
+        print("\n4. SAMPLE WORDS:")
+        for i, word in enumerate(page.words[:5]):
+            print(f"  - Word {i}: '{word.text}'")
+            
+        # Find all statute codes using regex pattern matching
+        print("\n5. FIND STATUTE CODES:")
+        import re
+        statute_codes = []
+        for word in page.words:
+            if re.match(r'\d+\.\d+\.\d+', word.text):
+                statute_codes.append(word.text)
+                
+        print(f"  Found {len(statute_codes)} statute codes:")
+        for code in statute_codes[:3]:
+            print(f"  - {code}")
+        
+        # Demonstrate spatial relationships with fluent API
+        print("\n6. SPATIAL RELATIONSHIPS WITH FLUENT API:")
+        
+        # Find the line with width >= 2
+        thick_line = pdf.find('line[width>=2]')
+        if thick_line:
+            print(f"  Found thick line at y={thick_line.top}")
+            
+            # Use the below() method to create a region below the line
+            # Specify width="full" for full page width
+            below_region = thick_line.below(height=50, width="full")
+            
+            # Extract text from this region
+            region_text = below_region.extract_text(preserve_whitespace=True)
+            
+            # Print the first part of the text
+            print(f"  Text from region below line: {region_text[:30]}...")
+            
+            # We can also use find_all on the region to get elements in that region
+            words_below = below_region.find_all('text')
+            if words_below:
+                print(f"  Found {len(words_below)} text elements below the line")
+                # Show the first few words
+                if len(words_below) > 0:
+                    first_few = [w.text for w in words_below[:3]]
+                    print(f"  First few words: {' '.join(first_few)}")
+                
+        # Find critical violations
+        print("\n7. FIND CRITICAL VIOLATIONS:")
+        
+        # Use simple word search with filtering
+        critical_words = []
+        for word in page.words:
+            if "Critical" in word.text:
+                critical_words.append(word)
+                
+        if critical_words:
+            print(f"  Found {len(critical_words)} critical items")
+            
+            # For each critical item, find text on the same line
+            for critical in critical_words:
+                # Simple approach: find words on same line with lower x-position
+                descriptions = []
+                for word in page.words:
+                    # Check if it's on the same line and to the left
+                    if abs(word.top - critical.top) < 5 and word.x0 < critical.x0:
+                        descriptions.append(word)
+                
+                # Sort by x-position to get the closest one
+                if descriptions:
+                    descriptions.sort(key=lambda w: w.x0)
+                    print(f"  - {descriptions[0].text}")
+                    
+            # Get statutes with critical violations
+            critical_statutes = []
+            for i, word in enumerate(page.words):
+                if "Critical" in word.text:
+                    # Look for nearby statute code
+                    for j, code_word in enumerate(page.words):
+                        if abs(code_word.top - word.top) < 5 and code_word.x0 < word.x0:
+                            if re.match(r'\d+\.\d+\.\d+', code_word.text):
+                                critical_statutes.append(code_word.text)
+                                break
+            
+            if critical_statutes:
+                print(f"  Critical violations for statutes: {', '.join(critical_statutes)}")
+                
+        # Example of the intended fluent API (even if not all parts work yet)
+        print("\n8. FLUENT API EXAMPLES (HOW THE LIBRARY IS INTENDED TO BE USED):")
+        
+        print("  Example 1: Find thick lines and extract text below them")
+        print("  ```python")
+        print("  thick_line = pdf.find('line[width>=2]')")
+        print("  text_below = thick_line.below(height=50, width='full').find_all('text')")
+        print("  for text in text_below[:3]:")
+        print("      print(text.text)")
+        print("  ```")
+        
+        print("\n  Example 2: Find critical violations and their codes")
+        print("  ```python")
+        print("  critical_items = pdf.find_all('text:contains(\"Critical\")')")
+        print("  for item in critical_items:")
+        print("      # Find codes on the same line")
+        print("      codes = pdf.find_all(f'text:matches(\"\\d+\\.\\d+\\.\\d+\")[top~={item.top}]')")
+        print("      if codes:")
+        print("          print(f\"Critical violation: {codes[0].text}\")")
+        print("  ```")
+        
+        print("\n  Example 3: Extract a table")
+        print("  ```python")
+        print("  # Find the table header")
+        print("  header = pdf.find('text:contains(\"Statute\")')")
+        print("  # Select the entire table region")
+        print("  table_region = header.until('text:contains(\"Jungle Health\")')")
+        print("  # Extract the table as data")
+        print("  table_data = table_region.extract_tables()[0]")
+        print("  ```")
+
+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 basic_usage.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)
+    
+    basic_example(pdf_path)

examples/boundary_exclusion_test.py

@@ -0,0 +1,137 @@
+"""
+Test for boundary element exclusion with real PDFs.
+This test focuses on the boundary_inclusion parameter of get_sections.
+"""
+
+import os
+import sys
+from natural_pdf import PDF
+
+def main():
+    # Get path to PDF file, use default if not provided
+    if len(sys.argv) > 1:
+        pdf_path = sys.argv[1]
+        if not os.path.exists(pdf_path):
+            print(f"Error: File {pdf_path} not found")
+            sys.exit(1)
+    else:
+        # Just use a default PDF from the pdfs directory
+        pdfs_dir = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "pdfs")
+        pdf_files = [f for f in os.listdir(pdfs_dir) if f.endswith('.pdf')]
+        if not pdf_files:
+            print("No PDF files found in the pdfs directory")
+            sys.exit(1)
+        
+        pdf_path = os.path.join(pdfs_dir, pdf_files[0])
+    
+    print(f"Using PDF: {pdf_path}")
+    
+    # Open the PDF
+    pdf = PDF(pdf_path)
+    
+    # Use the first page for testing
+    page = pdf.pages[0]
+    
+    # Find elements to use as section boundaries
+    # First try to find large text as headings
+    headings = page.find_all('text[size>=14]')
+    
+    # If not enough headings, try smaller text
+    if len(headings) < 3:
+        headings = page.find_all('text[size>=12]')
+    
+    # If still not enough, try bold text
+    if len(headings) < 3:
+        headings = page.find_all('text:bold')
+    
+    # If still not enough, use the first 3 text elements
+    if len(headings) < 3:
+        headings = page.find_all('text')[:5]
+    
+    print(f"Found {len(headings)} potential section boundaries")
+    for i, h in enumerate(headings[:5]):
+        print(f"Boundary {i+1}: {h.text}")
+    
+    # Create different sections with different boundary_inclusion settings
+    none_sections = page.get_sections(start_elements=headings, boundary_inclusion='none')
+    start_sections = page.get_sections(start_elements=headings, boundary_inclusion='start')
+    both_sections = page.get_sections(start_elements=headings, boundary_inclusion='both')
+    
+    print("\nTesting boundary element inclusion/exclusion:")
+    
+    # Check if the boundary elements are included correctly
+    for i, section in enumerate(none_sections[:3]):
+        if i >= len(headings):
+            break
+            
+        boundary = headings[i]
+        found = section._is_element_in_region(boundary)
+        print(f"None Section {i+1}: Contains boundary element: {found}")
+    
+    for i, section in enumerate(start_sections[:3]):
+        if i >= len(headings):
+            break
+            
+        boundary = headings[i]
+        found = section._is_element_in_region(boundary)
+        print(f"Start Section {i+1}: Contains boundary element: {found}")
+    
+    for i, section in enumerate(both_sections[:3]):
+        if i >= len(headings):
+            break
+            
+        boundary = headings[i]
+        found = section._is_element_in_region(boundary)
+        print(f"Both Section {i+1}: Contains boundary element: {found}")
+    
+    # Simplify our test approach - just check if:
+    # 1. 'none' sections exclude their boundary elements
+    # 2. 'start' sections include their boundary elements  
+    # 3. 'both' sections include their boundary elements
+    
+    # Check section element counts
+    print("\nElement counts in sections:")
+    for i, section in enumerate(none_sections[:3]):
+        elements = section.get_elements()
+        print(f"None Section {i+1}: {len(elements)} elements")
+        
+    for i, section in enumerate(start_sections[:3]):
+        elements = section.get_elements()
+        print(f"Start Section {i+1}: {len(elements)} elements")
+        
+    for i, section in enumerate(both_sections[:3]):
+        elements = section.get_elements() 
+        print(f"Both Section {i+1}: {len(elements)} elements")
+    
+    # Summarize test results
+    none_correct = all(
+        not section._is_element_in_region(headings[i]) 
+        for i, section in enumerate(none_sections[:3]) 
+        if i < len(headings)
+    )
+    
+    # Check only non-empty sections that have a start_element
+    start_correct = all(
+        (section.start_element is None) or section._is_element_in_region(section.start_element)
+        for section in start_sections[:3]
+        if section.get_elements()  # Skip empty sections
+    )
+    
+    both_correct = all(
+        (section.start_element is None) or section._is_element_in_region(section.start_element)
+        for section in both_sections[:3]
+        if section.get_elements()  # Skip empty sections
+    )
+    
+    print("\nTest Results Summary:")
+    print(f"- 'none' excludes boundary elements: {'PASS' if none_correct else 'FAIL'}")
+    print(f"- 'start' includes boundary elements: {'PASS' if start_correct else 'FAIL'}")
+    print(f"- 'both' includes boundary elements: {'PASS' if both_correct else 'FAIL'}")
+    
+    if none_correct and start_correct and both_correct:
+        print("\n✅ All tests PASSED!")
+    else:
+        print("\n❌ Some tests FAILED!")
+
+if __name__ == "__main__":
+    main()

examples/boundary_inclusion_fix_test.py

@@ -0,0 +1,157 @@
+"""
+Example demonstrating the fixed boundary inclusion behavior in the get_sections method.
+"""
+
+import os
+import sys
+from natural_pdf import PDF
+
+def main():
+    # Get path to PDF file, use default if not provided
+    if len(sys.argv) > 1:
+        pdf_path = sys.argv[1]
+        if not os.path.exists(pdf_path):
+            print(f"Error: File {pdf_path} not found")
+            sys.exit(1)
+    else:
+        # Use a default PDF from the pdfs directory
+        parent_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+        pdf_path = os.path.join(parent_dir, "pdfs", "2019 Statistics.pdf")
+        if not os.path.exists(pdf_path):
+            print(f"Error: Default file {pdf_path} not found")
+            sys.exit(1)
+    
+    # Open the PDF
+    pdf = PDF(pdf_path)
+    page = pdf.pages[0]  # Use the first page
+    
+    # Find some elements to use as section boundaries
+    headings = page.find_all('text[size>=12]')
+    
+    if len(headings) < 3:
+        print(f"Not enough headings found on the first page. Found: {len(headings)}")
+        sys.exit(1)
+    
+    print(f"Found {len(headings)} headings")
+    for i, heading in enumerate(headings[:5]):  # Show first 5 headings
+        print(f"Heading {i+1}: {heading.text}")
+    
+    # Create sections with different boundary inclusion settings
+    sections_none = page.get_sections(
+        start_elements=headings, 
+        boundary_inclusion='none'
+    )
+    
+    sections_start = page.get_sections(
+        start_elements=headings, 
+        boundary_inclusion='start'
+    )
+    
+    sections_both = page.get_sections(
+        start_elements=headings, 
+        boundary_inclusion='both'
+    )
+    
+    # Display the results
+    print("\nTesting if headings are correctly included/excluded:")
+    
+    # Check the sections with 'none' inclusion
+    print("\n=== Sections with boundary_inclusion='none' ===")
+    for i, section in enumerate(sections_none[:3]):  # Check first 3 sections
+        # Get all elements in this section
+        elements = section.get_elements()
+        
+        # Check if we have any elements
+        if not elements:
+            print(f"Section {i+1} is empty (has no elements)")
+            continue
+            
+        # Get the first element text
+        first_element_text = elements[0].text if hasattr(elements[0], 'text') else str(elements[0])
+        
+        # Look for a heading in all section elements
+        heading_found = False
+        for h in headings:
+            if section._is_element_in_region(h):
+                heading_found = True
+                break
+        
+        print(f"Section {i+1} contains heading: {heading_found}")
+        print(f"  First element: {first_element_text}")
+        print(f"  Element count: {len(elements)}")
+    
+    # Check the sections with 'start' inclusion
+    print("\n=== Sections with boundary_inclusion='start' ===")
+    for i, section in enumerate(sections_start[:3]):  # Check first 3 sections
+        # Get elements in this section
+        elements = section.get_elements()
+        
+        # Check if we have any elements
+        if not elements:
+            print(f"Section {i+1} is empty (has no elements)")
+            continue
+        
+        # Check if the start heading is in this section
+        original_heading = headings[i] if i < len(headings) else None
+        heading_found = False
+        if original_heading:
+            heading_found = section._is_element_in_region(original_heading)
+        
+        print(f"Section {i+1} contains start heading: {heading_found}")
+        print(f"  Start element: {section.start_element.text if section.start_element else 'None'}")
+        print(f"  Element count: {len(elements)}")
+        print(f"  First element: {elements[0].text if hasattr(elements[0], 'text') else str(elements[0])}")
+    
+    # Check the sections with 'both' inclusion
+    print("\n=== Sections with boundary_inclusion='both' ===")
+    for i, section in enumerate(sections_both[:3]):  # Check first 3 sections
+        # Get elements in this section
+        elements = section.get_elements()
+        
+        # Check if we have any elements
+        if not elements:
+            print(f"Section {i+1} is empty (has no elements)")
+            continue
+        
+        # Check if the start heading is in this section
+        original_heading = headings[i] if i < len(headings) else None
+        heading_found = False
+        if original_heading:
+            heading_found = section._is_element_in_region(original_heading)
+        
+        print(f"Section {i+1} contains start heading: {heading_found}")
+        print(f"  Start element: {section.start_element.text if section.start_element else 'None'}")
+        print(f"  Element count: {len(elements)}")
+        print(f"  First element: {elements[0].text if hasattr(elements[0], 'text') else str(elements[0])}")
+    
+    # Save output images for visual verification
+    page.highlight_all()
+    page.save_image("output/all_elements.png")
+    
+    # Let's skip the highlighting part for this test since we're getting errors
+    print("\nResults of the test:")
+    print(f"- 'none' inclusion: Sections have {len([s for s in sections_none if s.get_elements()])} non-empty out of {len(sections_none)} total")
+    print(f"- 'start' inclusion: Sections have {len([s for s in sections_start if s.get_elements()])} non-empty out of {len(sections_start)} total")
+    print(f"- 'both' inclusion: Sections have {len([s for s in sections_both if s.get_elements()])} non-empty out of {len(sections_both)} total")
+    
+    # Test successful if:
+    # 1. 'none' has no headings in its sections (verified above)
+    # 2. 'start' includes the start headings but not end headings
+    # 3. 'both' includes both start and end headings
+    
+    none_success = all(len(s.get_elements()) == 0 or not any(s._is_element_in_region(h) for h in headings) for s in sections_none[:3])
+    start_success = all(s.start_element in headings and s._is_element_in_region(s.start_element) for s in sections_start[:3] if s.start_element)
+    both_success = all((s.start_element in headings and s._is_element_in_region(s.start_element)) for s in sections_both[:3] if s.start_element)
+    
+    print("\nTest Results:")
+    print(f"- 'none' excludes headings: {'Success' if none_success else 'Failure'}")
+    print(f"- 'start' includes start headings: {'Success' if start_success else 'Failure'}")
+    print(f"- 'both' includes start headings: {'Success' if both_success else 'Failure'}")
+    
+    if none_success and start_success and both_success:
+        print("\n✅ Fix was successful!")
+    else:
+        print("\n❌ Fix needs more work.")
+
+if __name__ == "__main__":
+    main()

examples/chainable_layout_example.py

@@ -0,0 +1,70 @@
+"""
+Example demonstrating the chainable analyze_layout method.
+
+This example shows how to use the chainable analyze_layout method
+to create more concise code by chaining method calls together.
+"""
+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", "2019 Statistics.pdf")
+
+# Set up argument parser
+parser = argparse.ArgumentParser(description="Chainable layout analysis 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)")
+parser.add_argument("--conf", type=float, default=0.2, help="Confidence threshold for detections")
+parser.add_argument("--output", type=str, default=None, help="Output file path for highlighted image")
+args = parser.parse_args()
+
+print(f"Analyzing PDF: {args.pdf_path}")
+print(f"Page: {args.page}")
+print(f"Confidence threshold: {args.conf}")
+
+# Load the PDF
+pdf = PDF(args.pdf_path)
+page = pdf.pages[args.page]
+
+print("Running document layout analysis with method chaining...")
+
+# Example 1: Chain analyze_layout with highlight_all
+page.analyze_layout(confidence=args.conf)\
+    .highlight_all(include_layout_regions=True)
+
+print(f"Found {len(page.detected_layout_regions)} regions with confidence >= {args.conf}")
+
+# Example 2: Save a highlighted image with labels
+output_path = args.output or os.path.join(root_dir, "output", "chainable_layout.png")
+os.makedirs(os.path.dirname(output_path), exist_ok=True)
+
+# Chain the whole sequence: clear highlights, analyze layout, highlight all, save image
+page.clear_highlights()\
+    .analyze_layout(model="yolo", confidence=args.conf)\
+    .highlight_all(include_layout_regions=True)\
+    .to_image(path=output_path, show_labels=True)
+
+print(f"Saved highlighted image to {output_path}")
+
+# Example 3: Chain with specialized highlighting
+if page.find_all('region[type=title]'):
+    result_path = os.path.join(os.path.dirname(output_path), "titles_only.png")
+    
+    page.clear_highlights()\
+        .analyze_layout(confidence=args.conf)\
+        .find_all('region[type=title]')\
+        .highlight(label="Document Titles", color=(1, 0, 0, 0.4))
+    
+    page.to_image(path=result_path, show_labels=True)
+    print(f"Saved titles-only highlighted image to {result_path}")
+
+print("Done!")

examples/color_basic_test.py

@@ -0,0 +1,49 @@
+"""
+Simple test for color conversion.
+"""
+
+# Test color conversion
+def normalize_color(color):
+    """Test function that normalizes colors from various formats to RGB(A) integers."""
+    if isinstance(color, tuple):
+        # Convert values to integers in 0-255 range
+        processed_color = []
+        for i, c in enumerate(color):
+            if isinstance(c, float):
+                # 0.0-1.0 float format
+                if c <= 1.0:
+                    processed_color.append(int(c * 255))
+                # Already in 0-255 range but as float
+                else:
+                    processed_color.append(int(c))
+            else:
+                processed_color.append(c)
+                
+        # Default alpha value if needed
+        if len(processed_color) == 3:
+            processed_color.append(100)  # Default alpha
+            
+        return tuple(processed_color)
+    else:
+        # Default if invalid color is provided
+        return (255, 255, 0, 100)  # Yellow with semi-transparency
+
+# Test cases
+print("Testing color conversion:")
+print("-----------------------")
+
+test_cases = [
+    ((255, 0, 0, 128), "Integer RGB with alpha"),
+    ((255, 0, 0), "Integer RGB without alpha"),
+    ((0.0, 1.0, 0.0, 0.5), "Float RGB with alpha (0-1)"),
+    ((0.0, 1.0, 0.0), "Float RGB without alpha (0-1)"),
+    ((0.5, 0.5, 255, 0.7), "Mixed float and integer"),
+    ((0.5, 0.5, 255), "Mixed without alpha"),
+    ((128.5, 64.3, 200.7, 50.9), "Float values > 1"),
+]
+
+for color, desc in test_cases:
+    result = normalize_color(color)
+    print(f"{desc}: {color} -> {result}")
+
+print("\nAll tests completed!")