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

> Learn how to perform detection-only analysis on a PDF using pdf-inspector. Classify PDFs into TextBased, Scanned, ImageBased, or Mixed types without running layout extraction.

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

---

**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`](https://github.com/firecrawl/pdf-inspector/blob/main/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`](https://github.com/firecrawl/pdf-inspector/blob/main/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`](https://github.com/firecrawl/pdf-inspector/blob/main/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`](https://github.com/firecrawl/pdf-inspector/blob/main/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:

```bash
detect-pdf my-document.pdf

```

Machine-readable JSON for pipeline integration:

```bash
detect-pdf my-document.pdf --json

```

Running from source with Cargo:

```bash
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`](https://github.com/firecrawl/pdf-inspector/blob/main/src/bin/detect_pdf.rs) for CLI handling and [`src/detector.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/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`](https://github.com/firecrawl/pdf-inspector/blob/main/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`](https://github.com/firecrawl/pdf-inspector/blob/main/src/bin/detect_pdf.rs) ensures string fields are safely encoded. This structured data enables automated routing decisions in document processing pipelines.