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

> Classify PDF types like TextBased, Scanned, Mixed, or ImageBased using the pdf-inspector CLI. Get human-readable or machine-readable JSON outputs for your documents.

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

---

**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`](https://github.com/firecrawl/pdf-inspector/blob/main/src/bin/detect_pdf.rs), which parses arguments and invokes the detection engine defined in [`src/detector.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/detector.rs).

### Basic Classification

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

```bash
detect-pdf sample.pdf

# → TextBased

```

### JSON Output for Automation

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

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

```bash
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`](https://github.com/firecrawl/pdf-inspector/blob/main/src/lib.rs) and implements the core logic in [`src/detector.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/detector.rs).

Classify a PDF from the filesystem:

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

```rust
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`](https://github.com/firecrawl/pdf-inspector/blob/main/src/detector.rs)**, while the CLI wrapper resides in **[`src/bin/detect_pdf.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/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`](https://github.com/firecrawl/pdf-inspector/blob/main/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`](https://github.com/firecrawl/pdf-inspector/blob/main/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`](https://github.com/firecrawl/pdf-inspector/blob/main/src/detector.rs)**, which implements the `detect_pdf_type` function and related heuristics. The CLI interface in **[`src/bin/detect_pdf.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/bin/detect_pdf.rs)** handles argument parsing and calls into the detector library, while **[`src/lib.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/lib.rs)** exposes the public API for crate consumers.