spdf

Fast, spatial PDF parsing in Rust.

Extract text with preserved columns, tables, and layout — plus optional OCR for scans, format conversion for Office docs, and a single self-contained binary.

Why spdf

Most PDF-to-text tools collapse whitespace, shuffle columns, and emit one giant line salad — fine for search indexing, useless for anything that cares about where things appear on the page (invoices, tax bills, property records, scientific tables, legal forms).

spdf keeps the geometry:

• Column-aware projection — tables, two-column layouts, sidebars, and indented blocks come back in reading order with their spatial structure intact.
• Faux-bold & shadow dedup — PDFs that "draw text twice" to simulate bold no longer produce TaTax Infofo; you get Tax Info.
• Word reconstruction — PDFium-style per-glyph extraction is stitched back into words (1 8 3 6 → 1836) using a liteparse-compatible merge heuristic.
• QR / barcode / microprint filtering — the hundreds of tiny numeric glyphs that encode a QR code are auto-dropped so they don't destroy the surrounding table.
• Optional OCR — Tesseract locally, or any HTTP OCR server (PaddleOCR, EasyOCR, etc.) for image-only pages. One flag to turn it off when you know the PDF is born-digital.
• Format conversion — Office docs via LibreOffice shell-out, images via ImageMagick, all behind the same CLI.
• One static binary. Install PDFium once, ship spdf anywhere.

Comparison

Benchmarked on two real-world U.S. county tax documents (TAX_APPEAL_MOM set) with --no-ocr. Token-level F1 measured against the same documents parsed through LiteParse using the provided reference outputs in tests/parity/.

Parity harness and golden outputs live in tests/parity/; run python3 tests/parity/compare.py to reproduce.

Benchmark

Reproducible head-to-head against LiteParse on the fixtures in example/. Ground truth is raw tesseract <image> - -l eng (PDFs rendered with pdftoppm -r 150 first); tokens are compared case-insensitively as a multiset.

This is a like-for-like comparison, not a knock on LiteParse. LiteParse is the project spdf was designed against — we owe the original authors for the reference implementation of the spatial projection algorithm, and the goal of publishing these numbers is transparency about where the Rust port stands, not to make the TypeScript original look bad.

Mean over fixtures: spdf F1 80.6% in 366 ms; liteparse F1 77.4% in 2594 ms.

Spatial precision

Token accuracy alone doesn't tell you whether an engine put each word in the right place on the page — which is the whole point of a spatial parser. We also compare every matched word's bounding box against the raw-tesseract ground truth and report mean IoU, the fraction of matches that clear IoU ≥ 0.5 (the COCO-style "well localised" bar), and the mean centroid error in PDF points.

Mean over fixtures: spdf mean IoU 0.679, 73.8% of matches ≥ 0.5, centroid error 44.64 pt; liteparse 0.482 / 61.1% / 77.05 pt.

Per-fixture raw outputs are committed under benchmark/outputs/ so the numbers are auditable. Reproduce on your own machine:

make build-ocr   # or `make install-ocr`
LITEPARSE_DIR=/path/to/liteparse make benchmark-update

Production-readiness

spdf is pre-1.0. The table below tracks what we've hardened so you can decide whether it fits your threat model; see CHANGELOG.md for per-release detail.

Recommended posture when parsing untrusted PDFs today:

let parser = SpdfParser::builder()
    .timeout_secs(30)           // defensive deadline
    .max_input_bytes(50 << 20)  // 50 MiB input cap
    .max_pages(500)             // reject page-tree bombs
    .build();

Then wrap the process in a resource-capped sandbox (systemd-run --property=MemoryMax=1G, Firejail, Docker --memory=). Follow the full hardening checklist in SECURITY.md.

Install

Prebuilt binaries

Self-contained tarballs (bundled libpdfium, no runtime deps) are attached to each GitHub release. Download, extract, and run. OCR is not compiled into the prebuilt binaries — use --ocr-server-url for HTTP OCR or cargo install with --features spdf-cli/tesseract for a local Tesseract build.

To produce a release tarball on a new host:

