### Install Node.js Package

Source: https://github.com/firecrawl/pdf-inspector/blob/main/README.md

Install the @firecrawl/pdf-inspector package for Node.js using npm.

```bash
npm install @firecrawl/pdf-inspector
```

--------------------------------

### Install PDF Inspector CLI

Source: https://github.com/firecrawl/pdf-inspector/blob/main/README.md

Install the pdf-inspector command-line interface tools using cargo.

```bash
cargo install pdf-inspector
```

--------------------------------

### Install PDF Inspector

Source: https://github.com/firecrawl/pdf-inspector/blob/main/napi/README.md

Install the PDF Inspector library using npm or bun. Prebuilt binaries are included for Linux x64 and macOS ARM64.

```bash
npm install @firecrawl/pdf-inspector
```

```bash
bun add @firecrawl/pdf-inspector
```

--------------------------------

### Install PDF Inspector with Maturin

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/python.md

Install the necessary tool and develop the Python package locally. This is typically done before using the library.

```bash
pip install maturin
maturin develop --release
```

--------------------------------

### Process PDF and Get Markdown

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/python.md

Perform full processing on a PDF file to detect its type, extract content, and convert it to Markdown. Useful for comprehensive document analysis.

```python
import pdf_inspector

# Full processing: detect + extract + convert to Markdown
result = pdf_inspector.process_pdf("document.pdf")
print(result.pdf_type)      # "text_based", "scanned", "image_based", "mixed"
print(result.confidence)     # 0.0 - 1.0
print(result.page_count)     # number of pages
print(result.markdown)       # Markdown string or None
```

--------------------------------

### Extract Text Within Specified Regions of a PDF Page

Source: https://github.com/firecrawl/pdf-inspector/blob/main/napi/README.md

Utilize `extractTextInRegions` to get text from defined bounding boxes on PDF pages. This is useful for hybrid OCR pipelines, extracting text directly from PDF structure for text-based pages to avoid unnecessary OCR.

```typescript
import { extractTextInRegions } from '@firecrawl/pdf-inspector'

const result = extractTextInRegions(pdf, [
  {
    page: 0, // 0-indexed
    regions: [
      [0, 0, 300, 400],    // [x1, y1, x2, y2] in PDF points, top-left origin
      [300, 0, 612, 400],
    ]
  }
])

for (const region of result[0].regions) {
  if (region.needsOcr) {
    // Unreliable text — send this region to OCR instead
  } else {
    console.log(region.text) // Extracted text in reading order
  }
}
```

--------------------------------

### Build and Test Commands

Source: https://github.com/firecrawl/pdf-inspector/blob/main/AGENTS.md

Commands for formatting, linting, running unit and integration tests, and building the release binary.

```bash
cargo fmt                                    # format
cargo clippy -- -D warnings                  # lint (enforced, zero warnings)
cargo test                                   # unit + integration tests (267+ unit, 73+ integration)
cargo build --release                        # release binary for benchmarks
```

--------------------------------

### Build and Test Commands

Source: https://github.com/firecrawl/pdf-inspector/blob/main/CLAUDE.md

Commands for formatting, linting, running tests, and building the release binary. Ensure all three pass before committing.

```bash
cargo fmt
                                    # format
cargo clippy -- -D warnings                  # lint (enforced, zero warnings)
cargo test                                   # unit + integration tests (267+ unit, 73+ integration)
cargo build --release                        # release binary for benchmarks
```

--------------------------------

### Run CLI Tools from Source Checkout

Source: https://github.com/firecrawl/pdf-inspector/blob/main/README.md

When working from a source checkout, use 'cargo run' to execute the pdf2md or detect-pdf binaries.

```bash
cargo run --bin pdf2md -- document.pdf
cargo run --bin detect-pdf -- document.pdf
```

--------------------------------

### Customize PDF Processing with PdfOptions

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/rust-api.md

Configure PDF processing using `PdfOptions` for various scenarios like layout analysis, custom detection strategies, or processing specific pages.

```rust
use pdf_inspector::{process_pdf_with_options, PdfOptions, ProcessMode, DetectionConfig, ScanStrategy};

// Analyze layout without generating markdown
let result = process_pdf_with_options(
    "document.pdf",
    PdfOptions::new().mode(ProcessMode::Analyze),
)?;

// Full extraction with custom detection strategy
let result = process_pdf_with_options(
    "large.pdf",
    PdfOptions::new().detection(DetectionConfig {
        strategy: ScanStrategy::Sample(5),
        ..Default::default()
    }),
)?;

// Process only specific pages
let result = process_pdf_with_options(
    "document.pdf",
    PdfOptions::new().pages([1, 3, 5]),
)?;
```

--------------------------------

### to_markdown(text, options)

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/rust-api.md

