OfficeIMO.Reader.Pdf 3.5.2

OfficeIMO.Reader.Pdf - PDF reader and compatibility projection bridge

OfficeIMO.Reader.Pdf reads PDF artifacts into the normalized Reader model. For existing Reader workflows it also contains a thin compatibility bridge that maps an OfficeDocumentReadResult into the dependency-free OfficeDocumentModel; the actual output policy and PDF composition are owned by OfficeIMO.Pdf. It does not pull Word, Excel, PowerPoint, Email, or the all-adapters composition package.

Install

dotnet add package OfficeIMO.Reader.Pdf

Register

using OfficeIMO.Reader;
using OfficeIMO.Reader.Pdf;

OfficeDocumentReader reader = new OfficeDocumentReaderBuilder()
    .AddPdfHandler()
    .Build();

IReadOnlyList<ReaderChunk> chunks = reader
    .Read("invoice.pdf")
    .ToList();

Examples

For an encrypted PDF, register AddPdfHandler(new ReaderPdfOptions { Password = password }) with a password supplied by the caller. The password is used locally to open the PDF and is not included in extracted content or metadata. PDF content-extraction permissions still apply.

Inspect native decoding and incomplete pages

Register full PDF parser settings through ReaderPdfOptions.LoadOptions. Registration and each read take independent option and resource-limit snapshots; ReaderOptions.MaxInputBytes can further restrict the PDF input budget.

using OfficeIMO.Pdf;
using OfficeIMO.Reader;
using OfficeIMO.Reader.Pdf;

var reader = new OfficeDocumentReaderBuilder()
    .AddPdfHandler(new ReaderPdfOptions {
        LoadOptions = new PdfLoadOptions {
            Limits = new PdfReadLimits { MaxPages = 500, MaxDecodedStreamBytes = 16 * 1024 * 1024 }
        }
    })
    .Build();
OfficeDocumentReadResult document = reader.ReadDocument("input.pdf", new ReaderOptions {
    Inspection = new ReaderInspectionOptions { MaxRecords = 4096, MaxCharacters = 1_000_000 }
});

Inspection uses the canonical PDF page pipeline and returns successful pages with explicit failed-page warnings and diagnostics. Located metadata records in pdf.page-outcome, pdf.text-decoding and pdf.repair retain every selected occurrence, decoding source, fallback and parser recovery evidence. Unreadable pages retain source links, annotations, page actions and geometry as metadata. Resource, cancellation, authentication, permission and unexpected parser failures remain terminal. The existing Reader JSON schema is unchanged. Without Inspection, PDF reading retains its fail-fast behavior. Native inspection does not run OCR.

Set ReaderOptions.Projection = ReaderProjection.TextAndMetadata to retain plain text chunks and metadata while skipping Markdown, image extraction, assets, visuals, normalized forms and OCR candidates. Combine it with Inspection to retain page outcomes and located decoding evidence. Source form counts and descriptors remain available; canonical parsing still retains bounded source field values. Full is the default projection.

To project an already loaded PdfDocumentReadResult, call logical.ReadDocument("input.pdf", readerOptions, pdfOptions). This uses the same Reader projection and operation budgets without opening the named path, parsing again, or rendering pages. The caller controls the native load, input limits and authentication. Inspection describes the supplied logical pages as existing-projection; it does not reassess original page completion or recreate native failure outcomes. Load with native IncludeImages = false and IncludeFormWidgets = false as well when you need to avoid that work before the Reader projection.

When you already have a PdfInspectionReadResult, call inspection.ReadDocument("input.pdf", readerOptions, pdfOptions). This preserves failed page outcomes and original selection indexes, including repeated pages. Choose pages in the native ReadForInspection call; this overload rejects a second page selection during projection. It retains bounded inspection evidence and uses the same Reader output budgets without reopening the source.

Discover OCR needs on mixed pages

The default policy emits candidates for image pages without native text. For a scanned body with a native footer, opt into mixed-page discovery:

