Migrating from PdfPig

This maps the PdfPig calls most programs use to their OnePDF equivalents. It is based on PdfPig's public documentation and README; check its docs for details of its behavior. OnePDF's API is smaller in some places and larger in others, so this is a map, not a drop-in replacement.

The differences that matter first

Opening

// PdfPig
using var document = PdfDocument.Open("a.pdf", new ParsingOptions { Password = "secret" });
 
// OnePDF
using var doc = OnePdf.PdfDocument.Open("a.pdf", new OnePdf.PdfOpenOptions { Password = "secret" });

A wrong or missing password throws PdfPasswordException. The user or the owner password opens the file. doc.Permissions reports the permission flags; they are not enforced.

Pages

Metadata

Text

PdfPig's Page.Text is the content-stream order of letters. OnePDF's default is reading order (structure tree for tagged files, geometry otherwise). Use PdfTextMode.ContentOrder for the nearest equivalent of Page.Text.

// PdfPig
using var document = PdfDocument.Open("a.pdf");
foreach (Page page in document.GetPages())
{
    Console.WriteLine(page.Text);
    foreach (Word word in page.GetWords())
        Console.WriteLine($"{word.Text} {word.BoundingBox}");
}
 
// OnePDF
using var doc = OnePdf.PdfDocument.Open("a.pdf");
foreach (OnePdf.Text.PdfPageText page in doc.ExtractText())    // pages in parallel
{
    Console.WriteLine(page.Text);
    foreach (OnePdf.Text.PdfTextWord word in page.Words)
        Console.WriteLine($"{word.Text} {word.Bounds}");
}

doc.ExtractText() does every page in parallel and also flags headers and footers by their repetition across pages; the degree is PdfTextOptions.MaxDegreeOfParallelism (default min(4, cores)). To keep a long document within memory it does not keep each page's glyph list (PdfTextOptions.RetainGlyphs); every plain-text mode, words, lines and blocks are still there, and pageText.ReadGlyphs() reads the glyphs of a page on request.

Things that behave differently and can change your output:

• Ligatures are decomposed by default (DecomposeLigatures); /ActualText replaces the text it covers.
• Line-end hyphens are kept unless you set JoinHyphenatedWords.
• Text that is clipped out or off the page is excluded unless you set IncludeClippedAndOffPage.
• Duplicate fake-bold text is collapsed (CollapseDuplicates).
• Right-to-left text comes out in logical order (UAX #9), not in the visual order of the content stream.
• Words with no Unicode mapping come out as U+FFFD; OnePDF never guesses by OCR.

Beyond text

PdfPig has no real page rendering. In OnePDF, page.Interpret(device) drives an IPdfDevice with paths, glyph runs, images, shadings and groups; PdfDisplayList is the recording device. Producing pixels is the job of a separate package, RecursiveAI.OneImage.Pdf, built on OneImage (see PDF pages as images).

What OnePDF does not have

PdfPig builds documents from nothing with PdfDocumentBuilder. OnePDF does too, with PdfDocument.CreateEmpty, InsertBlankPage and the content builder (content creation). It also changes and saves existing documents, including incremental updates and encryption (writing). The core content builder does no text shaping; RecursiveAI.OnePdf.Layout shapes complex scripts (Arabic, Indic and more) when it lays out text (see layout text).