How pdf-inspector Handles Mixed PDF Reclassification: A Technical Deep Dive

Mixed PDF reclassification upgrades documents to Scanned type when extracted text quality is detected as "garbage," triggering OCR fallback to recover usable content.

The firecrawl/pdf-inspector library employs a sophisticated two‑phase pipeline to handle PDFs that contain both vector text and raster images. Rather than treating these Mixed PDFs as a terminal classification, the system evaluates extraction quality and automatically reclassifies poor‑quality results to Scanned for OCR remediation. This article explains the reclassification mechanism, the garbage‑text detection criteria, and the specific source locations where this logic resides.

The Mixed PDF Detection Problem

Mixed PDFs present a unique challenge: they may contain legitimate selectable text alongside image‑based content, or the text layer may be corrupted, watermarked, or otherwise unusable. The library's approach, as implemented in src/lib.rs, does not commit to a single extraction strategy. Instead, it performs an initial extraction pass and validates the output before finalizing the document type.

Reclassification Logic in the Core Pipeline

The reclassification workflow spans approximately 200 lines in src/lib.rs (lines 4170‑4400). The key phases include initial extraction, quality assessment, and conditional type promotion.

Phase 1: Permissive Extraction for Mixed Types

When the detector identifies a PDF as PdfType::Mixed, the extraction proceeds with failure tolerance. This design allows the pipeline to continue even if partial extraction fails, ensuring the quality check can still execute:

// Extraction errors are intentionally ignored for Mixed PDFs
// so that we can evaluate whatever text was recovered

The extraction result is stored for subsequent analysis, regardless of whether pages produced errors.

Phase 2: Garbage Text Quality Assessment

After extraction, the system evaluates the Markdown output using the is_garbage_text function. This utility, typically defined in src/text_quality.rs, analyzes character distribution to identify low‑quality text—commonly manifested as excessive non‑alphanumeric characters, symbol spam, or encoding artifacts.

The assessment appears at line 4395 in src/lib.rs:

if pdf_type == PdfType::Mixed && markdown.as_ref().is_some_and(|m| is_garbage_text(m)) {
    // upgrade to Scanned and retry with OCR
}

This conditional checks two requirements:

• The current classification remains PdfType::Mixed
• The extracted Markdown exists and fails the garbage test

Phase 3: Type Promotion and OCR Retry

When the garbage condition triggers, the library performs an in‑place type upgrade. The comment at line 4172 documents this intent explicitly:

"The PDF is image‑backed (Mixed/template), upgrade to Scanned — the text"

Following promotion, the pipeline reprocesses the document using OCR‑based extraction, treating the content as a fully scanned document. This second pass bypasses the unreliable vector text layer and generates clean Markdown from image recognition.

Code Implementation Reference

The following Rust example demonstrates how the reclassification behavior manifests through the public API:

use pdf_inspector::{process_pdf_with_options, PdfType};

let opts = ProcessingOptions::default();
let result = process_pdf_with_options("mixed-document.pdf", opts);

// Internal behavior:
// 1. Detector assigns PdfType::Mixed
// 2. Initial text extraction runs permissively
// 3. is_garbage_text() evaluates the Markdown output
// 4. On failure, type becomes PdfType::Scanned
// 5. OCR reprocessing extracts final content

match result.pdf_type {
    PdfType::Scanned => println!("Document was upgraded from Mixed due to garbage text"),
    PdfType::Mixed => println!("Text layer was usable; no reclassification needed"),
    _ => println!("Other classification: {:?}", result.pdf_type),
}

CLI Usage

The pdf2md binary exposes this behavior without requiring manual intervention:

# Process with automatic reclassification

pdf2md corrupted-mixed.pdf --json

# Output indicates final type after quality assessment

# "pdf_type": "Scanned" appears when reclassification occurred

Source File Architecture

The reclassification system spans multiple source files with distinct responsibilities:

• src/lib.rs — Core orchestration logic; contains the Mixed → Scanned decision point at lines 4172‑4395 and the conditional upgrade at line 4395
• src/text_quality.rs — Implements is_garbage_text with heuristic analysis of character entropy and alphanumeric ratio
• src/detector.rs — Initial PDF type classification that assigns the provisional Mixed label
• src/markdown/convert.rs — Generates intermediate Markdown used for the quality gate evaluation
• src/bin/pdf2md.rs — Command‑line interface that invokes the full pipeline including reclassification

Performance and Design Considerations

The reclassification strategy optimizes for accuracy over speed. Mixed PDFs that pass the garbage test avoid the OCR penalty, while degraded documents receive necessary image processing. The permissive error handling during initial extraction ensures that partially corrupted files still reach the quality checkpoint rather than failing prematurely.

The is_garbage_text heuristic balances false positives against missed reclassifications. Documents with heavy symbol usage (mathematical notation, diagram labels) may require tunable thresholds, though the current implementation prioritizes recovery of business and academic documents where garbled text is definitive signal.

Summary

• Mixed PDFs receive provisional classification when both text and image content are detected
• The pipeline extracts text permissively and evaluates quality via is_garbage_text in src/text_quality.rs
• Garbage detection triggers automatic reclassification to PdfType::Scanned at line 4395 of src/lib.rs
• Reclassified documents undergo OCR reprocessing to recover usable Markdown content
• The pdf2md CLI tool exposes this behavior transparently with JSON output indicating final type

Frequently Asked Questions

How does pdf-inspector determine if extracted text is "garbage"?

The is_garbage_text function analyzes the Markdown output's character composition, flagging content with excessive non‑alphanumeric characters or symbol density that indicates encoding corruption or placeholder text. This heuristic operates on the final extracted string before any structural parsing.

Can reclassification be disabled for Mixed PDFs?

The source code analysis does not reveal a public configuration option to disable the quality gate. The reclassification at line 4395 appears unconditional when the garbage condition is met. Forcing Mixed retention would require source modification or post‑processing the detection result.

What happens if OCR also fails after reclassification?

If the Scanned reclassification path encounters OCR failures, the pipeline continues with available results or empty content depending on error handling configuration. The design prioritizes completing extraction over halting on secondary processing errors.

Does reclassification affect processing time significantly?

Yes—OCR‑based extraction is substantially slower than vector text extraction. Documents triggering reclassification incur the full image processing cost. However, this trade‑off prevents silent propagation of unusable text content that would require manual rediscovery.

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