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

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 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 (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:

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:

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 — Defines PdfType, DetectionConfig, and the detect_from_document algorithm
• src/lib.rs — Exports the public API: detect_pdf_type, detect_pdf_type_with_config, and PdfTypeResult
• 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
• 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.

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