How pdf-inspector Detects Tiled-Scan PDFs: OAR Escalation Heuristics Explained

pdf-inspector detects tiled-scan PDFs by analyzing OCR text-box dimensions and region density, triggering a higher-resolution re-render when median text height drops below ~13 pixels and region count exceeds ~150.

The pdf-inspector crate from Firecrawl provides robust PDF classification for downstream processing pipelines. One of its more sophisticated capabilities is identifying tiled-scan PDFs — documents where pages contain dense grids of tiny text regions, common in advertisements, pricing sheets, and product catalogs. This detection happens within the OAR (OCR Acceleration and Refinement) vision pipeline rather than through naive text-operator analysis.

What Is a Tiled-Scan PDF?

A tiled-scan PDF contains pages composed of many small, discrete text "tiles" rather than continuous text flows. These documents typically result from:

• High-resolution scans of printed materials with fine-grained layouts
• Export from design tools that rasterize text into small image blocks
• Advertisement pages with dense product grids and micro-typography

Standard OCR pipelines often fail on these documents because individual tiles fall below detection thresholds at normal resolutions. The pdf-inspector addresses this through escalation detection — a multi-stage heuristic that recognizes tiled patterns and automatically increases render DPI.

The OAR Escalation Detection Pipeline

Tiled-scan detection resides in src/vision/oar.rs and operates after an initial lightweight OCR pass on sampled pages.

Stage 1: Initial OCR Sampling

The detector samples up to 8 pages (configurable via DetectorConfig) and runs a fast OCR pass at reduced resolution. This produces two critical metrics per page:

• median_height: The median pixel height of detected text boxes
• region_count: Total number of distinct OCR-detected regions

These metrics feed into the escalation decision function.

Stage 2: The should_escalate_detection Heuristic

The core tiled-scan identification logic lives in should_escalate_detection at line 162 of src/vision/oar.rs:

// src/vision/oar.rs – line 162
fn should_escalate_detection(
    median_height: f32,
    region_count: usize,
    downscale: f32,
) -> bool {
    // Tiled-scan heuristics:
    // • Very low median height (≈ 12–13 px) → many tiny tiles
    // • High region count (≈ 150–300 tiles) → dense layout
    // • Down-scale factor must be below threshold to avoid false positives
    median_height < 13.0 && region_count > 150 && downscale < 0.6
}

The function returns true when all three conditions align, signaling that the page likely contains tiled-scan content requiring higher-resolution processing.

Stage 3: Escalated Re-render

When escalation triggers, src/vision/pipeline.rs orchestrates a second OCR pass at increased DPI (typically 2× or 4×). This higher resolution merges adjacent small tiles into coherent text blocks, dramatically improving extraction accuracy on dense layouts.

Threshold Calibration and Validation

The specific thresholds in should_escalate_detection emerged from empirical testing on real-world document corpora. The oar.rs test suite validates this behavior through targeted test cases:

• escalation_fires_for_dense_fine_print_pages (lines 855–860): Confirms detection fires for median heights of 12.0–14.2 pixels with 144–286 regions — the signature pattern of tiled advertisements and pricing tables.

• escalation_skips_ordinary_pages (lines 864–872): Verifies the heuristic does not trigger on standard prose documents or engineering drawings with larger, sparser text regions.

These tests prevent false positives on technical documentation while ensuring dense commercial PDFs receive appropriate OCR treatment.

Integration with PDF Type Classification

The escalation results feed into the broader type detection system in src/detector.rs. A PDF exhibiting tiled-scan characteristics on sampled pages receives classification based on overall content distribution:

Pattern	Classification	OCR Recommendation
Pure tiled-scan (no usable text operators)	PdfType::Scanned	true
Mixed tiled-scan + extractable text	PdfType::Mixed	true
Normal text flows, no escalation	PdfType::Text or PdfType::Hybrid	false

The ocr_reasons_by_page field in the detection result includes "tiled_scan" for pages where escalation triggered, enabling transparent debugging of classification decisions.

Practical Usage Example

use pdf_inspector::{detect_pdf_type, PdfType, DetectorConfig};

fn main() -> Result<(), pdf_inspector::PdfError> {
    // Configure sampling for large documents
    let config = DetectorConfig {
        sample_pages: 8,      // Default: check up to 8 pages
        escalation_dpi: 300,  // Target DPI for tiled-scan re-renders
        ..Default::default()
    };

    let result = detect_pdf_type_with_config("catalog.pdf", config)?;

    match result.pdf_type {
        PdfType::Scanned | PdfType::Mixed if result.ocr_recommended => {
            println!("Tiled-scan detected, OCR required");
            
            for (page, reasons) in &result.ocr_reasons_by_page {
                if reasons.contains(&"tiled_scan".to_string()) {
                    println!("  Page {}: escalated due to dense tile pattern", page);
                }
            }
        }
        _ => println!("Standard text extraction viable"),
    }

    Ok(())
}

Performance Considerations

The tiled-scan detection adds minimal overhead through strategic optimization:

• Early termination: Sampling stops after encountering sufficient classified pages
• Downscale guard: The downscale < 0.6 check prevents re-escalation of already high-resolution renders
• Cached renders: Escalated page renders are cached for downstream processing, avoiding duplicate OCR work

These optimizations ensure tiled-scan handling remains practical for high-throughput document pipelines.

Summary

• Tiled-scan PDFs contain dense grids of small text regions that defeat standard OCR at normal resolutions
• pdf-inspector detects them through the should_escalate_detection function in src/vision/oar.rs, which checks for median text height below 13 pixels and region count above 150
• Escalation triggering causes automatic re-rendering at higher DPI, merging tiny tiles into extractable text blocks
• Integration with src/detector.rs ensures proper PdfType classification and transparent ocr_reasons_by_page reporting

Frequently Asked Questions

How accurate is tiled-scan detection in pdf-inspector?

The heuristic achieves high precision on commercial document corpora. The validation test suite covers edge cases including fine-print legal documents, dense advertisements, and technical drawings. False positives are minimized by requiring all three threshold conditions simultaneously.

Can I adjust the tiled-scan detection sensitivity?

Currently, thresholds are compile-time constants in should_escalate_detection. For custom pipelines, you can fork and modify median_height < 13.0 and region_count > 150 to match your document domain. Runtime configuration support is not exposed in the public API as of the current release.

Does tiled-scan detection work on password-protected PDFs?

No. The detector requires page content access for OCR sampling. Encrypted PDFs must be decrypted before detect_pdf_type invocation, or they will return PdfError::Encrypted without escalation analysis.

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