How to Classify a PDF Type Using the pdf-inspector CLI

The detect-pdf command in firecrawl/pdf-inspector analyzes document structure to classify PDFs as TextBased, Scanned, Mixed, or ImageBased, supporting both human-readable and machine-readable JSON outputs.

The pdf-inspector repository provides a Rust-based toolkit for programmatic PDF analysis. Its primary CLI binary inspects files using heuristics implemented in the core detector library. This guide demonstrates how to use the command-line interface to classify PDF types accurately.

PDF Type Categories

The classification system distinguishes four distinct document types based on content composition:

• TextBased – PDFs containing extractable Unicode text with minimal or no embedded images.
• Scanned – PDFs consisting primarily of raster images, typically representing scanned paper documents.
• Mixed – PDFs containing both extractable text layers and image-based pages.
• ImageBased – PDFs that function essentially as single large images, such as photos of documents.

Using the detect-pdf CLI Command

The CLI entry point resides in src/bin/detect_pdf.rs, which parses arguments and invokes the detection engine defined in src/detector.rs.

Basic Classification

Run the binary with a file path to receive a concise classification:

detect-pdf sample.pdf

# → TextBased

JSON Output for Automation

Add the --json flag to emit structured data suitable for scripts and pipelines:

detect-pdf --json sample.pdf

# → {"pdf_type":"Scanned","pages_sampled":10,"image_count":12,...}

Detailed Analysis Mode

Include the --analyze flag with --json to expose per-page diagnostics and intermediate heuristics:

detect-pdf --analyze --json sample.pdf

# → {"pdf_type":"Mixed","pages_sampled":10,"image_count":4,

#     "page_analysis":[{"page":1,"type":"TextBased"},...]}

Programmatic PDF Classification

The underlying library exposes detection functions directly for Rust applications. The public API is defined in src/lib.rs and implements the core logic in src/detector.rs.

Classify a PDF from the filesystem:

use pdf_inspector::detector::detect_pdf_type;

let result = detect_pdf_type("sample.pdf")?;
println!("Detected: {}", result.pdf_type);

Process PDFs already loaded in memory using the detect_pdf_type_mem function:

let bytes = std::fs::read("sample.pdf")?;
let result = pdf_inspector::detect_pdf_type_mem(&bytes)?;

How Detection Works Under the Hood

The detect_pdf_type function implements a multi-stage heuristic analysis:

1. Page sampling – Analyzes a representative subset of pages rather than the entire document for performance.
2. Content evaluation – Distinguishes between vector text, embedded fonts, and raster images.
3. OCR-fallback detection – Identifies image-only pages that lack text layers.
4. Background-image evaluation – Detects documents where a single image constitutes the entire page content.

These checks determine whether a document qualifies as TextBased, requires OCR (Scanned), mixes both formats (Mixed), or consists entirely of a bitmap (ImageBased).

Summary

• The detect-pdf binary in firecrawl/pdf-inspector provides the primary CLI interface for PDF classification.
• Four classification types exist: TextBased, Scanned, Mixed, and ImageBased.
• Use --json for machine-readable output and --analyze for detailed per-page diagnostics.
• The detection logic lives in src/detector.rs, while the CLI wrapper resides in src/bin/detect_pdf.rs.
• Rust applications can import detect_pdf_type or detect_pdf_type_mem from the library crate for programmatic access.

Frequently Asked Questions

What PDF types can pdf-inspector detect?

pdf-inspector classifies documents into four categories: TextBased for text-heavy documents, Scanned for image-based documents requiring OCR, Mixed for documents combining both text and images, and ImageBased for single-image documents. These classifications help determine whether text extraction or image processing workflows are appropriate.

How does pdf-inspector distinguish between scanned and text-based PDFs?

The tool uses heuristics defined in src/detector.rs to sample pages and analyze content structure. It checks for the presence of embedded fonts, Unicode text streams, and bitmap coverage ratios. Documents dominated by raster images without text layers classify as Scanned, while those with accessible text content classify as TextBased.

Can I use pdf-inspector programmatically without the CLI?

Yes. The Rust library exposes detect_pdf_type for filesystem paths and detect_pdf_type_mem for in-memory byte vectors, both defined in the public API via src/lib.rs. These functions return structured results identical to the CLI’s JSON output, allowing integration into larger Rust applications or services.

Where is the detection logic implemented in the source code?

The core classification algorithms reside in src/detector.rs, which implements the detect_pdf_type function and related heuristics. The CLI interface in src/bin/detect_pdf.rs handles argument parsing and calls into the detector library, while src/lib.rs exposes the public API for crate consumers.

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