Converts plain text content into Markdown format using specified options.

```APIDOC
## to_markdown(text, options)

### Description
Converts plain text to Markdown format.

### Function Signature
`fn to_markdown(text: &str, options: &MarkdownOptions) -> Result<String, Error>`

### Parameters
#### Request Body
- **text** (string) - Required - The plain text to convert.
- **options** (MarkdownOptions) - Required - Options for Markdown conversion.
```

--------------------------------

### Smart PDF Routing Pipeline Logic

Source: https://github.com/firecrawl/pdf-inspector/blob/main/README.md

Illustrates the decision-making process for routing PDFs based on classification. This logic helps optimize processing by avoiding unnecessary OCR for text-based documents.

```text
PDF arrives
  → pdf-inspector classifies it (~20ms)
  → TextBased + high confidence?
      YES → extract locally (~150ms), done
      NO  → send to OCR service (2-10s)
```

--------------------------------

### process_pdf_with_options(path, options)

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/rust-api.md

Processes a PDF file at the specified path with custom processing options.

```APIDOC
## process_pdf_with_options(path, options)

### Description
Process a PDF file with custom `PdfOptions`.

### Function Signature
`fn process_pdf_with_options(path: &str, options: PdfOptions) -> PdfProcessResult`

### Parameters
#### Path Parameters
- **path** (string) - Required - The file path to the PDF document.
- **options** (PdfOptions) - Required - Custom options for PDF processing.
```

--------------------------------

### Add pdf-inspector to Cargo.toml

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/rust-api.md

Add the pdf-inspector crate to your project's dependencies in Cargo.toml by specifying the git repository.

```toml
[dependencies]
pdf-inspector = { git = "https://github.com/firecrawl/pdf-inspector" }
```

--------------------------------

### process_pdf_mem_with_options(bytes, options)

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/rust-api.md

Processes a PDF from a byte buffer with custom processing options.

```APIDOC
## process_pdf_mem_with_options(bytes, options)

### Description
Process a PDF from a byte buffer with custom `PdfOptions`.

### Function Signature
`fn process_pdf_mem_with_options(bytes: &[u8], options: PdfOptions) -> PdfProcessResult`

### Parameters
#### Request Body
- **bytes** (byte array) - Required - The byte buffer containing the PDF data.
- **options** (PdfOptions) - Required - Custom options for PDF processing.
```

--------------------------------

### Debugging PDF Detector

Source: https://github.com/firecrawl/pdf-inspector/blob/main/AGENTS.md

Set the RUST_LOG environment variable to debug the PDF detector binary, useful for classifying PDF types.

```bash
RUST_LOG=pdf_inspector::detector=debug cargo run --release --bin detect-pdf -- file.pdf
```

--------------------------------

### Process PDF from Byte Buffer

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/rust-api.md

Use `process_pdf_mem` to process PDF data directly from a byte slice, avoiding the need to read from the filesystem.

```rust
use pdf_inspector::process_pdf_mem;

let bytes = std::fs::read("document.pdf")?;
let result = process_pdf_mem(&bytes)?;
```

--------------------------------

### Fast PDF Metadata Detection

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/rust-api.md

Utilize `detect_pdf` for quick metadata extraction without full text processing. This is useful for determining if OCR is needed.

```rust
use pdf_inspector::detect_pdf;

let info = detect_pdf("document.pdf")?;

match info.pdf_type {
    pdf_inspector::PdfType::TextBased => {
        // Extract locally — fast and free
    }
    _ => {
        // Route to OCR service
        // info.pages_needing_ocr tells you exactly which pages
    }
}
```

--------------------------------

### Detect and Extract PDF Content

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/rust-api.md

Use the `process_pdf` function for a one-call solution to detect PDF type, confidence, page count, and extract markdown content.

```rust
use pdf_inspector::process_pdf;

let result = process_pdf("document.pdf")?;

println!("Type: {:?}", result.pdf_type);       // TextBased, Scanned, ImageBased, Mixed
println!("Confidence: {:.0}%", result.confidence * 100.0);
println!("Pages: {}", result.page_count);

if let Some(markdown) = &result.markdown {
    println!("{}", markdown);
}
```

--------------------------------

### Detect PDF Type using CLI

Source: https://github.com/firecrawl/pdf-inspector/blob/main/README.md

Use the detect-pdf CLI tool to determine the type of a PDF file. Options include JSON output and detailed layout analysis.

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

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

--------------------------------

### to_markdown_from_items(items, options)

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/rust-api.md

Converts a collection of pre-extracted `TextItem`s into Markdown format.

```APIDOC
## to_markdown_from_items(items, options)

### Description
Converts pre-extracted `TextItem`s to Markdown format.

### Function Signature
`fn to_markdown_from_items(items: Vec<TextItem>, options: &MarkdownOptions) -> Result<String, Error>`

### Parameters
#### Request Body
- **items** (array of TextItem) - Required - The list of `TextItem`s to convert.
- **options** (MarkdownOptions) - Required - Options for Markdown conversion.
```

