oxidize-pdf

A pure Rust PDF generation and manipulation library with zero external PDF dependencies. Production-ready for basic PDF functionality. Generate PDFs 2x faster than PDFSharp, with memory safety guarantees and a 5.2MB binary size.

Features

🚀 100% Pure Rust - No C dependencies or external PDF libraries
📄 PDF Generation - Create multi-page documents with text, graphics, and images
🔍 PDF Parsing - Read and extract content from existing PDFs (tested on 749 real-world PDFs*)
✂️ PDF Operations - Split, merge, and rotate PDFs while preserving basic content
🖼️ Image Support - Embed JPEG images with automatic compression
🎨 Rich Graphics - Vector graphics with shapes, paths, colors (RGB/CMYK/Gray)
📝 Advanced Text - Custom TTF/OTF fonts, standard fonts, text flow with automatic wrapping, alignment
🅰️ Custom Fonts - Load and embed TrueType/OpenType fonts with full Unicode support
🔍 OCR Support - Extract text from scanned PDFs using Tesseract OCR (v0.1.3+)
🤖 AI/RAG Integration - Document chunking for LLM pipelines with sentence boundaries and metadata (v1.3.0+)
🗜️ Compression - Built-in FlateDecode compression for smaller files
🔒 Type Safe - Leverage Rust's type system for safe PDF manipulation

🎉 What's New

Latest: v1.3.0 - AI/RAG Integration:

🤖 Document Chunking for LLMs - Production-ready chunking with 0.62ms for 100 pages
📊 Rich Metadata - Page tracking, position info, confidence scores
✂️ Smart Boundaries - Sentence boundary detection for semantic coherence
⚡ Exceptional Performance - 161x better than target, 160K pages/second throughput
📚 Complete Examples - RAG pipeline with embeddings and vector store integration

Major features (v1.1.6+):

🅰️ Custom Font Support - Load TTF/OTF fonts from files or memory
✍️ Advanced Text Formatting - Character spacing, word spacing, text rise, rendering modes
📋 Clipping Paths - Both EvenOdd and NonZero winding rules
💾 In-Memory Generation - Generate PDFs without file I/O using to_bytes()
🗜️ Compression Control - Enable/disable compression with set_compress()

Significant improvements in PDF compatibility:

📈 Better parsing: Handles more PDF structures including circular references
🛡️ Stack overflow protection - More resilient against malformed PDFs
🚀 Performance: Fast parsing for basic PDF operations
⚡ Error recovery - Better handling of corrupted files
🔧 Lenient parsing - Handles some malformed PDFs
💾 Memory optimization: New OptimizedPdfReader with LRU cache

Note: *Success rates apply only to non-encrypted PDFs with basic features. The library provides basic PDF functionality. See Known Limitations for a transparent assessment of current capabilities and planned features.

🏆 Why oxidize-pdf?

Performance & Efficiency

2x faster than PDFSharp - Process 215 PDFs/second
5.2 MB binary - 3x smaller than PDFSharp, 40x smaller than IronPDF
Zero dependencies - No runtime, no Chrome, just a single binary
Low memory usage - Efficient streaming for large PDFs

Safety & Reliability

Memory safe - Guaranteed by Rust compiler (no null pointers, no buffer overflows)
Type safe API - Catch errors at compile time
3,000+ tests - Comprehensive test suite with real-world PDFs
No CVEs possible - Memory safety eliminates entire classes of vulnerabilities

Developer Experience

Modern API - Designed in 2024, not ported from 2005
True cross-platform - Single binary runs on Linux, macOS, Windows, ARM
Easy deployment - One file to ship, no dependencies to manage
Fast compilation - Incremental builds in seconds

Quick Start

Add oxidize-pdf to your Cargo.toml:

[dependencies]
oxidize-pdf = "1.1.0"

# For OCR support (optional)
oxidize-pdf = { version = "1.1.0", features = ["ocr-tesseract"] }

Basic PDF Generation

use oxidize_pdf::{Document, Page, Font, Color, Result};

