firecrawl/pdf-inspector

pip install maturin
maturin develop --release

import pdf_inspector

result = pdf_inspector.process_pdf("document.pdf")
print(result.pdf_type)   # "text_based", "scanned", "image_based", "mixed"
print(result.markdown)   # Markdown string or None

npm install @firecrawl/pdf-inspector

import { readFileSync } from 'fs';
import { processPdf, classifyPdf } from '@firecrawl/pdf-inspector';

const result = processPdf(readFileSync('document.pdf'));
console.log(result.pdfType);   // "TextBased", "Scanned", "ImageBased", "Mixed"
console.log(result.markdown);  // Markdown string or null

npm install @firecrawl/pdf-inspector-wasm

import init, { processPdf } from '@firecrawl/pdf-inspector-wasm';

await init();
const response = await fetch('/document.pdf');
const pdf = new Uint8Array(await response.arrayBuffer());
const result = processPdf(pdf);

console.log(result.pdfType);
console.log(result.markdown);

cargo add pdf-inspector

[dependencies]
pdf-inspector = "1"

use pdf_inspector::process_pdf;

let result = process_pdf("document.pdf")?;
println!("Type: {:?}", result.pdf_type);
if let Some(markdown) = &result.markdown {
    println!("{}", markdown);
}

# Install the CLI tools
cargo install pdf-inspector

# Convert PDF to Markdown
pdf2md document.pdf

# JSON output (for piping)
pdf2md document.pdf --json

# Positioned TextItem JSON, including is_underline metadata
pdf2md document.pdf --items-json

# Raw markdown only (no headers)
pdf2md document.pdf --raw

# Token-efficient output (collapses long dot leaders and similar source padding)
pdf2md document.pdf --compact

# Insert page break markers (<!-- Page N -->)
pdf2md document.pdf --pages

# Process only specific pages
pdf2md document.pdf --select-pages 1,3,5-10

# Detection only (no extraction)
detect-pdf document.pdf
detect-pdf document.pdf --json

# Detection + layout analysis (tables, columns)
detect-pdf document.pdf --analyze --json

PDF bytes
  │
  ├─► detector         → PdfType (TextBased / Scanned / ImageBased / Mixed)
  │
  └─► extractor
        ├─ fonts        → font widths, encodings
        ├─ content_stream → walk PDF operators → TextItems + PdfRects
        ├─ xobjects     → Form XObject text, image placeholders
        ├─ links        → hyperlinks, AcroForm fields
        └─ layout       → column detection → line grouping → reading order
              │
              ├─► tables
              │     ├─ detect_rects      → rectangle-based tables (union-find)
              │     ├─ detect_heuristic  → alignment-based tables
              │     ├─ grid              → column/row assignment → cells
              │     └─ format            → cells → Markdown table
              │
              └─► markdown
                    ├─ analysis     → font stats, heading tiers
                    ├─ preprocess   → merge headings, drop caps
                    ├─ convert      → line loop + table/image insertion
                    ├─ classify     → captions, lists, code
                    └─ postprocess  → cleanup → final Markdown

src/
  lib.rs                — Public API, PdfOptions builder, convenience functions
  python.rs             — PyO3 Python bindings
  types.rs              — Shared types: TextItem, TextLine, PdfRect, ItemType
  text_utils.rs         — Character/text helpers (CJK, RTL, ligatures, bold/italic)
  process_mode.rs       — ProcessMode enum (DetectOnly, Analyze, Full)
  detector.rs           — Fast PDF type detection without full document load
  glyph_names.rs        — Adobe Glyph List → Unicode mapping
  tounicode.rs          — ToUnicode CMap parsing for CID-encoded text
  extractor/            — Text extraction pipeline
  tables/               — Table detection and formatting
  markdown/             — Markdown conversion and structure detection
  bin/                  — CLI tools (pdf2md, detect_pdf)
napi/                   — Node.js/Bun bindings (napi-rs)
wasm/                   — Browser bindings (wasm-bindgen)

## การทำงานของการจำแนกประเภท

1.  แยกวิเคราะห์ตาราง xref และโครงสร้างหน้า (ไม่มีการโหลดอ็อบเจกต์ทั้งหมด)
2.  เลือกหน้าตาม `ScanStrategy` (ค่าเริ่มต้น: ทุกหน้าพร้อมการออกก่อนกำหนด)
3.  มองหา `Tj`/`TJ` (ตัวดำเนินการข้อความ) และ `Do` (ตัวดำเนินการรูปภาพ) ในสตรีมเนื้อหา
4.  จำแนกประเภทตามการมีอยู่ของตัวดำเนินการข้อความในหน้าตัวอย่าง