--------------------------------

### Debugging Table Detection

Source: https://github.com/firecrawl/pdf-inspector/blob/main/AGENTS.md

Set the RUST_LOG environment variable to debug table detection logic during PDF to Markdown conversion.

```bash
RUST_LOG=pdf_inspector::tables=debug cargo run --bin pdf2md -- file.pdf
```

--------------------------------

### process_pdf_with_options

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/rust-api.md

Processes a PDF file with customizable options, allowing control over the processing mode, detection strategy, and specific pages to process.

```APIDOC
## process_pdf_with_options

### Description
Processes a PDF file with customizable options, allowing control over the processing mode, detection strategy, and specific pages to process.

### Function Signature
`process_pdf_with_options(file_path: &str, options: PdfOptions) -> Result<ProcessResult, Error>`

### Parameters
#### Path Parameters
- **file_path** (string) - Required - The path to the PDF file to process.
#### Request Body
- **options** (PdfOptions) - Required - An object containing processing options.
  - **mode** (ProcessMode) - Optional - The processing mode (e.g., Analyze, Extract).
  - **detection** (DetectionConfig) - Optional - Configuration for PDF detection.
    - **strategy** (ScanStrategy) - Optional - The scanning strategy (e.g., Sample).
  - **pages** (Slice of usize) - Optional - A slice specifying which pages to process.

### Request Example
```rust
use pdf_inspector::{process_pdf_with_options, PdfOptions, ProcessMode, DetectionConfig, ScanStrategy};

// Analyze layout without generating markdown
let result = process_pdf_with_options(
    "document.pdf",
    PdfOptions::new().mode(ProcessMode::Analyze),
)?;

// Full extraction with custom detection strategy
let result = process_pdf_with_options(
    "large.pdf",
    PdfOptions::new().detection(DetectionConfig {
        strategy: ScanStrategy::Sample(5),
        ..Default::default()
    }),
)?;

// Process only specific pages
let result = process_pdf_with_options(
    "document.pdf",
    PdfOptions::new().pages([1, 3, 5]),
)?;
```
```

--------------------------------

### PDF Inspector Architecture Diagram

Source: https://github.com/firecrawl/pdf-inspector/blob/main/README.md

Illustrates the flow of PDF data through the detection and extraction pipeline, including sub-modules for layout analysis and Markdown conversion. The document is loaded once to avoid redundant parsing.

```text
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
```

--------------------------------

### Add Rust Package Dependency

Source: https://github.com/firecrawl/pdf-inspector/blob/main/README.md

Add the pdf-inspector crate to your Rust project's dependencies either via cargo add or by manually editing Cargo.toml.

```bash
cargo add pdf-inspector
```

```toml
[dependencies]
pdf-inspector = "0.1"
```

--------------------------------

### process_pdf(path)

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/rust-api.md

Performs full processing of a PDF file located at the specified path, using default options. This includes detection, extraction, and conversion to Markdown.

```APIDOC
## process_pdf(path)

### Description
Full processing of a PDF file with default options.

### Function Signature
`fn process_pdf(path: &str) -> PdfProcessResult`

### Parameters
#### Path Parameters
- **path** (string) - Required - The file path to the PDF document.
```

--------------------------------

### to_markdown_from_items_with_rects(items, options, rects)

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/rust-api.md

Converts `TextItem`s into Markdown format, considering rectangle-based table detection.

```APIDOC
## to_markdown_from_items_with_rects(items, options, rects)

### Description
Converts `TextItem`s to Markdown with rectangle-based table detection.

### Function Signature
`fn to_markdown_from_items_with_rects(items: Vec<TextItem>, options: &MarkdownOptions, rects: Vec<Rect>) -> Result<String, Error>`

### Parameters
#### Request Body
- **items** (array of TextItem) - Required - The list of `TextItem`s to convert.
- **options** (MarkdownOptions) - Required - Options for Markdown conversion.
- **rects** (array of Rect) - Required - Rectangles for table detection.
```

--------------------------------

### PDF Inspector Project Structure

Source: https://github.com/firecrawl/pdf-inspector/blob/main/README.md

Outlines the directory and file organization for the PDF Inspector project, including source code, bindings, and CLI tools. Key modules handle API, Python bindings, types, text utilities, and detection/extraction pipelines.

```text
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)
```

--------------------------------

### Process PDF in Rust

Source: https://github.com/firecrawl/pdf-inspector/blob/main/README.md

Use the pdf_inspector library in Rust to process a PDF file and print its type and Markdown content.

