How to Configure Table Detection Strategies in pdf-inspector (Rect-Based vs. Line-Based vs. Heuristic)

pdf-inspector extracts tables from PDFs using a three-stage detection pipeline that runs in fixed priority order, and you can control which strategies are active and their execution priority through the Rust API or CLI flags.

The open-source pdf-inspector library (maintained by Firecrawl) implements a deterministic fallback strategy for table detection. When you process a PDF, it attempts multiple detection methods in sequence until tables are found. Understanding how to configure these strategies lets you optimize accuracy for different PDF types—from tightly formatted financial reports to loosely structured scanned documents.

---

The Three Table Detection Strategies Explained

pdf-inspector implements three distinct detection strategies in src/tables/. Each strategy analyzes different geometric or typographic cues:

Rect-Based Detection

Rect-based detection is the fastest strategy. It clusters rectangular drawing objects—explicitly drawn boxes that form table borders—using a union-find algorithm.

In src/tables/detect_rects.rs, the detect_rects function:

1. Collects all rectangle primitives from the PDF content stream
2. Clusters overlapping or adjacent rectangles
3. Validates that clusters form valid row/column structures

This strategy excels for PDFs with explicit table borders, such as exported Excel spreadsheets or CAD-generated reports.

Line-Based Detection

When rectangle primitives are absent, pdf-inspector falls back to line-based detection in src/tables/detect_lines.rs. The detect_lines function:

1. Extracts horizontal and vertical line segments
2. Builds a grid by merging intersecting lines
3. Derives cell boundaries from line intersections

This approach handles PDFs that use lines without surrounding boxes—common in academic papers and government forms.

Heuristic Detection

The final fallback is heuristic detection implemented in src/tables/detect_heuristic.rs. The detect_heuristic function analyzes:

• Font size variations to identify header rows
• Spacing patterns to infer column boundaries
• Text alignment to detect implicit table structures

This strategy catches text-only tables or loosely formatted data where geometric cues are missing—typical of scanned documents or HTML-to-PDF conversions.

---

Configuring Strategies via the Rust API

The public API exposes fine-grained control through TableDetectionOptions in src/lib.rs. You can enable/disable strategies and reorder their priority.

Disable Specific Strategies

use pdf_inspector::{
    process_pdf_with_options,
    TableDetectionOptions,
};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Disable line-based and heuristic detection
    let mut opts = TableDetectionOptions::default();
    opts.enable_rect_based = true;
    opts.enable_line_based = false;
    opts.enable_heuristic = false;

    let markdown = process_pdf_with_options("clean_bordered_tables.pdf", opts)?;
    println!("{}", markdown);
    Ok(())
}

Reorder Detection Priority

use pdf_inspector::{
    process_pdf_with_options,
    TableDetectionOptions,
    TableStrategy,
};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut opts = TableDetectionOptions::default();
    
    // Prioritize heuristic detection for scanned PDFs
    opts.priority = vec![
        TableStrategy::Heuristic,
        TableStrategy::RectBased,
        TableStrategy::LineBased,
    ];

    let markdown = process_pdf_with_options("scanned_document.pdf", opts)?;
    Ok(())
}

The process_pdf_with_options function passes these settings to the detection pipeline, which iterates through opts.priority and skips any strategy where enable_* is false.

---

Configuring Strategies via CLI

The pdf2md binary exposes the same options as command-line flags:

Flag	Purpose
--detect-rects	Enable rectangle-based detection (default: on)
--detect-lines	Enable line-based detection (default: on)
--detect-heuristic	Enable heuristic detection (default: on)
--no-detect-rects	Disable rectangle-based detection
--no-detect-lines	Disable line-based detection
--no-detect-heuristic	Disable heuristic detection

CLI Examples

Run only rect-based detection for a well-structured report:

pdf2md --detect-rects --no-detect-lines --no-detect-heuristic annual_report.pdf

Prioritize heuristics for scanned documents with no visible borders:

pdf2md --detect-heuristic --detect-rects --detect-lines scanned_invoice.pdf

Force line-based detection for line-drawn tables without boxes:

pdf2md --detect-lines --no-detect-rects --no-detect-heuristic academic_paper.pdf

---

Source Code Architecture

The table detection pipeline is implemented across these core files:

• src/lib.rs — Public API entry points (process_pdf_with_options, TableDetectionOptions struct)
• src/tables/detect_rects.rs — Rectangle clustering and validation via union-find
• src/tables/detect_lines.rs — Line grid construction and intersection analysis
• src/tables/detect_heuristic.rs — Font and spacing heuristics for implicit tables
• src/tables/format.rs — Converts detected cell matrices to Markdown, handles spanning cells
• src/markdown/convert.rs — Integrates table output into final document stream

According to the firecrawl/pdf-inspector source code, the detection order is hard-coded in the default priority vector but fully overrideable through TableDetectionOptions.priority.

---

Performance and Accuracy Considerations

Strategy	Speed	Accuracy	Best For
Rect-based	Fastest	Highest (when borders exist)	Explicitly bordered tables
Line-based	Fast	High	Line-grid tables without boxes
Heuristic	Slowest	Variable	Borderless or scanned tables

Performance tip: Disable unused strategies to reduce processing time. For a batch of uniformly formatted PDFs, hardcoding the correct strategy eliminates unnecessary fallback attempts.

Accuracy tip: For mixed document collections, maintain the default three-stage pipeline. The overhead is minimal compared to PDF parsing, and fallback coverage prevents missed tables.

---

Summary

• pdf-inspector uses three strategies in fixed priority: rect-based (fastest, geometric), line-based (grid analysis), and heuristic (typographic patterns).
• Control strategies via TableDetectionOptions in src/lib.rs: set boolean flags to enable/disable, and reorder the priority vector to change execution order.
• CLI flags mirror the API: use --detect-* and --no-detect-* switches with pdf2md.
• Implementation files are modular: detect_rects.rs, detect_lines.rs, and detect_heuristic.rs each contain isolated logic you can study or extend.

---

Frequently Asked Questions

How do I completely disable heuristic detection for faster processing?

Pass --no-detect-heuristic to the CLI, or set opts.enable_heuristic = false in Rust. This is safe when you know your PDFs contain explicit borders or lines.

Can I add a custom detection strategy to the pipeline?

The current architecture in src/tables/mod.rs uses a fixed enum TableStrategy. You would need to fork the repository, add your variant to the enum, and implement the detection trait in a new module following the pattern in detect_rects.rs.

Why does pdf-inspector miss tables in my scanned PDF?

Scanned documents often lack geometric primitives. Try reordering priority to TableStrategy::Heuristic first, or use --detect-heuristic as the first CLI flag. The heuristic analyzer in detect_heuristic.rs specifically targets spacing patterns common in OCR output.

What's the difference between line-based and rect-based detection?

Rect-based detection requires closed rectangular paths (explicit box borders), while line-based detection works with intersecting line segments that may not form complete rectangles. Line-based is more tolerant of incomplete borders but slightly slower due to grid construction logic.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}