cargo build --release -p spdf-cli
VER=0.2.0-alpha.1
TARGET=$(rustc -vV | awk '/^host:/ {print $2}')
DIR="spdf-${VER}-${TARGET}"
mkdir -p "dist/${DIR}"
cp target/release/spdf "dist/${DIR}/"          # use spdf.exe on Windows
cp LICENSE README.md CHANGELOG.md "dist/${DIR}/"
tar czf "dist/${DIR}.tar.gz" -C dist "${DIR}"   # or zip on Windows
sha256sum "dist/${DIR}.tar.gz" > "dist/${DIR}.tar.gz.sha256"
gh release upload v${VER} "dist/${DIR}.tar.gz" "dist/${DIR}.tar.gz.sha256"

From source

# from source (requires Rust 1.85+)
cargo install --path crates/spdf-cli

# or build locally
cargo build --release -p spdf-cli
./target/release/spdf --help

Runtime dependency: PDFium

spdf dynamically loads a PDFium shared library. On macOS:

brew install pdfium

Or download a prebuilt binary from bblanchon/pdfium-binaries and point PDFIUM_LIB_PATH at it.

Platform support matrix

Windows OCR caveat. The tesseract Rust crate used by spdf-ocr links against libtesseract + libleptonica via bindgen, which needs a working C toolchain (clang) and a vcpkg or manually-installed Tesseract/Leptonica. The CI matrix builds spdf on Windows without the tesseract feature; the Linux/macOS jobs cover OCR. If you need Windows OCR in production today, install Tesseract via vcpkg install tesseract leptonica --triplet x64-windows, set LIBCLANG_PATH, and build with cargo build --release -p spdf-cli --features spdf-cli/tesseract. The HTTP OCR backend (--ocr-server-url) works on every platform and is the recommended option for Windows until we cut a proper MSVC-native build.

Quick start

# Plain text with preserved layout
spdf parse invoice.pdf --no-ocr --format text

# Structured JSON with per-glyph bounding boxes
spdf parse invoice.pdf --no-ocr --format json > out.json

# OCR-only mode for scanned PDFs
spdf parse scan.pdf --ocr-language eng

# Use an external OCR server (PaddleOCR, EasyOCR, etc.)
spdf parse scan.pdf --ocr-server-url http://localhost:8000

# Render specific pages
spdf parse book.pdf --target-pages 1-3,7,12-15

# Dump pages as PNGs
spdf screenshot report.pdf -o ./pages --dpi 200

# Batch-convert a directory of PDFs
spdf batch-parse ./inputs ./outputs --format text

Library usage

use spdf_core::LiteParse;
use spdf_types::ParseConfig;

let parser = LiteParse::new(ParseConfig {
    ocr_enabled: false,
    ..Default::default()
});
let result = parser.parse_path("invoice.pdf")?;
for page in &result.pages {
    println!("--- page {} ---\n{}", page.page_num, page.text);
}

Architecture

crates/
  spdf-types/        public schema
  spdf-processing/   text / geometry / markup helpers
  spdf-projection/   spatial reconstruction (the crown jewel)
  spdf-pdf/          PdfEngine trait + PDFium impl
  spdf-ocr/          OcrEngine trait + Tesseract + HTTP impls
  spdf-convert/      LibreOffice / ImageMagick shell-outs
  spdf-output/       JSON + text formatters
  spdf-core/         orchestrator
  spdf-cli/          spdf binary
  spdf-ffi/          C ABI cdylib
xtask/               parity harness, benches, pdfium fetcher

See AGENTS.md for the full crate map and CONTRIBUTING.md for development workflow.

Roadmap

• Node bindings (@spdf/node) on top of spdf-ffi
• Python bindings via PyO3
• spdf serve — a local HTTP parsing service
• Optional ML-based reading-order classifier (opt-in, burn feature flag)

Acknowledgements

spdf is an independent Rust project authored by Fanaperana. The spatial projection algorithm was inspired by (and is benchmarked against) LiteParse, but spdf is not a port or rewrite — it's its own implementation, with its own engine choices (PDFium + Tesseract), its own data model, and its own hardening work. Rendering is powered by PDFium; OCR uses Tesseract.

License

MIT © 2026 spdf contributors.