var reader = new OfficeDocumentReaderBuilder()
    .AddPdfHandler(new ReaderPdfOptions {
        IncludeMixedPageOcrCandidates = true,
        MinimumMixedPageImageAreaRatio = 0.25
    })
    .Build();
var document = reader.ReadDocument("mixed-invoice.pdf");

The image-area threshold filters small decorative images. It is a discovery heuristic, not proof that an image contains text or that native text covers the image. Native blocks remain available, while candidates and ocr-needed diagnostics disclose the additional review. Use OfficeIMO.Pdf.Ocr for rendered-page recognition, geometry-aware native-text merging and searchable output; the Reader adapter does not run an OCR provider.

Read page-aware Markdown chunks

using OfficeIMO.Reader;
using OfficeIMO.Reader.Pdf;

OfficeDocumentReader reader = new OfficeDocumentReaderBuilder()
    .AddPdfHandler()
    .Build();

foreach (var chunk in reader.Read("manual.pdf")) {
    Console.WriteLine($"Page {chunk.Location.Page}: {chunk.Id}");
    Console.WriteLine(chunk.Markdown ?? chunk.Text);
}

OfficeDocumentReadResult document = reader.ReadDocument("manual.pdf");
OfficeDocumentSearchResult matches = document.Search("installation");
Console.WriteLine(string.Join(", ", matches.Hits
    .SelectMany(hit => hit.Pages)
    .Select(page => page.Display)));

Cross-page paragraph continuation evidence is projected into document metadata without rewriting page-local text or chunk boundaries. The default confidence policy is conservative and can be tightened at registration time:

using OfficeIMO.Pdf;
using OfficeIMO.Reader;
using OfficeIMO.Reader.Pdf;

OfficeDocumentReader reader = new OfficeDocumentReaderBuilder()
    .AddPdfHandler(new ReaderPdfOptions {
        ParagraphContinuationOptions = new PdfLogicalParagraphContinuationOptions {
            MinimumConfidence = 0.85,
            RejoinSoftHyphens = true
        }
    })
    .Build();

OfficeDocumentReadResult document = reader.ReadDocument("manual.pdf");
IReadOnlyList<OfficeDocumentMetadataEntry> continuations = document.Metadata
    .Where(entry => entry.Category == "pdf.paragraph.continuation")
    .ToArray();

The semantic reader processes at most 1,000 selected pages by default. Set the semantic pipeline limit explicitly when a larger document is expected:

OfficeDocumentReader largePdfReader = new OfficeDocumentReaderBuilder()
    .AddPdfHandler(new ReaderPdfOptions {
        ReadOptions = new PdfReadOptions {
            Pipeline = new PdfUnderstandingPipelineOptions { MaxPages = 2_500 }
        }
    })
    .Build();

ReaderPdfOptions.ReadOptions is the canonical PDF semantic configuration. Use it for Profile, PageSelection, LayoutOptions, custom stages, and semantic work limits; the Reader adapter does not maintain a second set of PDF parsing options.

Headerless or otherwise ambiguous PDF tables retain every detected source row and expose empty column names. ReaderChunkDiagnostics.UnnamedTableColumnCount reports that uncertainty; the adapter does not inject English fallback names.

Read a stream with input limits

using OfficeIMO.Reader;
using OfficeIMO.Reader.Pdf;

OfficeDocumentReader reader = new OfficeDocumentReaderBuilder()
    .AddPdfHandler()
    .Build();

using var stream = File.OpenRead("large-report.pdf");
var chunks = reader.Read(stream, "large-report.pdf", new ReaderOptions {
    MaxChars = 12_000,
    MaxInputBytes = 100L * 1024L * 1024L
}).ToList();

foreach (var chunk in chunks.Where(chunk => chunk.Diagnostics != null)) {
    Console.WriteLine($"{chunk.Id}: {chunk.Diagnostics!.TableCount} table(s)");
}