fn main() -> Result<()> {
    // Create a new document
    let mut doc = Document::new();
    doc.set_title("My First PDF");
    doc.set_author("Rust Developer");
    
    // Create a page
    let mut page = Page::a4();
    
    // Add text
    page.text()
        .set_font(Font::Helvetica, 24.0)
        .at(50.0, 700.0)
        .write("Hello, PDF!")?;
    
    // Add graphics
    page.graphics()
        .set_fill_color(Color::rgb(0.0, 0.5, 1.0))
        .circle(300.0, 400.0, 50.0)
        .fill();
    
    // Add the page and save
    doc.add_page(page);
    doc.save("hello.pdf")?;
    
    Ok(())
}

AI/RAG Document Chunking (v1.3.0+)

use oxidize_pdf::ai::DocumentChunker;
use oxidize_pdf::parser::{PdfReader, PdfDocument};
use oxidize_pdf::Result;

fn main() -> Result<()> {
    // Load and parse PDF
    let reader = PdfReader::open("document.pdf")?;
    let pdf_doc = PdfDocument::new(reader);
    let text_pages = pdf_doc.extract_text()?;

    // Prepare page texts with page numbers
    let page_texts: Vec<(usize, String)> = text_pages
        .iter()
        .enumerate()
        .map(|(idx, page)| (idx + 1, page.text.clone()))
        .collect();

    // Create chunker: 512 tokens per chunk, 50 tokens overlap
    let chunker = DocumentChunker::new(512, 50);
    let chunks = chunker.chunk_text_with_pages(&page_texts)?;

    // Process chunks for RAG pipeline
    for chunk in chunks {
        println!("Chunk {}: {} tokens", chunk.id, chunk.tokens);
        println!("  Pages: {:?}", chunk.page_numbers);
        println!("  Position: chars {}-{}",
            chunk.metadata.position.start_char,
            chunk.metadata.position.end_char);
        println!("  Sentence boundary: {}",
            chunk.metadata.sentence_boundary_respected);

        // Send to embedding API, store in vector DB, etc.
        // let embedding = openai.embed(&chunk.content)?;
        // vector_db.insert(chunk.id, embedding, chunk.content)?;
    }

    Ok(())
}

Custom Fonts Example

use oxidize_pdf::{Document, Page, Font, Color, Result};

fn main() -> Result<()> {
    let mut doc = Document::new();
    doc.set_title("Custom Fonts Demo");

    // Load a custom font from file
    doc.add_font("MyFont", "/path/to/font.ttf")?;

    // Or load from bytes
    let font_data = std::fs::read("/path/to/font.otf")?;
    doc.add_font_from_bytes("MyOtherFont", font_data)?;

    let mut page = Page::a4();

    // Use standard font
    page.text()
        .set_font(Font::Helvetica, 14.0)
        .at(50.0, 700.0)
        .write("Standard Font: Helvetica")?;

    // Use custom font
    page.text()
        .set_font(Font::Custom("MyFont".to_string()), 16.0)
        .at(50.0, 650.0)
        .write("Custom Font: This is my custom font!")?;

    // Advanced text formatting with custom font
    page.text()
        .set_font(Font::Custom("MyOtherFont".to_string()), 12.0)
        .set_character_spacing(2.0)
        .set_word_spacing(5.0)
        .at(50.0, 600.0)
        .write("Spaced text with custom font")?;

    doc.add_page(page);
    doc.save("custom_fonts.pdf")?;

    Ok(())
}

Parse Existing PDF

use oxidize_pdf::{PdfReader, Result};

fn main() -> Result<()> {
    // Open and parse a PDF
    let mut reader = PdfReader::open("document.pdf")?;
    
    // Get document info
    println!("PDF Version: {}", reader.version());
    println!("Page Count: {}", reader.page_count()?);
    
    // Extract text from all pages
    let document = reader.into_document();
    let text = document.extract_text()?;
    
    for (page_num, page_text) in text.iter().enumerate() {
        println!("Page {}: {}", page_num + 1, page_text.content);
    }
    
    Ok(())
}

Working with Images

use oxidize_pdf::{Document, Page, Image, Result};