```rust
use pdf_inspector::process_pdf;

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

--------------------------------

### Debugging Extractor Layout

Source: https://github.com/firecrawl/pdf-inspector/blob/main/AGENTS.md

Set the RUST_LOG environment variable to debug the layout module during PDF extraction.

```bash
RUST_LOG=pdf_inspector::extractor::layout=debug cargo run --bin pdf2md -- file.pdf
```

--------------------------------

### Debug Table Detection

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/debugging.md

Set RUST_LOG to 'pdf_inspector::tables=debug' to enable debugging for table detection.

```bash
RUST_LOG=pdf_inspector::tables=debug cargo run --bin pdf2md -- file.pdf > /dev/null
```

--------------------------------

### Debug Column Detection and Reading Order

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/debugging.md

Set RUST_LOG to 'pdf_inspector::extractor::layout=debug' to debug column detection and reading order. This replaces the functionality of debug_order.

```bash
RUST_LOG=pdf_inspector::extractor::layout=debug cargo run --bin pdf2md -- file.pdf > /dev/null
```

--------------------------------

### Process PDF from Bytes

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/python.md

Process PDF content directly from bytes without needing to access the filesystem. Ideal for in-memory operations or when the PDF is received as a byte stream.

```python
# Process from bytes (no filesystem needed)
with open("document.pdf", "rb") as f:
    result = pdf_inspector.process_pdf_bytes(f.read())
```

--------------------------------

### Debug Y-gap Analysis and Paragraph Thresholds

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/debugging.md

Use RUST_LOG=pdf_inspector::markdown::analysis=debug to debug y-gap analysis and paragraph thresholds. This replaces the functionality of debug_ygaps.

```bash
RUST_LOG=pdf_inspector::markdown::analysis=debug cargo run --bin pdf2md -- file.pdf > /dev/null
```

--------------------------------

### Debug All pdf-inspector Components

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/debugging.md

Set RUST_LOG=pdf_inspector=debug to enable debugging for all components of the pdf-inspector project. This provides comprehensive debug output.

```bash
RUST_LOG=pdf_inspector=debug cargo run --bin pdf2md -- file.pdf > /dev/null
```

--------------------------------

### process_pdf_mem

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/rust-api.md

Processes a PDF file directly from a byte buffer, eliminating the need for filesystem access.

```APIDOC
## process_pdf_mem

### Description
Processes a PDF file directly from a byte buffer, eliminating the need for filesystem access.

### Function Signature
`process_pdf_mem(bytes: &[u8]) -> Result<ProcessResult, Error>`

### Parameters
#### Request Body
- **bytes** (byte slice) - Required - The byte slice containing the PDF data.

### Response
#### Success Response
- **pdf_type** (PdfType) - The type of the PDF.
- **confidence** (f32) - The confidence score of the detection.
- **page_count** (usize) - The total number of pages in the PDF.
- **markdown** (Option<String>) - The extracted markdown content, if generated.

### Request Example
```rust
use pdf_inspector::process_pdf_mem;

let bytes = std::fs::read("document.pdf")?;
let result = process_pdf_mem(&bytes)?;
```
```

--------------------------------

### detect_pdf(path)

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/rust-api.md

Performs fast metadata-only detection of a PDF file at the specified path without performing extraction.

```APIDOC
## detect_pdf(path)

### Description
Fast metadata-only detection of a PDF file.

### Function Signature
`fn detect_pdf(path: &str) -> PdfDetectResult`

### Parameters
#### Path Parameters
- **path** (string) - Required - The file path to the PDF document.
```

--------------------------------

### Debug Font Metadata, Encodings, and Ligatures

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/debugging.md

Use RUST_LOG=pdf_inspector::extractor::fonts=debug to debug font metadata, encodings, and ligatures. This replaces the functionality of debug_fonts and debug_ligatures.

```bash
RUST_LOG=pdf_inspector::extractor::fonts=debug cargo run --bin pdf2md -- file.pdf > /dev/null
```

--------------------------------

### process_pdf_mem(bytes)

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/rust-api.md

Performs full processing of a PDF from a byte buffer, including detection, extraction, and conversion to Markdown.

```APIDOC
## process_pdf_mem(bytes)

### Description
Full processing of a PDF from a byte buffer with default options.

### Function Signature
`fn process_pdf_mem(bytes: &[u8]) -> PdfProcessResult`

### Parameters
#### Request Body
- **bytes** (byte array) - Required - The byte buffer containing the PDF data.
```

--------------------------------

### Extract Per-Page Markdown

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/python.md

Generate Markdown for each page of a PDF, including layout metadata. This provides a structured representation of each page's content.

```python
# Per-page markdown (one Markdown string per page, plus layout metadata)
result = pdf_inspector.extract_pages_markdown("document.pdf")
for page in result.pages:
    print(f"Page {page.page}: {len(page.markdown)} chars, needs_ocr={page.needs_ocr}")
