natural-pdf 0.1.3__py3-none-any.whl → 0.1.5__py3-none-any.whl

docs/layout-analysis/index.md

@@ -0,0 +1,185 @@
+# Document Layout Analysis
+
+Natural PDF can automatically detect the structure of a document (titles, paragraphs, tables, figures) using layout analysis models. This guide shows how to use this feature.
+
+## Setup
+
+We'll use a sample PDF that includes various layout elements.
+
+```python
+from natural_pdf import PDF
+
+pdf = PDF("https://github.com/jsoma/natural-pdf/raw/refs/heads/main/pdfs/01-practice.pdf")
+page = pdf.pages[0]
+
+page.to_image(width=700)
+```
+
+## Running Basic Layout Analysis
+
+Use the `analyze_layout()` method. By default, it uses the YOLO model.
+
+```python
+# Analyze the layout using the default engine (YOLO)
+# This adds 'region' elements to the page
+page.analyze_layout()
+```
+
+```python
+# Find all detected regions
+regions = page.find_all('region')
+len(regions) # Show how many regions were detected
+```
+
+```python
+first_region = regions[0]
+f"First region: type='{first_region.type}', confidence={first_region.confidence:.2f}"
+```
+
+## Visualizing Detected Layout
+
+Use `highlight()` or `show()` on the detected regions.
+
+```python
+# Highlight all detected regions, colored by type
+regions.highlight(group_by='type')
+page.to_image(width=700)
+```
+
+## Finding Specific Region Types
+
+Use attribute selectors to find regions of a specific type.
+
+```python
+# Find all detected titles
+titles = page.find_all('region[type=title]')
+titles
+```
+
+```python
+titles.show()
+```
+
+```python
+page.find_all('region[type=table]').show()
+```
+
+## Working with Layout Regions
+
+Detected regions are like any other `Region` object. You can extract text, find elements within them, etc.
+
+```python
+page.find('region[type=table]').extract_text(layout=True)
+```
+
+## Using Different Layout Models
+
+Natural PDF supports multiple engines (`yolo`, `paddle`, `tatr`). Specify the engine when calling `analyze_layout`.
+
+*Note: Using different engines requires installing the corresponding extras (e.g., `natural-pdf[layout_paddle]`).* `yolo` is the default.
+
+```python
+page.clear_detected_layout_regions()
+page.clear_highlights()
+
+page.analyze_layout(engine="paddle")
+page.find_all('region[model=paddle]').highlight(group_by='region_type')
+page.to_image(width=700)
+```
+
+```python
+# Analyze using Table Transformer (TATR) - specialized for tables
+page.clear_detected_layout_regions()
+page.clear_highlights()
+
+page.analyze_layout(engine="tatr")
+page.find_all('region[model=tatr]').highlight(group_by='region_type')
+page.to_image(width=700)
+```
+
+```python
+# Analyze using Table Transformer (TATR) - specialized for tables
+page.clear_detected_layout_regions()
+page.clear_highlights()
+
+page.analyze_layout(engine="docling")
+page.find_all('region[model=docling]').highlight(group_by='region_type')
+page.to_image(width=700)
+```
+
+```python
+# Analyze using Table Transformer (TATR) - specialized for tables
+page.clear_detected_layout_regions()
+page.clear_highlights()
+
+page.analyze_layout(engine="surya")
+page.find_all('region[model=surya]').highlight(group_by='region_type')
+page.to_image(width=700)
+```
+
+*Note: Calling `analyze_layout` multiple times (even with the same engine) can add duplicate regions. You might want to use `page.clear_detected_layout_regions()` first, or filter by model using `region[model=yolo]`.* 
+
+## Controlling Confidence Threshold
+
+Filter detections by their confidence score.
+
+```python
+# Re-run YOLO analysis (clearing previous results might be good practice)
+page.clear_detected_layout_regions()
+page.analyze_layout(engine="yolo")
+
+# Find only high-confidence regions (e.g., >= 0.8)
+high_conf_regions = page.find_all('region[confidence>=0.8]')
+len(high_conf_regions)
+```
+
+## Table Structure with TATR
+
+The TATR engine provides detailed table structure elements (`table`, `table-row`, `table-column`, `table-column-header`). This is very useful for precise table extraction.
+
+```python
+# Ensure TATR analysis has been run
+page.clear_detected_layout_regions()
+page.clear_highlights()
+
+page.analyze_layout(engine="tatr")
+page.find_all('region[model=tatr]').highlight(group_by='region_type')
+page.to_image(width=700)
+```
+
+```python
+# Find different structural elements from TATR
+tables = page.find_all('region[type=table][model=tatr]')
+rows = page.find_all('region[type=table-row][model=tatr]')
+cols = page.find_all('region[type=table-column][model=tatr]')
+hdrs = page.find_all('region[type=table-column-header][model=tatr]')
+
+f"Found: {len(tables)} tables, {len(rows)} rows, {len(cols)} columns, {len(hdrs)} headers (from TATR)"
+```
+
+### Enhanced Table Extraction with TATR
+
+When a `region[type=table]` comes from the TATR model, `extract_table()` can use the underlying row/column structure for more robust extraction.
+
+```python
+# Find the TATR table region again
+tatr_table = page.find('region[type=table][model=tatr]')
+
+# This extraction uses the detected rows/columns
+tatr_table.extract_table()
+```
+
+if you'd like the normal approach instead of the "intelligent" one, you can ask for pdfplumber.
+
+```python
+# This extraction uses the detected rows/columns
+tatr_table.extract_table(method='pdfplumber')
+```
+
+## Next Steps
+
+Layout analysis provides regions that you can use for:
+
+- [Table Extraction](../tables/index.ipynb): Especially powerful with TATR regions.
+- [Text Extraction](../text-extraction/index.ipynb): Extract text only from specific region types (e.g., paragraphs).
+- [Document QA](../document-qa/index.ipynb): Focus question answering on specific detected regions.