Project a normalized document into PDF

using OfficeIMO.Drawing;
using OfficeIMO.Pdf;
using OfficeIMO.Reader;

OfficeDocumentReadResult normalized = reader.ReadDocument("manual.pdf");
PdfDocumentConversionResult conversion = normalized.ToPdfDocumentResult(
    new PdfProjectionOptions {
        PagePolicy = PdfProjectionPagePolicy.PreserveSourcePages,
        AssetPolicy = PdfProjectionAssetPolicy.EmbedSupportedImages,
        RasterDecodeOptions = new OfficeRasterDecodeOptions {
            AnimationPolicy = OfficeRasterAnimationPolicy.RejectAnimated
        },
        LinkPolicy = PdfProjectionLinkPolicy.PreserveUriLinks,
        FormPolicy = PdfProjectionFormPolicy.RenderCurrentValues
    });

PdfSaveResult save = conversion.Save("normalized-manual.pdf");
foreach (PdfConversionWarning warning in save.Warnings) {
    Console.WriteLine($"{warning.Code}: {warning.Message}");
}

The same projection accepts normalized results produced by Email, EPUB, Visio, Office, and other Reader adapters without taking dependencies on those packages. Source diagnostics are merged with PDF generation diagnostics. Email attachment, EPUB resource/pagination, and Visio preview/semantic fallback decisions are recorded explicitly. Page-scoped and document-scoped normalized collections are reconciled by the neutral model identities, so aggregate resources are retained without repeating page content. The Drawing raster policy is used for selected GIF frames and animation rejection; selecting a frame emits loss evidence rather than silently flattening animation. This does not advertise a direct format converter until that route has its own artifact and degradation gates.

Register alongside other ingestion adapters

using OfficeIMO.Reader;
using OfficeIMO.Reader.Html;
using OfficeIMO.Reader.Pdf;
using OfficeIMO.Reader.Zip;

OfficeDocumentReader reader = new OfficeDocumentReaderBuilder()
    .AddHtmlHandler()
    .AddPdfHandler()
    .AddZipHandler()
    .Build();

var chunks = reader.ReadFolder("KnowledgeBase", new ReaderFolderOptions {
    Recurse = true,
    DeterministicOrder = true,
    MaxFiles = 500
}).ToList();

What it emits

• Page-aware chunks with ReaderLocation.Page.
• Native fixed-page membership and geometry compatible with Reader Core location, search, and page-Markdown helpers.
• Markdown text, logical tables, column profiles, table diagnostics, and confidence signals.
• Conservative paragraph continuation metadata with page range, confidence, evidence, segment count, and rejoined soft-hyphen count.
• Source/security/form/catalog-metadata/open-action/active-content counters in ReaderChunk.Diagnostics.
• Document metadata for XMP, output intents, tagged structure, optional content/layers, attachments, security/signatures, navigation, links, forms, annotations, and passive actions.
• Passive action summaries without executable payloads.
• Image placeholders and visual geometry when available.
• Link annotations and typed form fields when available.
• A source-neutral normalized-document-to-PDF projection with page, asset, link, and form policies plus merged conversion evidence.

Boundaries

• Reader adapter configuration belongs here.
• PDF parsing, logical readback, generation, and safety behavior belongs in OfficeIMO.Pdf.
• Shared extraction contracts belong in OfficeIMO.Reader.Core.
• This package maps between those two owners; source-format packages continue to own their normalization rules and do not gain a second PDF engine here.

Targets and license

• Targets: netstandard2.0, net8.0, net10.0.
• License: MIT.

Dependency footprint

• External: None beyond the dependencies of its OfficeIMO format packages.
• OfficeIMO: OfficeIMO.Reader.Core, OfficeIMO.Core, and the first-party OfficeIMO.Pdf engine own normalized content, raster compatibility, PDF parsing/generation, assets, and diagnostics.

See the complete OfficeIMO package map for related formats and conversion paths.