```

--------------------------------

### Process PDF in Node.js

Source: https://github.com/firecrawl/pdf-inspector/blob/main/README.md

Use the @firecrawl/pdf-inspector library to process a PDF file and access its type and Markdown content.

```javascript
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
```

--------------------------------

### Debug Text Items per Page with Coordinates

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/debugging.md

Use RUST_LOG=pdf_inspector::extractor=debug to debug text items per page, including their x/y coordinates and width. This replaces the functionality of debug_spaces and debug_pages.

```bash
RUST_LOG=pdf_inspector::extractor=debug cargo run --bin pdf2md -- file.pdf > /dev/null
```

--------------------------------

### detect_pdf_mem(bytes)

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/rust-api.md

Performs fast metadata-only detection of a PDF from a byte buffer.

```APIDOC
## detect_pdf_mem(bytes)

### Description
Fast metadata-only detection of a PDF from a byte buffer.

### Function Signature
`fn detect_pdf_mem(bytes: &[u8]) -> PdfDetectResult`

### Parameters
#### Request Body
- **bytes** (byte array) - Required - The byte buffer containing the PDF data.
```

--------------------------------

### Convert PDF to Markdown using CLI

Source: https://github.com/firecrawl/pdf-inspector/blob/main/README.md

Convert a PDF file to Markdown format using the pdf2md CLI tool. Options include JSON output, raw markdown, page breaks, and page selection.

```bash
# Convert PDF to Markdown
pdf2md document.pdf

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

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

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

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

--------------------------------

### Process PDF in Python

Source: https://github.com/firecrawl/pdf-inspector/blob/main/README.md

Use the pdf_inspector library to process a PDF file and access its type and Markdown content.

```python
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
```

--------------------------------

### process_pdf

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/python.md

Performs full PDF processing, including detection, text extraction, and conversion to Markdown. It can process the entire document or specific pages.

```APIDOC
## process_pdf(path, pages=None)

### Description
Full processing (detect + extract + markdown) for a PDF file.

### Parameters
#### Path Parameters
- **path** (string) - Required - Path to the PDF file.
- **pages** (list of int) - Optional - A list of 0-indexed page numbers to process. If None, all pages are processed.
```

--------------------------------

### Debug ToUnicode CMap Parsing

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/debugging.md

Set RUST_LOG to 'pdf_inspector::tounicode=debug' to enable debugging for ToUnicode CMap parsing.

```bash
RUST_LOG=pdf_inspector::tounicode=debug cargo run --bin pdf2md -- file.pdf > /dev/null
```

--------------------------------

### process_pdf_bytes

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/python.md

Performs full PDF processing on PDF data provided as bytes, including detection, text extraction, and conversion to Markdown. It can process the entire document or specific pages.

```APIDOC
## process_pdf_bytes(data, pages=None)

### Description
Full processing from bytes (detect + extract + markdown).

### Parameters
#### Path Parameters
- **data** (bytes) - Required - The PDF file content as bytes.
- **pages** (list of int) - Optional - A list of 0-indexed page numbers to process. If None, all pages are processed.
```

--------------------------------

### detect_pdf

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/python.md

Performs fast PDF detection to determine its type (text-based, scanned, etc.) without full text extraction. Returns a PdfResult object.

```APIDOC
## detect_pdf(path)

### Description
Fast detection only (returns PdfResult).

### Parameters
#### Path Parameters
- **path** (string) - Required - Path to the PDF file.
```

--------------------------------

### Debug Raw PDF Content Stream Operators

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/debugging.md

Set RUST_LOG to 'pdf_inspector::extractor::content_stream=trace' to view raw PDF content stream operators. This replaces the functionality of dump_ops.

```bash
RUST_LOG=pdf_inspector::extractor::content_stream=trace cargo run --bin pdf2md -- file.pdf > /dev/null
```

--------------------------------

### extract_text(path)

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/rust-api.md

Extracts plain text content from a PDF file.

```APIDOC
## extract_text(path)

### Description
Extracts plain text content from a PDF file.

### Function Signature
`fn extract_text(path: &str) -> Result<String, Error>`

### Parameters
#### Path Parameters
- **path** (string) - Required - The file path to the PDF document.
```

--------------------------------

### Process Specific PDF Pages

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/python.md

Process only a subset of pages from a PDF document. This is useful for targeting specific sections or reducing processing time.

```python
# Process specific pages only
result = pdf_inspector.process_pdf("document.pdf", pages=[1, 3, 5])
```

--------------------------------

### extract_pages_markdown(path, pages)

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/rust-api.md

Extracts per-page Markdown and layout metadata from a PDF file.

