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

> Master pdf-inspector table detection strategies. Learn to configure rect-based, line-based, and heuristic methods via API or CLI for optimal PDF data extraction.

- Repository: [Firecrawl/pdf-inspector](https://github.com/firecrawl/pdf-inspector)
- Tags: how-to-guide
- Published: 2026-08-10

---

**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`](https://github.com/firecrawl/pdf-inspector/blob/main/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`](https://github.com/firecrawl/pdf-inspector/blob/main/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`](https://github.com/firecrawl/pdf-inspector/blob/main/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`](https://github.com/firecrawl/pdf-inspector/blob/main/src/lib.rs). You can enable/disable strategies and reorder their priority.

### Disable Specific Strategies

```rust
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

```rust
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:

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

```

Prioritize heuristics for scanned documents with no visible borders:

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

```

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

```bash
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`](https://github.com/firecrawl/pdf-inspector/blob/main/src/lib.rs)** — Public API entry points (`process_pdf_with_options`, `TableDetectionOptions` struct)
- **[`src/tables/detect_rects.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/tables/detect_rects.rs)** — Rectangle clustering and validation via union-find
- **[`src/tables/detect_lines.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/tables/detect_lines.rs)** — Line grid construction and intersection analysis
- **[`src/tables/detect_heuristic.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/tables/detect_heuristic.rs)** — Font and spacing heuristics for implicit tables
- **[`src/tables/format.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/tables/format.rs)** — Converts detected cell matrices to Markdown, handles spanning cells
- **[`src/markdown/convert.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/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`](https://github.com/firecrawl/pdf-inspector/blob/main/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`](https://github.com/firecrawl/pdf-inspector/blob/main/detect_rects.rs), [`detect_lines.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/detect_lines.rs), and [`detect_heuristic.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/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`](https://github.com/firecrawl/pdf-inspector/blob/main/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`](https://github.com/firecrawl/pdf-inspector/blob/main/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`](https://github.com/firecrawl/pdf-inspector/blob/main/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.