docs/ocr/index.md

@@ -0,0 +1,222 @@
+# OCR Integration
+
+Natural PDF includes OCR (Optical Character Recognition) to extract text from scanned documents or images embedded in PDFs.
+
+## OCR Engine Comparison
+
+Natural PDF supports multiple OCR engines:
+
+| Feature              | EasyOCR                            | PaddleOCR                                | Surya OCR                             |
+|----------------------|------------------------------------|------------------------------------------|---------------------------------------|
+| **Installation**     | `natural-pdf[easyocr]`             | `natural-pdf[paddle]`                    | `natural-pdf[surya]`                  |
+| **Primary Strength** | Good general performance, simpler  | Excellent Asian language, speed        | High accuracy, multilingual lines     |
+| **Speed**            | Moderate                           | Fast                                     | Moderate (GPU recommended)            |
+| **Memory Usage**     | Higher                             | Efficient                                | Higher (GPU recommended)            |
+| **Paragraph Detect** | Yes (via option)                   | No                                       | No (focuses on lines)                 |
+| **Handwritten**      | Better support                     | Limited                                  | Limited                               |
+| **Small Text**       | Moderate                           | Good                                     | Good                                  |
+| **When to Use**      | General documents, handwritten text| Asian languages, speed-critical tasks    | Highest accuracy needed, line-level   |
+
+## Basic OCR Usage
+
+Apply OCR directly to a page or region:
+
+```python
+from natural_pdf import PDF
+
+# Assume 'page' is a Page object from a PDF
+page = pdf.pages[0]
+
+# Apply OCR using the default engine (or specify one)
+ocr_elements = page.apply_ocr(languages=['en'])
+
+# Extract text (will use the results from apply_ocr if run previously)
+text = page.extract_text()
+print(text)
+```
+
+## Configuring OCR
+
+Specify the engine and basic options directly:
+
+## OCR Configuration
+
+```python
+# Use PaddleOCR for Chinese and English
+ocr_elements = page.apply_ocr(engine='paddle', languages=['zh-cn', 'en'])
+
+# Use EasyOCR with a lower confidence threshold
+ocr_elements = page.apply_ocr(engine='easyocr', languages=['en'], min_confidence=0.3)
+```
+
+For advanced, engine-specific settings, use the Options classes:
+
+```python
+from natural_pdf.ocr import PaddleOCROptions, EasyOCROptions, SuryaOCROptions
+
+# --- Configure PaddleOCR ---
+paddle_opts = PaddleOCROptions(
+    languages=['en', 'zh-cn'],
+    use_gpu=True,         # Explicitly enable GPU if available
+    use_angle_cls=False,  # Disable text direction classification (if text is upright)
+    det_db_thresh=0.25,   # Lower detection threshold (more boxes, potentially noisy)
+    rec_batch_num=16      # Increase recognition batch size for potential speedup on GPU
+    # rec_char_dict_path='/path/to/custom_dict.txt' # Optional: Path to a custom character dictionary
+    # See PaddleOCROptions documentation or source code for all parameters
+ )
+ocr_elements = page.apply_ocr(engine='paddle', options=paddle_opts)
+
+# --- Configure EasyOCR ---
+easy_opts = EasyOCROptions(
+    languages=['en', 'fr'],
+    gpu=True,            # Explicitly enable GPU if available
+    paragraph=True,      # Group results into paragraphs (if structure is clear)
+    detail=1,            # Ensure bounding boxes are returned (required)
+    text_threshold=0.6,  # Confidence threshold for text detection (adjust based on tuning table)
+    link_threshold=0.4,  # Standard EasyOCR param, uncomment if confirmed in wrapper
+    low_text=0.4,        # Standard EasyOCR param, uncomment if confirmed in wrapper
+    batch_size=8         # Processing batch size (adjust based on memory)
+    # See EasyOCROptions documentation or source code for all parameters
+ )
+ocr_elements = page.apply_ocr(engine='easyocr', options=easy_opts)
+
+# --- Configure Surya OCR ---
+# Surya focuses on line detection and recognition
+surya_opts = SuryaOCROptions(
+    languages=['en', 'de'], # Specify languages for recognition
+    # device='cuda',       # Use GPU ('cuda') or CPU ('cpu') <-- Set via env var TORCH_DEVICE
+    min_confidence=0.4   # Example: Adjust minimum confidence for results
+    # Core Surya options like device, batch size, and thresholds are typically
+    # set via environment variables (see note below).
+)
+ocr_elements = page.apply_ocr(engine='surya', options=surya_opts)
+```
+
+## Multiple Languages
+
+OCR supports multiple languages:
+
+```python
+# Recognize English and Spanish text
+pdf = PDF('multilingual.pdf', ocr={
+    'enabled': True,
+    'languages': ['en', 'es']
+})
+
+# Multiple languages with PaddleOCR
+pdf = PDF('multilingual_document.pdf', 
+          ocr_engine='paddleocr',
+          ocr={
+              'enabled': True,
+              'languages': ['zh', 'ja', 'ko', 'en']  # Chinese, Japanese, Korean, English
+          })
+```
+
+## Applying OCR Directly
+
+The `page.apply_ocr(...)` and `region.apply_ocr(...)` methods are the primary way to run OCR:
+
+```python
+# Apply OCR to a page and get the OCR elements
+ocr_elements = page.apply_ocr(engine='easyocr')
+print(f"Found {len(ocr_elements)} text elements via OCR")
+
+# Apply OCR to a specific region
+title = page.find('text:contains("Title")')
+content_region = title.below(height=300)
+region_ocr_elements = content_region.apply_ocr(engine='paddle', languages=['en'])
+```
+
+## OCR Engines
+
+Choose the engine best suited for your document and language requirements using the `engine` parameter in `apply_ocr`.
+
+## Finding and Working with OCR Text
+
+After applying OCR, work with the text just like regular text:
+
+```python
+# Find all OCR text elements
+ocr_text = page.find_all('text[source=ocr]')
+
+# Find high-confidence OCR text
+high_conf = page.find_all('text[source=ocr][confidence>=0.8]')
+
+# Extract text only from OCR elements
+ocr_text_content = page.find_all('text[source=ocr]').extract_text()
+
+# Filter OCR text by content
+names = page.find_all('text[source=ocr]:contains("Smith")', case=False)
+```
+
+## Visualizing OCR Results
+
+See OCR results to help debug issues:
+
+```python
+# Apply OCR 
+ocr_elements = page.apply_ocr()
+
+# Highlight all OCR elements
+for element in ocr_elements:
+    # Color based on confidence
+    if element.confidence >= 0.8:
+        color = "green"  # High confidence
+    elif element.confidence >= 0.5:
+        color = "yellow"  # Medium confidence
+    else:
+        color = "red"  # Low confidence
+        
+    element.highlight(color=color, label=f"OCR ({element.confidence:.2f})")
+
+# Get the visualization as an image
+image = page.to_image(labels=True)
+# Just return the image in a Jupyter cell
+image
+
+# Highlight only high-confidence elements
+high_conf = page.find_all('text[source=ocr][confidence>=0.8]')
+high_conf.highlight(color="green", label="High Confidence OCR")
+```
+
+## OCR Debugging
+
+For troubleshooting OCR problems:
+
+```python
+# Create an interactive HTML debug report
+pdf.debug_ocr("ocr_debug.html")
+
+# Specify which pages to include
+pdf.debug_ocr("ocr_debug.html", pages=[0, 1, 2])
+```
+
+The debug report shows:
+- The original image
+- Text found with confidence scores
+- Boxes around each detected word
+- Options to sort and filter results
+
+## OCR Parameter Tuning
+
+### Parameter Recommendation Table
+
+| Issue | Engine | Parameter | Recommended Value | Effect |
+|-------|--------|-----------|-------------------|--------|
+| Missing text | EasyOCR | `text_threshold` | 0.1 - 0.3 (default: 0.7) | Lower values detect more text but may increase false positives |
+| Missing text | PaddleOCR | `det_db_thresh` | 0.1 - 0.3 (default: 0.3) | Lower values detect more text areas |
+| Low quality scan | EasyOCR | `contrast_ths` | 0.05 - 0.1 (default: 0.1) | Lower values help with low contrast documents |
+| Low quality scan | PaddleOCR | `det_limit_side_len` | 1280 - 2560 (default: 960) | Higher values improve detail detection |
+| Accuracy vs. speed | EasyOCR | `decoder` | "wordbeamsearch" (accuracy)<br>"greedy" (speed) | Word beam search is more accurate but slower |
+| Accuracy vs. speed | PaddleOCR | `rec_batch_num` | 1 (accuracy)<br>8+ (speed) | Larger batches process faster but use more memory |
+| Small text | Both | `min_confidence` | 0.3 - 0.4 (default: 0.5) | Lower confidence threshold to capture small/blurry text |
+| Text orientation | PaddleOCR | `use_angle_cls` | `True` | Enable angle classification for rotated text |
+| Asian languages | PaddleOCR | `lang` | "ch", "japan", "korea" | Use PaddleOCR for Asian languages |
+
+## Next Steps
+
+With OCR capabilities, you can explore:
+
+- [Layout Analysis](../layout-analysis/index.ipynb) for automatically detecting document structure
+- [Document QA](../document-qa/index.ipynb) for asking questions about your documents
+- [Visual Debugging](../visual-debugging/index.ipynb) for visualizing OCR results