```APIDOC
## extract_pages_markdown(path, pages)

### Description
Extracts per-page Markdown and layout metadata from a PDF file.

### Function Signature
`fn extract_pages_markdown(path: &str, pages: &[u32]) -> Result<Vec<PageMarkdownResult>, Error>`

### Parameters
#### Path Parameters
- **path** (string) - Required - The file path to the PDF document.
- **pages** (array of unsigned integers) - Required - The specific pages to extract Markdown from.
```

--------------------------------

### detect_pdf_bytes

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/python.md

Performs fast PDF detection on PDF data provided as bytes to determine its type without full text extraction. Returns a PdfResult object.

```APIDOC
## detect_pdf_bytes(data)

### Description
Fast detection from bytes (returns PdfResult).

### Parameters
#### Path Parameters
- **data** (bytes) - Required - The PDF file content as bytes.
```

--------------------------------

### extract_pages_markdown_mem(bytes, pages)

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/rust-api.md

Extracts per-page Markdown from a PDF byte buffer.

```APIDOC
## extract_pages_markdown_mem(bytes, pages)

### Description
Extracts per-page Markdown from a PDF byte buffer.

### Function Signature
`fn extract_pages_markdown_mem(bytes: &[u8], pages: &[u32]) -> Result<Vec<PageMarkdownResult>, Error>`

### Parameters
#### Request Body
- **bytes** (byte array) - Required - The byte buffer containing the PDF data.
- **pages** (array of unsigned integers) - Required - The specific pages to extract Markdown from.
```

--------------------------------

### Extract Specific Pages as Markdown

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/python.md

Extract Markdown content for a specified list of 0-indexed pages from a PDF. This allows for targeted extraction while preserving the order of the requested pages.

```python
# Restrict to specific 0-indexed pages (preserves caller order)
result = pdf_inspector.extract_pages_markdown("document.pdf", pages=[0, 2])
```

--------------------------------

### Fast PDF Detection

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/python.md

Quickly detect the type of PDF (text-based, scanned, etc.) without performing full text extraction. This is useful for determining if OCR is needed.

```python
# Fast detection only (no text extraction)
result = pdf_inspector.detect_pdf("document.pdf")
if result.pdf_type == "text_based":
    print("Can extract locally!")
else:
    print(f"Pages needing OCR: {result.pages_needing_ocr}")
```

--------------------------------

### process_pdf

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/rust-api.md

Detects and extracts information from a PDF file in a single call. This function returns the PDF type, confidence score, page count, and optionally, markdown content.

```APIDOC
## process_pdf

### Description
Detects and extracts information from a PDF file in a single call. This function returns the PDF type, confidence score, page count, and optionally, markdown content.

### Function Signature
`process_pdf(file_path: &str) -> Result<ProcessResult, Error> `

### Parameters
#### Path Parameters
- **file_path** (string) - Required - The path to the PDF file to process.

### Response
#### Success Response
- **pdf_type** (PdfType) - The type of the PDF (e.g., TextBased, Scanned).
- **confidence** (f32) - The confidence score of the detection.
- **page_count** (usize) - The total number of pages in the PDF.
- **markdown** (Option<String>) - The extracted markdown content, if generated.

### Request Example
```rust
use pdf_inspector::process_pdf;

let result = process_pdf("document.pdf")?;

println!("Type: {:?}", result.pdf_type);
println!("Confidence: {:.0}%", result.confidence * 100.0);
println!("Pages: {}", result.page_count);

if let Some(markdown) = &result.markdown {
    println!("{}", markdown);
}
```
```

--------------------------------

### Extract Per-Page Markdown

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/rust-api.md

The `extract_pages_markdown` function extracts markdown for each page individually, along with document-wide layout metadata. It allows specifying which pages to process or processing all pages.

```rust
use pdf_inspector::extract_pages_markdown;

// Pass `None` for every page in document order, or a slice of 0-indexed
// pages to restrict the output (caller-supplied order is preserved).
let result = extract_pages_markdown("document.pdf", None)?;

for page in &result.pages {
    if page.needs_ocr {
        // Route this page to OCR
    } else {
        println!("Page {}: {}", page.page, page.markdown);
    }
}

println!("Complex layout? {}", result.is_complex);
```

--------------------------------

### extract_text

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/python.md

Extracts plain text content from a PDF file.

```APIDOC
## extract_text(path)

### Description
Plain text extraction.

### Parameters
#### Path Parameters
- **path** (string) - Required - Path to the PDF file.
```

--------------------------------

### Extract Plain Text from PDF

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/python.md

Extract only the plain text content from a PDF document. Use this when only the textual content is required, without any formatting or layout information.

```python
# Plain text extraction
text = pdf_inspector.extract_text("document.pdf")
```

--------------------------------

### extract_pages_markdown_bytes

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/python.md