fn main() -> Result<()> {
    let mut doc = Document::new();
    let mut page = Page::a4();
    
    // Load a JPEG image
    let image = Image::from_jpeg_file("photo.jpg")?;
    
    // Add image to page
    page.add_image("my_photo", image);
    
    // Draw the image
    page.draw_image("my_photo", 100.0, 300.0, 400.0, 300.0)?;
    
    doc.add_page(page);
    doc.save("image_example.pdf")?;
    
    Ok(())
}

Advanced Text Flow

use oxidize_pdf::{Document, Page, Font, TextAlign, Result};

fn main() -> Result<()> {
    let mut doc = Document::new();
    let mut page = Page::a4();
    
    // Create text flow with automatic wrapping
    let mut flow = page.text_flow();
    flow.at(50.0, 700.0)
        .set_font(Font::Times, 12.0)
        .set_alignment(TextAlign::Justified)
        .write_wrapped("This is a long paragraph that will automatically wrap \
                       to fit within the page margins. The text is justified, \
                       creating clean edges on both sides.")?;
    
    page.add_text_flow(&flow);
    doc.add_page(page);
    doc.save("text_flow.pdf")?;
    
    Ok(())
}

PDF Operations

use oxidize_pdf::operations::{PdfSplitter, PdfMerger, PageRange};
use oxidize_pdf::Result;

fn main() -> Result<()> {
    // Split a PDF
    let splitter = PdfSplitter::new("input.pdf")?;
    splitter.split_by_pages("page_{}.pdf")?; // page_1.pdf, page_2.pdf, ...
    
    // Merge PDFs
    let mut merger = PdfMerger::new();
    merger.add_pdf("doc1.pdf", PageRange::All)?;
    merger.add_pdf("doc2.pdf", PageRange::Pages(vec![1, 3, 5]))?;
    merger.save("merged.pdf")?;
    
    // Rotate pages
    use oxidize_pdf::operations::{PdfRotator, RotationAngle};
    let rotator = PdfRotator::new("input.pdf")?;
    rotator.rotate_all(RotationAngle::Clockwise90, "rotated.pdf")?;
    
    Ok(())
}

OCR Text Extraction

use oxidize_pdf::text::tesseract_provider::{TesseractOcrProvider, TesseractConfig};
use oxidize_pdf::text::ocr::{OcrOptions, OcrProvider};
use oxidize_pdf::operations::page_analysis::PageContentAnalyzer;
use oxidize_pdf::parser::PdfReader;
use oxidize_pdf::Result;

fn main() -> Result<()> {
    // Open a scanned PDF
    let document = PdfReader::open_document("scanned.pdf")?;
    let analyzer = PageContentAnalyzer::new(document);
    
    // Configure OCR provider
    let config = TesseractConfig::for_documents();
    let ocr_provider = TesseractOcrProvider::with_config(config)?;
    
    // Find and process scanned pages
    let scanned_pages = analyzer.find_scanned_pages()?;
    
    for page_num in scanned_pages {
        let result = analyzer.extract_text_from_scanned_page(page_num, &ocr_provider)?;
        println!("Page {}: {} (confidence: {:.1}%)", 
                 page_num, result.text, result.confidence * 100.0);
    }
    
    Ok(())
}

OCR Installation

Before using OCR features, install Tesseract on your system:

macOS:

brew install tesseract
brew install tesseract-lang  # For additional languages

Ubuntu/Debian:

sudo apt-get install tesseract-ocr
sudo apt-get install tesseract-ocr-spa  # For Spanish
sudo apt-get install tesseract-ocr-deu  # For German

Windows: Download from: https://github.com/UB-Mannheim/tesseract/wiki

Supported Features

PDF Generation

✅ Multi-page documents
✅ Vector graphics (rectangles, circles, paths, lines)
✅ Text rendering with standard fonts (Helvetica, Times, Courier)
✅ JPEG image embedding
✅ RGB, CMYK, and Grayscale colors
✅ Graphics transformations (translate, rotate, scale)
✅ Text flow with automatic line wrapping
✅ FlateDecode compression

PDF Parsing

✅ PDF 1.0 - 1.7 basic structure support
✅ Cross-reference table parsing
✅ Object and stream parsing
✅ Page tree navigation (simple)
✅ Content stream parsing (basic operators)
✅ Text extraction (simple cases)
✅ Document metadata extraction
✅ Filter support (FlateDecode, ASCIIHexDecode, ASCII85Decode, RunLengthDecode, LZWDecode)