สิ่งนี้สามารถตรวจจับ PDF ที่มีมากกว่า 300 หน้าได้ในหน่วยมิลลิวินาที ผลลัพธ์ประกอบด้วย `pages_needing_ocr` — รายการหมายเลขหน้าเฉพาะที่ไม่มีข้อความ ทำให้สามารถกำหนดเส้นทาง OCR แบบต่อหน้าได้ แทนที่จะเป็นแบบทั้งหมดหรือไม่มีเลย

### กลยุทธ์การสแกน

| กลยุทธ์ | พฤติกรรม | เหมาะที่สุดสำหรับ |
|---|---|---|
| `EarlyExit` (ค่าเริ่มต้น) | สแกนทุกหน้า หยุดเมื่อเจอหน้าแรกที่ไม่ใช่ข้อความ | ไปป์ไลน์ที่กำหนดเส้นทาง PDF ที่เป็นข้อความไปยังการแยกข้อมูลที่รวดเร็ว |
| `Full` | สแกนทุกหน้า ไม่มีการออกก่อนกำหนด | การจำแนกประเภทแบบผสมเทียบกับแบบสแกนที่แม่นยำ |
| `Sample(n)` | สุ่มตัวอย่าง `n` หน้าที่กระจายอย่างสม่ำเสมอ (หน้าแรก, หน้าสุดท้าย, กลาง) | PDF ขนาดใหญ่มากที่ความเร็วสำคัญกว่าความแม่นยำ |
| `Pages(vec)` | สแกนเฉพาะหมายเลขหน้าแบบ 1-indexed ที่ระบุเท่านั้น | เมื่อผู้เรียกทราบว่าต้องตรวจสอบหน้าใดบ้าง |

## เอาต์พุต Markdown

ตัวแปลงจัดการ:

| องค์ประกอบ | ตรวจจับได้อย่างไร |
|---|---|
| หัวข้อ (H1-H4) | ระดับขนาดตัวอักษรสัมพันธ์กับข้อความเนื้อหา โดยมีการจัดกลุ่ม 0.5pt |
| ตัวหนา/ตัวเอียง | รูปแบบชื่อฟอนต์ (Bold, Italic, Oblique) |
| รายการสัญลักษณ์แสดงหัวข้อย่อย | คำนำหน้า `•`, `-`, `*`, `○`, `●`, `◦` |
| รายการลำดับเลข | รูปแบบ `1.`, `1)`, `(1)` |
| รายการตัวอักษร | รูปแบบ `a.`, `a)`, `(a)` |
| บล็อกโค้ด | ฟอนต์ Monospace (Courier, Consolas, Monaco, Menlo, Fira Code, JetBrains Mono) และการตรวจจับคีย์เวิร์ด |
| ตาราง | การตรวจจับตามสี่เหลี่ยมจาก PDF drawing ops + การตรวจจับแบบฮิวริสติกจากการจัดแนวข้อความ |
| ตารางการเงิน | การแยกโทเค็นสำหรับค่าตัวเลขที่รวมกัน |
| คำบรรยายภาพ | การตรวจจับคำนำหน้า "Figure", "Table", "Source:" |
| ตัวห้อย/ตัวยก | ขนาดตัวอักษรและ Y-offset สัมพันธ์กับเส้นฐาน |
| URL | แปลงเป็นลิงก์ Markdown |
| การแบ่งคำ | รวมคำที่ถูกแบ่งข้ามบรรทัดเข้าด้วยกัน |
| หมายเลขหน้า | กรองออกจากเอาต์พุต |
| อักษรตัวใหญ่ขึ้นต้น | ตัวอักษรเริ่มต้นขนาดใหญ่รวมกับข้อความที่ตามมา |
| จุดนำ | จุดสไตล์ TOC ยุบเป็น " ... " |

## กรณีการใช้งาน: การกำหนดเส้นทาง PDF อัจฉริยะ

pdf-inspector ถูกสร้างขึ้นสำหรับไปป์ไลน์ที่ประมวลผล PDF ในปริมาณมาก แทนที่จะส่ง PDF ทุกไฟล์ผ่าน OCR:

สิ่งนี้ช่วยประหยัดค่าใช้จ่ายและลดเวลาแฝงสำหรับ PDF ส่วนใหญ่ที่เป็นข้อความอยู่แล้ว (รายงาน, เอกสารวิชาการ, ใบแจ้งหนี้, เอกสารทางกฎหมาย)

## การดีบัก

ดู [docs/debugging.md](https://github.com/firecrawl/pdf-inspector/blob/main/docs/debugging.md) สำหรับการใช้งานตัวแปรสภาพแวดล้อม `RUST_LOG`

## ใบอนุญาต

[MIT](https://github.com/firecrawl/pdf-inspector/blob/main/LICENSE)