Extracts Markdown content for each page from PDF data provided as bytes, along with layout metadata. By default, all pages are processed.

```APIDOC
## extract_pages_markdown_bytes(data, pages=None)

### Description
Per-page Markdown from bytes.

### Parameters
#### Path Parameters
- **data** (bytes) - Required - The PDF file content as bytes.
- **pages** (list of int) - Optional - A list of 0-indexed page numbers to extract Markdown from. If None, all pages are processed.
```

--------------------------------

### Page Regions Definition for Text Extraction

Source: https://github.com/firecrawl/pdf-inspector/blob/main/napi/README.md

Defines the structure for specifying regions on a PDF page from which text should be extracted. Includes the page number and an array of bounding box coordinates.

```typescript
interface PageRegions {
  page: number              // 0-indexed
  regions: number[][]       // [[x1, y1, x2, y2], ...] in PDF points, top-left origin
}
```

--------------------------------

### extract_pages_markdown

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/python.md

Extracts Markdown content for each page of a PDF file, along with layout metadata. By default, all pages are processed.

```APIDOC
## extract_pages_markdown(path, pages=None)

### Description
Per-page Markdown + layout metadata (all pages by default).

### Parameters
#### Path Parameters
- **path** (string) - Required - Path to the PDF file.
- **pages** (list of int) - Optional - A list of 0-indexed page numbers to extract Markdown from. If None, all pages are processed.
```

--------------------------------

### Extract Positioned Text with Font Info

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/python.md

Extract text items along with their precise positions (X, Y coordinates) and font details. Useful for analyzing document layout and specific text element placement.

```python
# Positioned text items with font info
items = pdf_inspector.extract_text_with_positions("document.pdf")
for item in items[:5]:
    print(f"'{item.text}' at ({item.x:.0f}, {item.y:.0f}) size={item.font_size}")
```

--------------------------------

### extractTextInRegions

Source: https://github.com/firecrawl/pdf-inspector/blob/main/napi/README.md

Extracts text from specified bounding-box regions within a PDF. This is useful for hybrid OCR pipelines, allowing text extraction from PDF structure for text-based pages, thus avoiding unnecessary OCR processing.

```APIDOC
## extractTextInRegions(buffer: Buffer, pageRegions: PageRegions[]): PageRegionTexts[]

### Description
Extract text within bounding-box regions from a PDF. Designed for hybrid OCR pipelines where a layout model detects regions in rendered page images, and this function extracts text from the PDF structure for text-based pages — skipping GPU OCR.

### Method
`extractTextInRegions`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **buffer** (Buffer) - Required - The PDF file content as a Buffer.
* **pageRegions** (PageRegions[]) - Required - An array of objects, each specifying a page number and an array of regions (bounding boxes) on that page from which to extract text.

### Request Example
```typescript
import { extractTextInRegions } from '@firecrawl/pdf-inspector'

const result = extractTextInRegions(pdf, [
  {
    page: 0, // 0-indexed
    regions: [
      [0, 0, 300, 400],    // [x1, y1, x2, y2] in PDF points, top-left origin
      [300, 0, 612, 400],
    ]
  }
])

for (const region of result[0].regions) {
  if (region.needsOcr) {
    // Unreliable text — send this region to OCR instead
  } else {
    console.log(region.text) // Extracted text in reading order
  }
}
```

### Response
#### Success Response (PageRegionTexts[])
An array of objects, where each object corresponds to a processed page and contains an array of extracted text regions.
* **page** (number) - The 0-indexed page number.
* **regions** (RegionText[]) - An array of text extraction results for the specified regions on the page.
  * **text** (string) - The extracted text. This field may be empty if extraction is unreliable.
  * **needsOcr** (boolean) - True if the extracted text is unreliable and OCR might be needed for accuracy.

### Response Example
```json
[
  {
    "page": 0,
    "regions": [
      {
        "text": "Extracted text from region 1.",
        "needsOcr": false
      },
      {
        "text": "",
        "needsOcr": true
      }
    ]
  }
]
```
```

--------------------------------

### classify_pdf_bytes

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/python.md

Performs lightweight PDF classification on PDF data provided as bytes to determine its type and page count. Returns a PdfClassification object.

```APIDOC
## classify_pdf_bytes(data)

### Description
Lightweight classification from bytes (returns PdfClassification).

### Parameters
#### Path Parameters
- **data** (bytes) - Required - The PDF file content as bytes.
```

--------------------------------

### classify_pdf

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/python.md

Performs lightweight PDF classification to determine its type and page count. Returns a PdfClassification object.

```APIDOC
## classify_pdf(path)

### Description
Lightweight classification (returns PdfClassification).

### Parameters
#### Path Parameters
- **path** (string) - Required - Path to the PDF file.
```

--------------------------------

### extract_text_bytes

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/python.md