PDF Operations

✅ Split by pages, ranges, or size
✅ Merge multiple PDFs
✅ Rotate pages (90°, 180°, 270°)
✅ Basic content preservation

OCR Support (v0.1.3+)

✅ Tesseract OCR integration with feature flag
✅ Multi-language support (50+ languages)
✅ Page analysis and scanned page detection
✅ Configurable preprocessing (denoise, deskew, contrast)
✅ Layout preservation with position information
✅ Confidence scoring and filtering
✅ Multiple page segmentation modes (PSM)
✅ Character whitelisting/blacklisting
✅ Mock OCR provider for testing
✅ Parallel and batch processing

Performance

Parsing: Fast for PDFs with basic features
Generation: Efficient for simple documents
Memory efficient: Streaming operations available
Pure Rust: No external C dependencies

Examples

Check out the examples directory for more usage patterns:

hello_world.rs - Basic PDF creation
graphics_demo.rs - Vector graphics showcase
text_formatting.rs - Advanced text features
custom_fonts.rs - TTF/OTF font loading and embedding
jpeg_image.rs - Image embedding
parse_pdf.rs - PDF parsing and text extraction
comprehensive_demo.rs - All features demonstration
tesseract_ocr_demo.rs - OCR text extraction (requires --features ocr-tesseract)
scanned_pdf_analysis.rs - Analyze PDFs for scanned content
extract_images.rs - Extract embedded images from PDFs
create_pdf_with_images.rs - Advanced image embedding examples

Run examples with:

cargo run --example hello_world

# For OCR examples
cargo run --example tesseract_ocr_demo --features ocr-tesseract

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) - see the LICENSE file for details.

Why AGPL-3.0?

AGPL-3.0 ensures that oxidize-pdf remains free and open source while protecting against proprietary use in SaaS without contribution back to the community. This license:

✅ Allows free use, modification, and distribution
✅ Requires sharing modifications if you provide the software as a service
✅ Ensures improvements benefit the entire community
✅ Supports sustainable open source development

Commercial Products & Licensing

oxidize-pdf-core is free and open source (AGPL-3.0). For commercial products and services:

Commercial Products:

oxidize-pdf-pro: Enhanced library with advanced features
oxidize-pdf-api: REST API server for PDF operations
oxidize-pdf-cli: Command-line interface with enterprise capabilities

Commercial License Benefits:

✅ Commercial-friendly terms (no AGPL obligations)
✅ Advanced features (cloud OCR, batch processing, digital signatures)
✅ Priority support and SLAs
✅ Custom feature development
✅ Access to commercial products (API, CLI, PRO library)

Contact: bzsanti@outlook.com for commercial licensing inquiries.

Known Limitations

oxidize-pdf provides basic PDF functionality. We prioritize transparency about what works and what doesn't.

Working Features

✅ Compression: FlateDecode, ASCIIHexDecode, ASCII85Decode, RunLengthDecode, LZWDecode, DCTDecode (JPEG)
✅ Color Spaces: DeviceRGB, DeviceCMYK, DeviceGray
✅ Fonts: Standard 14 fonts + TTF/OTF custom font loading and embedding
✅ Images: JPEG embedding, raw RGB/Gray data
🚧 PNG Support: Basic functionality (7 tests failing - compression issues)
✅ Operations: Split, merge, rotate, page extraction, text extraction
✅ Graphics: Vector operations, clipping paths, transparency (CA/ca)
✅ Encryption: RC4 40/128-bit, AES-128/256 with permissions
✅ Forms: Basic text fields, checkboxes, radio buttons, combo boxes, list boxes

Known Issues & Missing Features

🐛 PNG Compression: 7 tests consistently failing - use JPEG for now
🚧 Form Interactions: Forms can be created but not edited interactively
❌ Rendering: No PDF to image conversion
❌ Advanced Compression: CCITTFaxDecode, JBIG2Decode, JPXDecode
❌ Advanced Graphics: Complex patterns, shadings, gradients, advanced blend modes
❌ Digital Signatures: Signature fields exist but no signing capability
❌ Tagged PDFs: No accessibility/structure support yet
❌ Advanced Color: ICC profiles, spot colors, Lab color space
❌ JavaScript: No form calculations or validation scripts
❌ Multimedia: No sound, video, or 3D content support

