How to Perform Detection-Only Analysis on a PDF with pdf-inspector

Use the detect-pdf CLI binary without the --analyze flag to classify PDFs into TextBased, Scanned, ImageBased, or Mixed types without running layout extraction.

The firecrawl/pdf-inspector repository provides a lightweight detection-only analysis mode that rapidly categorizes PDF documents before resource-intensive extraction. This workflow executes the classifier heuristics in isolation, bypassing the layout extraction modules entirely to deliver sub-second results even on large files. By invoking the dedicated detect-pdf binary, you can determine document type, OCR requirements, and text density without loading the full extraction pipeline.

How Detection-Only Mode Works

The detection-only workflow is implemented in the standalone detect-pdf binary. When invoked without the --analyze flag, the system executes a four-stage pipeline that samples pages and applies heuristics without performing table or column detection.

CLI Argument Parsing and Dispatch

The entry point resides in src/bin/detect_pdf.rs, which parses command-line arguments and determines the execution path. When the --analyze flag is absent, the binary routes to run_detect_only (lines 11–12). This function prepares the file handle and selects the output format based on the presence of --json.

Core Detection Heuristics

The run_detect_only function invokes detect_pdf_type from src/detector.rs (lines 214–215), which loads and validates the PDF before forwarding it to detect_from_document. This internal function applies heuristics that measure text-operation density, sample page ratios, and OCR hints to classify the document.

The default DetectionConfig::default configuration samples eight pages using strategy: ScanStrategy::Sample(8) (lines 83–86) and requires a minimum of three text operations per page (min_text_ops_per_page: 3 at line 86). The classifier uses a text-page-ratio threshold of 0.6 (line 87) to distinguish between TextBased and other types. Because this mode does not load the extractor modules in src/extractor/*, it maintains a minimal memory footprint and executes significantly faster than full analysis.

Result Formatting and Output

The detect_pdf_type function returns a PdfTypeResult struct containing:

• pdf_type: The classified category (TextBased, Scanned, ImageBased, or Mixed)
• page_count: Total number of pages
• pages_sampled: Number of pages analyzed
• pages_with_text: Count of pages containing extractable text
• confidence: Classification confidence score
• pages_needing_ocr: Pages requiring optical character recognition
• ocr_reasons_by_page: Detailed OCR failure reasons per page

In src/bin/detect_pdf.rs, the run_detect_only function formats these fields as human-readable text by default, or as JSON when --json is specified. The JSON encoder uses the json_escape helper (lines 45–62) to safely embed strings. After printing the result, the binary terminates without invoking any layout analysis.

Configuring Detection Parameters

While the default configuration suits most documents, you can customize detection behavior programmatically using detect_pdf_type_with_config. This function accepts a bespoke DetectionConfig to adjust sampling strategy, text operation thresholds, or confidence ratios without modifying the source code.

For example, increasing the sample size or lowering the text-operation threshold may improve accuracy on documents with sparse text layouts. The configuration struct is publicly exported from src/lib.rs alongside detect_pdf_type and PdfTypeResult, allowing direct integration into Rust applications.

Practical Usage Examples

Run detection-only analysis from the command line using the prebuilt binary or Cargo. These commands execute strictly the classification logic without table or column extraction.

Basic human-readable output:

detect-pdf my-document.pdf

Machine-readable JSON for pipeline integration:

detect-pdf my-document.pdf --json

Running from source with Cargo:

cargo run --bin detect-pdf -- my-document.pdf
cargo run --bin detect-pdf -- my-document.pdf --json

Note that adding the --analyze flag switches the binary to full analysis mode, which includes layout detection. Omitting this flag maintains the lightweight detection-only behavior.

Summary

• Use the detect-pdf binary without --analyze to perform detection-only analysis that classifies PDFs into TextBased, Scanned, ImageBased, or Mixed categories.
• The workflow spans src/bin/detect_pdf.rs for CLI handling and src/detector.rs for classification heuristics, bypassing src/extractor/* modules entirely for speed.
• Default configuration samples eight pages and requires three text operations per page with a 0.6 text-page ratio threshold, tunable via detect_pdf_type_with_config.
• Output formats include human-readable text or JSON via the --json flag, with the PdfTypeResult struct providing detailed metadata including OCR requirements.

Frequently Asked Questions

What is the difference between detection-only mode and full analysis in pdf-inspector?

Detection-only mode runs the detect_pdf_type function to classify the document type without loading layout extraction modules. Full analysis mode, triggered by the --analyze flag, executes additional pipelines to identify tables, columns, and reading order. Detection-only executes significantly faster because it skips the heavy processing in src/extractor/* and does not perform structural layout analysis.

How does pdf-inspector determine if a PDF is scanned or text-based?

The classification relies on heuristics in detect_from_document that calculate text-operation density across sampled pages. The default DetectionConfig requires at least three text operations per page and a text-page ratio of 0.6 to qualify as TextBased. Documents failing these thresholds are flagged as Scanned, ImageBased, or Mixed based on OCR hints and image content ratios detected during the sampling phase.

Can I adjust the number of pages sampled during detection-only analysis?

Yes. While the CLI uses the default configuration sampling eight pages, you can programmatically invoke detect_pdf_type_with_config and provide a custom DetectionConfig with a different ScanStrategy::Sample(n) value. This allows you to sample more pages for higher confidence or fewer pages for faster execution when using the library API directly from src/lib.rs.

What fields are included in the JSON output from the detect-pdf binary?

The JSON output serializes the PdfTypeResult struct, including pdf_type, page_count, pages_sampled, pages_with_text, confidence, pages_needing_ocr, and ocr_reasons_by_page. The json_escape helper in src/bin/detect_pdf.rs ensures string fields are safely encoded. This structured data enables automated routing decisions in document processing pipelines.

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