# PDF Classification Types in pdf-inspector: TextBased, Scanned, ImageBased, and Mixed Explained

> Discover PDF classification types in pdf-inspector: TextBased, Scanned, ImageBased, and Mixed. Understand how pdf-inspector analyzes your PDFs for efficient data extraction.

- Repository: [Firecrawl/pdf-inspector](https://github.com/firecrawl/pdf-inspector)
- Tags: deep-dive
- Published: 2026-09-01

---

**The pdf-inspector library classifies PDFs into four distinct types—TextBased, Scanned, ImageBased, and Mixed—based on extractable text presence, image content, and page-level analysis.**

The firecrawl/pdf-inspector Rust library provides robust PDF type detection to drive intelligent extraction pipelines. Understanding these **PDF classification types** helps developers determine when OCR is necessary and optimize document processing workflows.

## The Four PDF Classification Types

The classification system centers on the `PdfType` enum defined in [`src/detector.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/detector.rs) at lines 14-23. Each type triggers different processing strategies downstream.

### TextBased

**TextBased** PDFs contain sufficient extractable text with minimal image-only pages. The detector identifies these when PDF text operators `Tj` or `TJ` appear across enough pages.

This classification applies when the ratio of pages containing text exceeds the `text_page_ratio_threshold` (default 0.6). No OCR is recommended—text extracts directly via standard PDF parsing.

### Scanned

**Scanned** PDFs lack extractable text entirely and consist purely of images, such as digitized paper documents. The detector finds no text operators but confirms image or vector-text presence.

OCR is **strongly recommended** for these documents. The entire page set typically requires optical character recognition to recover usable text.

### ImageBased

**ImageBased** PDFs contain mostly images with minimal text, but aren't pure scans. These often include presentation slides, brochures, or design files with embedded graphics.

While some text operators may appear, the overall text ratio remains low. OCR is recommended to capture the visual text content missed by standard extraction.

### Mixed

**Mixed** PDFs combine extractable text pages with image-heavy or template-image sections. Common examples include reports with chart pages, scanned covers on digitized books, or invoices with embedded logos.

The detector flags individual pages needing OCR via `pages_needing_ocr` in the result. This granular approach optimizes processing by running OCR only where required.

## How Detection Works

The core detection logic resides in `detect_from_document` in [`src/detector.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/detector.rs) (lines 81-136). This function returns a `PdfTypeResult` containing:

- `pdf_type`: The determined `PdfType` classification
- Confidence score for the determination
- Per-page OCR recommendations

The detection algorithm analyzes PDF page streams for:
- Text operator counts (`Tj`, `TJ`)
- Image XObject presence
- Vector text vs. raster content ratios

Configuration parameters in `DetectionConfig` tune sensitivity:

| Parameter | Default | Purpose |
|-----------|---------|---------|
| `text_page_ratio_threshold` | 0.6 | Minimum ratio of text-containing pages for TextBased classification |
| `min_text_ops_per_page` | Varies | Minimum text operators to consider a page "text-based" |
| `strategy` | `ScanStrategy::Fast` | Sampling approach (Fast, Full, or Adaptive) |

## Using the Detection API

### Basic PDF Type Detection

Detect a PDF from a file path with the simple API:

```rust
use pdf_inspector::detect_pdf_type;

fn main() -> Result<(), pdf_inspector::PdfError> {
    let result = detect_pdf_type("example.pdf")?;
    println!("PDF type: {:?}", result.pdf_type);
    println!("Pages needing OCR: {:?}", result.pages_needing_ocr);
    Ok(())
}

```

This returns the classification and automatically identifies which pages require OCR processing.

### Custom Detection Configuration

For fine-grained control, use `detect_pdf_type_with_config` with a custom `DetectionConfig`:

```rust
use pdf_inspector::{detect_pdf_type_with_config, DetectionConfig, ScanStrategy};

fn main() -> Result<(), pdf_inspector::PdfError> {
    let config = DetectionConfig {
        strategy: ScanStrategy::Full, // scan every page
        min_text_ops_per_page: 5,
        text_page_ratio_threshold: 0.7,
        ..Default::default()
    };
    let result = detect_pdf_type_with_config("complex.pdf", config)?;
    println!("Detected type: {:?}", result.pdf_type);
    Ok(())
}

```

The `ScanStrategy::Full` option ensures complete page analysis rather than sampling, improving accuracy for heterogeneous documents at the cost of processing time.

## Source Code Architecture

According to the firecrawl/pdf-inspector source code, the classification system spans three key modules:

- **[`src/detector.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/detector.rs)** — Defines `PdfType`, `DetectionConfig`, and the `detect_from_document` algorithm
- **[`src/lib.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/lib.rs)** — Exports the public API: `detect_pdf_type`, `detect_pdf_type_with_config`, and `PdfTypeResult`
- **[`src/types.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/types.rs)** — Houses supporting data structures including result types and configuration structs

This architecture separates detection logic from the public interface, enabling both library consumption and embedded use in larger extraction pipelines.

## Summary

- **pdf-inspector provides four PDF classification types**: TextBased, Scanned, ImageBased, and Mixed
- Classification depends on text operator presence, image content, and configurable ratio thresholds
- **TextBased PDFs** extract directly; **Scanned**, **ImageBased**, and **Mixed** types typically need OCR
- The `PdfType` enum and detection logic live in [`src/detector.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/detector.rs)
- Public API functions `detect_pdf_type` and `detect_pdf_type_with_config` expose classification capabilities with optional configuration

## Frequently Asked Questions

### How does pdf-inspector distinguish between Scanned and ImageBased PDFs?

Both types lack substantial extractable text, but **Scanned** indicates zero text operators across all pages—suggesting a pure raster document. **ImageBased** allows for minimal text presence or vector text that doesn't meet extraction thresholds. The distinction helps callers prioritize OCR intensity: Scanned documents typically need full-page OCR, while ImageBased may have selectable text elements worth preserving.

### Can I customize the classification thresholds?

Yes. Pass a custom `DetectionConfig` to `detect_pdf_type_with_config`. Key tunables include `text_page_ratio_threshold` (default 0.6) for TextBased eligibility and `min_text_ops_per_page` for per-page text detection sensitivity. Adjusting these helps handle domain-specific documents like dense academic papers or sparse presentation decks.

### What information does PdfTypeResult provide beyond the classification type?

`PdfTypeResult` includes a confidence score indicating detection certainty and `pages_needing_oc: Vec<PageOcrRecommendation>` with per-page guidance. Each recommendation specifies which pages require OCR and why, enabling selective processing that skips already-readable pages in Mixed documents.

### When should I use ScanStrategy::Full versus the default Fast mode?

Use **Fast** for batch processing of homogeneous documents where sampling maintains accuracy. Choose **Full** when documents vary significantly page-to-page, when classification confidence matters critically, or when processing archival material with unpredictable content distribution. Full mode examines every page rather than statistical sampling, trading performance for precision.