Examples Status

We're actively adding more examples for core features. New examples include:

merge_pdfs.rs - PDF merging with various options
split_pdf.rs - Different splitting strategies
extract_text.rs - Text extraction with layout preservation
encryption.rs - RC4 and AES encryption demonstrations

Important Notes

Parsing success doesn't mean full feature support
Many PDFs will parse but advanced features will be ignored
This is early beta software with significant limitations

Project Structure

oxidize-pdf/
├── oxidize-pdf-core/     # Core PDF library (AGPL-3.0)
├── test-suite/           # Comprehensive test suite
├── docs/                 # Documentation
│   ├── technical/        # Technical docs and implementation details
│   └── reports/          # Analysis and test reports
├── tools/                # Development and analysis tools
├── scripts/              # Build and release scripts
└── test-pdfs/            # Test PDF files

Commercial Products (available separately under commercial license):

oxidize-pdf-api: REST API server for PDF operations
oxidize-pdf-cli: Command-line interface with advanced features
oxidize-pdf-pro: Enhanced library with additional capabilities

See REPOSITORY_ARCHITECTURE.md for detailed information.

Testing

oxidize-pdf includes comprehensive test suites to ensure reliability:

# Run standard test suite (synthetic PDFs)
cargo test

# Run all tests including performance benchmarks
cargo test -- --ignored

# Run with local PDF fixtures (if available)
OXIDIZE_PDF_FIXTURES=on cargo test

# Run OCR tests (requires Tesseract installation)
cargo test tesseract_ocr_tests --features ocr-tesseract -- --ignored

Local PDF Fixtures (Optional)

For enhanced testing with real-world PDFs, you can optionally set up local PDF fixtures:

Create a symbolic link: tests/fixtures -> /path/to/your/pdf/collection
The test suite will automatically detect and use these PDFs
Fixtures are never committed to the repository (excluded in .gitignore)
Tests work fine without fixtures using synthetic PDFs

Note: CI/CD always uses synthetic PDFs only for consistent, fast builds.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Roadmap

oxidize-pdf is under active development. Our focus areas include:

Current Focus

Parsing & Compatibility: Improving support for diverse PDF structures
Core Operations: Enhancing split, merge, and manipulation capabilities
Performance: Optimizing memory usage and processing speed
Stability: Addressing edge cases and error handling

Upcoming Areas

Extended Format Support: Additional image formats and encodings
Advanced Text Processing: Improved text extraction and layout analysis
Enterprise Features: Features designed for production use at scale
Developer Experience: Better APIs, documentation, and tooling

Long-term Vision

Comprehensive PDF standard compliance for common use cases
Production-ready reliability and performance
Rich ecosystem of tools and integrations
Sustainable open source development model

We prioritize features based on community feedback and real-world usage. Have a specific need? Open an issue to discuss!

Support

Acknowledgments

Built with ❤️ using Rust. Special thanks to the Rust community and all contributors.

oxidize-pdf 1.3.0

oxidize-pdf

Features

🎉 What's New

🏆 Why oxidize-pdf?

Performance & Efficiency

Safety & Reliability

Developer Experience

Quick Start

Basic PDF Generation

AI/RAG Document Chunking (v1.3.0+)

Custom Fonts Example

Parse Existing PDF

Working with Images

Advanced Text Flow

PDF Operations

OCR Text Extraction

OCR Installation

Supported Features

PDF Generation

PDF Parsing

PDF Operations

OCR Support (v0.1.3+)

Performance

Examples

License

Why AGPL-3.0?

Commercial Products & Licensing

Known Limitations

Working Features

Known Issues & Missing Features

Examples Status

Important Notes

Project Structure

Testing

Local PDF Fixtures (Optional)

Contributing

Roadmap

Current Focus

Upcoming Areas

Long-term Vision

Support

Acknowledgments