Table parser

[AmineDiro]

Summary

Add end-to-end table structure recognition to Ferrules. Tables detected by the layout model are now parsed into structured TableBlock objects with rows, cells, column/row spans, and header detection — ready for HTML rendering.

Architecture

The table parser uses a three-algorithm fallback strategy, selecting the best approach based on the table characteristics:

1. Lattice — Path-based parsing for tables with visible borders. Extracts horizontal/vertical lines from PDF path objects and uses their intersections to derive the grid structure. Handles column spans by detecting missing vertical boundaries.

2. Vision — ML-based parsing using Microsoft Table Transformer (DETR) for borderless or complex tables. The model runs as a FP16 ONNX model with support for CoreML, CUDA, TensorRT, and CPU execution providers.

3. Stream — Text-alignment fallback for tables where neither paths nor the vision model produce usable results. Clusters text lines by vertical proximity and infers column boundaries from horizontal gaps.

The parser automatically evaluates Lattice results and falls back to Vision when the table looks "suspicious" (too few cells, too few rows, or insufficient area coverage).

Key Changes

New Modules

• ferrules-core/src/parse/table.rs (~1000 lines) — Core table parsing module containing:
  • TableParser — Orchestrates the three parsing algorithms
  • TableTransformer — ONNX inference wrapper with image preprocessing (ImageNet normalization, dynamic scaling) and DETR postprocessing (softmax, cx/cy/w/h → bbox conversion, confidence thresholding)
  • ParseTableQueue / ParseTableRequest — Async message-passing interface matching the existing layout queue pattern
  • Concurrency-limited workers via tokio::sync::Semaphore
• python/export_table_transformer.py — Script to export the HuggingFace model to ONNX with FP16 quantization

Data Model

• New types: TableBlock, TableRow, TableCell, TableAlgorithm
• BlockType::Table now wraps a TableBlock instead of being a unit variant
• ElementType::Table carries an Option<TableBlock> for deferred population
• New PDFPath and Segment entities for representing extracted vector paths
• CharSpan and Line are now Clone to support shared ownership across parsing stages

Integration

• Page parsing (page.rs): Table elements are dispatched to the table queue concurrently via JoinSet, results are joined back before block merging
• Document parsing (document.rs): FerrulesParser now owns a ParseTableQueue alongside the existing layout and native queues
• Native parsing (native.rs): Extracts PDF path objects (lines, rects) before page.flatten() to avoid segfaults from stale pdfium pointers
• HTML rendering (html.rs): Full <table> rendering with colspan/rowspan attributes, recursive cell content rendering, and header row support (<th>)
• Debug drawing (draw.rs): Table structure visualization (rows, cells, text) and PDF path overlay for debugging
• Block merging (blocks.rs, merge.rs): Table blocks can now be merged; table images are saved as cropped PNGs

CI / Build

• Table Transformer FP16 ONNX model tracked via Git LFS (58 MB)
• .gitattributes configured for *.onnx LFS tracking
• .gitignore updated to allow the specific model file through
• Added half crate dependency for FP16 tensor support
• Enabled half feature flag on ort

Other

• CLI error handling for TableTransformerModelError
• OCR test guarded behind file existence check
• Tracing subscriber initialization in CLI debug mode

Testing

• Manual validation on bordered and borderless table PDFs
• Debug image output confirms correct cell boundaries and text mapping
• Draw module includes unit tests for table structure rendering'

To get started with GitHub CLI, please run: gh auth login
Alternatively, populate the GH_TOKEN environment variable with a GitHub API authentication token.