Extracts plain text content from PDF data provided as bytes.

```APIDOC
## extract_text_bytes(data)

### Description
Plain text extraction from bytes.

### Parameters
#### Path Parameters
- **data** (bytes) - Required - The PDF file content as bytes.
```

--------------------------------

### classifyPdf

Source: https://github.com/firecrawl/pdf-inspector/blob/main/napi/README.md

Classifies a PDF document to determine its type (TextBased, Scanned, Mixed, or ImageBased) and identifies which pages might require OCR. This function is optimized for speed, typically completing within 10-50ms.

```APIDOC
## classifyPdf(buffer: Buffer): PdfClassification

### Description
Classify a PDF as TextBased, Scanned, Mixed, or ImageBased (~10-50ms). Returns which pages need OCR.

### Method
`classifyPdf`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **buffer** (Buffer) - Required - The PDF file content as a Buffer.

### Response
#### Success Response (PdfClassification)
* **pdfType** (string) - The classification of the PDF ('TextBased', 'Scanned', 'Mixed', 'ImageBased').
* **pageCount** (number) - The total number of pages in the PDF.
* **pagesNeedingOcr** (number[]) - An array of 0-indexed page numbers that require OCR.
* **confidence** (number) - A confidence score (0.0 - 1.0) for the classification.

### Request Example
```typescript
import { classifyPdf } from '@firecrawl/pdf-inspector'
import { readFileSync } from 'fs'

const pdf = readFileSync('document.pdf')
const result = classifyPdf(pdf)

console.log(result.pdfType)
console.log(result.pageCount)
console.log(result.pagesNeedingOcr)
console.log(result.confidence)
```

### Response Example
```json
{
  "pdfType": "TextBased",
  "pageCount": 42,
  "pagesNeedingOcr": [5, 12, 15],
  "confidence": 0.875
}
```
```

--------------------------------

### extract_text_with_positions

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/python.md

Extracts text items from a PDF file, including their positions (X/Y coordinates) and font information.

```APIDOC
## extract_text_with_positions(path, pages=None)

### Description
Text with X/Y coordinates and font info.

### Parameters
#### Path Parameters
- **path** (string) - Required - Path to the PDF file.
- **pages** (list of int) - Optional - A list of 0-indexed page numbers to extract text from. If None, all pages are processed.
```

--------------------------------

### extract_text_with_positions_bytes

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/python.md

Extracts text items from PDF data provided as bytes, including their positions (X/Y coordinates) and font information.

```APIDOC
## extract_text_with_positions_bytes(data, pages=None)

### Description
Text with positions from bytes.

### Parameters
#### Path Parameters
- **data** (bytes) - Required - The PDF file content as bytes.
- **pages** (list of int) - Optional - A list of 0-indexed page numbers to extract text from. If None, all pages are processed.
```

--------------------------------

### PDF Classification Type Definition

Source: https://github.com/firecrawl/pdf-inspector/blob/main/napi/README.md

Defines the structure for the result of PDF classification, including the detected PDF type, page count, pages needing OCR, and confidence score.

```typescript
interface PdfClassification {
  pdfType: string          // "TextBased" | "Scanned" | "Mixed" | "ImageBased"
  pageCount: number
  pagesNeedingOcr: number[] // 0-indexed page numbers
  confidence: number        // 0.0 - 1.0
}
```

--------------------------------

### extract_text_in_regions

Source: https://github.com/firecrawl/pdf-inspector/blob/main/docs/python.md

Extracts text within specified bounding-box regions on given pages of a PDF file.

```APIDOC
## extract_text_in_regions(path, page_regions)

### Description
Extract text in bounding-box regions.

### Parameters
#### Path Parameters
- **path** (string) - Required - Path to the PDF file.
- **page_regions** (list of dict) - Required - A list where each dictionary specifies a page and the regions to extract text from. Each dictionary should have a 'page' (0-indexed int) and 'regions' (list of region dicts, each with 'x', 'y', 'width', 'height').
```

--------------------------------

### Classify PDF Document Type and OCR Needs

Source: https://github.com/firecrawl/pdf-inspector/blob/main/napi/README.md

Use the `classifyPdf` function to determine if a PDF is TextBased, Scanned, Mixed, or ImageBased. It also returns the total page count and a list of pages that require OCR.

```typescript
import { classifyPdf } from '@firecrawl/pdf-inspector'
import { readFileSync } from 'fs'

const pdf = readFileSync('document.pdf')
const result = classifyPdf(pdf)

console.log(result.pdfType)        // "TextBased" | "Scanned" | "Mixed" | "ImageBased"
console.log(result.pageCount)      // 42
console.log(result.pagesNeedingOcr) // [5, 12, 15] (0-indexed)
console.log(result.confidence)     // 0.875
```