JetsonPDF.Reader 1.1.0

JetsonPDF.Reader

Headless, code-first reader for PDF files. Parses bytes that conform to ISO 32000-2 (PDF 2.0) into a navigable in-memory tree of immutable DTOs rooted on ReadDocument. No native dependencies, no JIT codegen, no STA threads; runs on net8.0, netstandard2.0, and net462.

using JetsonPDF.Reading;

ReadDocument doc = Reader.Load("input.pdf");

Console.WriteLine($"{doc.Pages.Count} pages, PDF {doc.PdfVersion}");
foreach (ReadPage page in doc.Pages)
{
    Console.WriteLine($"  page {page.MediaBox.Width}x{page.MediaBox.Height}");
    foreach (PageItem item in page.Items)
    {
        // PageTextItem / PagePathItem / PageImageItem / PageInlineImageItem
        // / PageShadingItem / PageFormXObjectItem
        Console.WriteLine($"    {item.GetType().Name}");
    }
    foreach (PageAnnotation anno in page.Annotations)
    {
        Console.WriteLine($"    annot {anno.GetType().Name} @ {anno.X},{anno.Y}");
    }
}

Contents

• Overview
• Quick start
• Core concepts
• Loading a document
• File structure and encryption
• Pages and content streams
• Raw operator stream
• Colors and shading
• Fonts and text
• Filters
• Annotations
• Forms
• Document metadata
• Structure tree
• Measurement and viewports
• Conformance detection
• Limitations
• Targets
• License

Overview

JetsonPDF.Reader is the inverse of JetsonPDF.Writer. Where the writer assembles an object graph and emits PDF bytes, the reader takes PDF bytes and hands back a ReadDocument that downstream tooling (the WPF XAML converter, the OpenSilver converter, the TIFF rasteriser, custom code) can walk without ever touching the underlying COS layer.

The shape mirrors the writer surface — every writer DTO has a matching ReadX (or PageX for content-stream items). Round-trip tooling can read a PDF, mutate the model, and re-emit through JetsonPDF.Writer without shifting domain types.

Decoding is lazy where it matters: content streams interpret on first access of ReadPage.Items; annotations parse on first access of ReadPage.Annotations; tiling patterns, viewports, associated files, and piece info all cache behind their property accessors. The cost of opening a 1000-page PDF is the file scan plus an xref/object-stream pass — page contents are touched only when you ask.

Quick start

Add a project reference to JetsonPDF.Reader and a using JetsonPDF.Reading;. Open from a path, a Stream, or a byte[], with an optional password for encrypted files:

using JetsonPDF.Reading;

ReadDocument fromPath   = Reader.Load("document.pdf");
ReadDocument fromStream = Reader.Load(File.OpenRead("document.pdf"));
ReadDocument fromBytes  = Reader.Load(File.ReadAllBytes("document.pdf"));

ReadDocument encrypted  = Reader.Load("locked.pdf", password: "hunter2");
if (!encrypted.EncryptionAuthenticated)
    throw new InvalidOperationException("Wrong password.");

Stream overloads buffer the input into memory; PDF requires random access, so a non-seekable Stream is copied into a MemoryStream first.

Core concepts

Every public DTO is immutable post-construction; mutate by reading, projecting into a writer-side Document, and emitting fresh bytes.

Loading a document

// Path / stream / byte[], with optional password.
public static ReadDocument Load(string path);
public static ReadDocument Load(string path, string password);
public static ReadDocument Load(Stream input);
public static ReadDocument Load(Stream input, string password);
public static ReadDocument Load(byte[] data);
public static ReadDocument Load(byte[] data, string password);

The reader internally caches WinAnsi (Windows-1252) registration through Encoding.RegisterProvider on first call, so the same process can open files from any thread without re-registering.

File structure and encryption

PDF's binary layout is opaque to the consumer surface — ReadDocument already resolved every cross-reference. The file-structure features the reader handles transparently:

• Classic xref tables and xref streams (§7.5.4 / §7.5.8) — both layouts resolve to the same indirect-object lookup.
• Object streams (§7.5.7) — compressed indirect objects unpacked on demand.
• Incremental updates — multiple startxref sections walked back to the oldest generation; the most recent write wins.
• Linearized layouts ("Fast Web View", Annex F) — the linearization dict, two xrefs, and the hint stream are all recognised and traversed.
• Encrypted documents — RC4-40, RC4-128, AES-128, and AES-256 (/V 4 and /V 5 security handlers). Supply a password to Reader.Load(...):

ReadDocument doc = Reader.Load("locked.pdf", password: "secret");
if (doc.IsEncrypted && !doc.EncryptionAuthenticated)
{
    // Wrong password; content streams will return their encrypted bytes.
}

ReadDocument.IsEncrypted reports whether the trailer declared /Encrypt; EncryptionAuthenticated reports whether the supplied password unlocked the file. Both must be true before content reads will return cleartext.

Pages and content streams

Pages are exposed through ReadDocument.Pages. Each ReadPage has a MediaBox and a lazy Items collection of PageItems extracted from the page's content stream.

foreach (ReadPage page in doc.Pages)
{
    foreach (PageItem item in page.Items)
    {
        switch (item)
        {
            case PageTextItem text:
                Console.WriteLine($"text {text.X},{text.Y}: \"{text.Text}\" " +
                                  $"({text.FontResource} {text.FontSize:0.#}pt, " +
                                  $"argb {text.FillArgb:X8})");
                break;
            case PagePathItem path:
                Console.WriteLine($"path \"{path.PathData}\" fill={path.DoFill} stroke={path.DoStroke}");
                break;
            case PageImageItem img:
                Console.WriteLine($"image {img.XObjectResource} {img.Width}x{img.Height}");
                break;
            case PageInlineImageItem inline:
                Console.WriteLine($"inline {inline.PixelWidth}x{inline.PixelHeight} " +
                                  $"{inline.ColorSpaceName} bpc={inline.BitsPerComponent}");
                break;
            case PageShadingItem sh:
                Console.WriteLine($"shading radial={sh.IsRadial} stops={sh.Stops.Count}");
                break;
        }
    }
}

Every PageItem also carries ClipPathData (current clip geometry in WPF mini-language, null if none), ClipEvenOdd, and BlendMode for the operator graphics-state in force at draw time.

// Keep Form XObject boundaries instead of flattening — useful for round-trip echo.
foreach (var item in page.ItemsPreservingForms)
{
    if (item is PageFormXObjectItem form)
        Console.WriteLine($"form {form.XObjectResource}");
}

Page-level extras:

page.Warnings           // soft errors from the content interpreter
page.Annotations        // /Annots overlays, see below
page.Viewports          // §12.10 viewports (rare)
page.AssociatedFiles    // §14.13 page-level /AF
page.PieceInfo          // §14.5 application piece info
page.TilingPatterns     // /Resources /Pattern entries with PatternType 1

Raw operator stream

For round-trip workflows that need every CTM, every q/Q, every marked-content scope, bypass Items and read RawOperators instead:

foreach (PdfOperator op in page.RawOperators)
{
    if (op.Op == "Tj" && op.TryGetStringBytes(0, out var bytes))
        Console.WriteLine($"Tj: {bytes.Length} encoded bytes");
}

PdfOperator.Op is the operator keyword, Operands is opaque (typed helpers TryGetNumber / TryGetName / TryGetStringBytes are provided). Hand the operator back to JetsonPDF.Page.EmitOperator(...) for verbatim re-emit — Tm/CTM matrices and graphics-state nesting are preserved without the interpreter folding them into PageItems.

Colors and shading

The content interpreter resolves colour into packed 0xAARRGGBB on every PagePathItem, PageTextItem, and PageShadingItem. The colour spaces the reader resolves before producing those packed values:

• Device — DeviceGray, DeviceRGB, DeviceCMYK.
• CIE-based — CalGray, CalRGB, Lab (honest CIE math).
• ICCBased — single- and multi-component ICC profiles.
• Indexed — palette-lookup through the base space.
• Separation — single-colorant with the PdfFunction evaluator applied.
• DeviceN / NChannel — multi-colorant with tint transform.
• Pattern — both tiling (uncoloured + coloured) and shading variants.

PdfFunction Types 0 (sampled), 2 (exponential interpolation), 3 (stitching), and 4 (PostScript) all evaluate end-to-end. Functions on shading dicts, tint transforms, and stitched gradient stops all use the same evaluator.

foreach (var item in page.Items.OfType<PageShadingItem>())
{
    if (item.IsRadial)
        Console.WriteLine($"radial @ ({item.RadialCenterX}, {item.RadialCenterY}) r={item.RadialRadius}");
    else
        Console.WriteLine($"axial {item.LinearStartX},{item.LinearStartY} -> {item.LinearEndX},{item.LinearEndY}");

    foreach (var (offset, argb) in item.Stops)
        Console.WriteLine($"  stop {offset:0.000} {argb:X8}");
}

Shading types 1 (function-based), 2 (axial), and 3 (radial) collapse to PageShadingItem. Mesh shadings — types 4/5 (Gouraud triangles), 6 (Coons patches), 7 (tensor-product patches) — decode to triangle / patch lists behind the scenes; the interpreter folds them into stops where it can.

Fonts and text

PageTextItem.Text is already Unicode — the font's encoding has been applied. The strategies the reader picks from per font:

• Type 1 simple fonts with /Encoding /WinAnsiEncoding, /MacRomanEncoding, /Differences mapped through Adobe Glyph List, or /ToUnicode when present.
• TrueType / OpenType simple fonts with the same encoding routes; CID-keyed composite fonts use Identity-H or CMap.
• Type 3 procedural fonts (writer-side feature) — /ToUnicode is preferred over AGL fallback so round-trip glyph names survive.
• Standard 14 fonts use Adobe Core AFM metrics for ascent / descent / cap-height / glyph widths.
• CID Identity-H composite fonts with stripped Unicode cmaps recover through a synthesised cmap built from the font's /CIDSystemInfo plus /ToUnicode.

PageTextItem.RawBytes and PageTextItem.TJElements carry the source operator's encoded bytes so callers can re-emit the run verbatim under the original font, bypassing decode-and-re-encode roundtrips that would lose glyph ordering for stripped CID fonts.

Vertical writing mode, /Span /ActualText marked content, and ToUnicode cluster decoding (multi-code-unit glyph clusters via GlyphClusterLengths) all flow through to the produced text.

Filters

Every standard PDF filter is supported on the stream-decoding path:

Inline images (BI / ID / EI) feed the same filter pipeline through PageInlineImageItem.Filters + EncodedData.

Annotations

ReadPage.Annotations parses the /Annots array into typed subclasses of PageAnnotation. Each annotation reports its rect (X, Y, Width, Height), Contents text (with fallback to a linked /Popup), and any AssociatedFiles.

Geometric markup annotations also pick up an inline /Measure dict (GeometricAnnotation.Measure) when present.

foreach (var anno in page.Annotations)
{
    switch (anno)
    {
        case LinkAnnotation link:
            Console.WriteLine($"link {link.Uri ?? link.InternalDestination}");
            break;
        case TextMarkupAnnotation tm:
            Console.WriteLine($"{tm.Kind} {tm.Quads.Count} quads argb={tm.Argb:X8}");
            break;
        case FileAttachmentAnnotation fa:
            File.WriteAllBytes(fa.FileName, fa.FileBytes);
            break;
        case WidgetAnnotation w:
            Console.WriteLine($"widget {w.FieldName} ({w.FieldType}) = {w.FieldValue}");
            break;
    }
}

Forms

AcroForm widgets land on WidgetAnnotation. Field-related state is inheritance-resolved up the /Parent chain per §12.7.4.2 before the widget is constructed, so a widget directly exposes its effective values:

var widgets = doc.Pages.SelectMany(p => p.Annotations).OfType<WidgetAnnotation>();

foreach (var w in widgets)
{
    Console.WriteLine($"{w.FieldName} ({w.FieldType}) = {w.FieldValue}");
    if (w.IsCheckBox)    Console.WriteLine($"  checked={w.IsChecked}");
    if (w.IsRadioButton) Console.WriteLine($"  appearance state={w.AppearanceState}");
    if (w.IsComboBox || w.IsListBox)
    {
        foreach (var (export, display) in w.Options)
            Console.WriteLine($"  option {export} -> {display}");
        Console.WriteLine($"  selected values: {string.Join(", ", w.SelectedValues)}");
    }
    if (w.IsMultiline) Console.WriteLine($"  multiline (max length {w.MaxLength})");

    if (w.Action is UriAction uri)        Console.WriteLine($"  action URI -> {uri.Uri}");
    if (w.Action is ResetFormAction rf)   Console.WriteLine($"  action ResetForm");
    if (w.Action is SubmitFormAction sf)  Console.WriteLine($"  action SubmitForm -> {sf.Url}");
}

Widget field types covered: Tx (text), Btn (push / check / radio), Ch (combo / list), Sig (signature), plus JetsonPDF's private /JetsonPDFBarcode round-trip for barcode fields (surfaced through WidgetAnnotation.Barcode as ReadBarcodeMetadata).

Decoded /Ff flag bits are reported through named properties — IsReadOnly, IsRequired, IsMultiline, IsPassword, IsRadioButton, IsPushButton, IsComboBox, IsEditableChoice, IsMultiSelect, IsFileSelect, DoNotSpellCheck, DoNotScroll, IsComb, IsRichText, RadiosInUnison, IsSorted, CommitOnSelChange.

Additional actions (/AA) are decoded into WidgetAnnotation.AdditionalActions, with named slots for Keystroke / Format / Validate / Calculate plus the mouse triggers Enter / Exit / Down / Up and the focus triggers Fo / Bl:

if (w.AdditionalActions is { } aa)
{
    if (aa.Keystroke is JavaScriptAction k) Console.WriteLine($"  /AA /K  -> {k.Script}");
    if (aa.Format    is JavaScriptAction f) Console.WriteLine($"  /AA /F  -> {f.Script}");
    if (aa.Calculate is JavaScriptAction c) Console.WriteLine($"  /AA /C  -> {c.Script}");
}

Document-level form pieces live on ReadDocument:

doc.CalculationOrder        // /AcroForm /CO — fully-qualified field names
doc.Signatures              // signed /FT /Sig fields (regular + DocTimeStamp)
doc.DocMdpPermission        // 1 / 2 / 3 from /Perms /DocMDP
doc.FieldMdpRestriction     // FieldMDP transform on certification signature
doc.SecurityStore           // /DSS + /VRI for PAdES-LT / LTA validation

Signature widgets also surface SignatureSeedValue (/SV) and SignatureLock (/Lock) constraints:

foreach (var w in widgets.Where(w => w.FieldType == "Sig"))
{
    if (w.SignatureSeedValue is { } sv)
        Console.WriteLine($"  filter={sv.Filter} subfilters={string.Join(",", sv.SubFilters)}");
    if (w.SignatureLock is { } lck)
        Console.WriteLine($"  lock action={lck.Action} fields={string.Join(",", lck.Fields)}");
}

Document metadata

ReadDocument lifts every catalog-level entry the writer can emit:

foreach (var item in doc.Outlines)
    PrintOutline(item, depth: 0);

string label = doc.GetPageLabel(0);          // "i", "ii", "1", "A-1", ...
var dest     = doc.NamedDestinations["intro"];

if (doc.ViewerPreferences is { } vp)
    Console.WriteLine($"display doc title? {vp.DisplayDocTitle}");

Destination carries the resolved page index plus the explicit-destination type (Xyz, Fit, FitH, FitR, ...) so consumers don't have to re-walk /Kids.

Structure tree

Tagged-PDF documents decode into ReadDocument.StructureTree, which is either null (no tagged structure) or a ReadStructureTree with the nested element hierarchy plus the document-level RoleMap and ClassMap.

if (doc.StructureTree is { } tree)
{
    foreach (var root in tree.Roots)
        Visit(root, depth: 0);

    foreach (var (custom, standard) in tree.RoleMap)
        Console.WriteLine($"role {custom} -> {standard}");
}

void Visit(ReadStructureElement el, int depth)
{
    Console.WriteLine($"{new string(' ', depth * 2)}{el.StructureType} {el.Title}");
    foreach (var child in el.Children) Visit(child, depth + 1);
}

Each ReadStructureElement exposes StructureType (the /S name), Alt / ActualText / ExpansionAbbreviation / Language / Title / Id, marked-content IDs, OBJR references back to annotations (decoded to (pageIndex, annotationIndex) tuples), and a list of nested Children. Class names on /C resolve through ClassMap into shared ReadStructureAttributes bundles.

Measurement and viewports

Measurement-aware PDFs (engineering drawings, geospatial maps) decode their inline /Measure dicts and /VP viewport arrays:

foreach (var page in doc.Pages)
foreach (var vp in page.Viewports)
{
    Console.WriteLine($"viewport {vp.Name} bbox={vp.BBox}");
    if (vp.Measure is ReadRectilinearMeasure rl)
        Console.WriteLine($"  rectilinear scale {rl.ScaleRatio}");
    else if (vp.Measure is ReadGeospatialMeasure geo)
        Console.WriteLine($"  geospatial gcs={geo.Gcs?.EpsgCode}");
}

// Inline Measure on a geometric annotation.
foreach (var anno in page.Annotations.OfType<GeometricAnnotation>())
    if (anno.Measure is ReadRectilinearMeasure rl)
        Console.WriteLine($"  inline measure {rl.ScaleRatio}");

ReadNumberFormat chains (XAxis, YAxis, Distance, Area, Angle, Slope) are exposed raw so callers can format compound units (e.g. "5' 6 1/2"") in whatever convention they like. ReadCoordinateSystem carries either an EPSG code or a WKT string.

Conformance detection

ReadDocument.Conformance is a flags enum (Conformance.None when no declaration is present). The reader detects PDF/A-1b, PDF/A-2 a/u/b, PDF/A-3 a/u/b, PDF/UA-1, and PDF/UA-2 by parsing pdfaid:part / pdfaid:conformance / pdfuaid:part out of the XMP packet — the catalog flag is declarative, the reader does not validate content against the profile's rules.

if ((doc.Conformance & Conformance.PdfA2u) != 0)
    Console.WriteLine("Declares PDF/A-2u.");

foreach (var oi in doc.OutputIntents)
    Console.WriteLine($"output intent {oi.Subtype} {oi.OutputConditionIdentifier}");

For actual conformance checking (rule codes PDFA1x, PDFA2x, PDFA3x, PDFUA1, PDFUA2), use the writer-side validator: it walks a built JetsonPDF.Document and reports violations. The reader doesn't ship its own validator because the rules that matter are about the bytes the writer produced, not the bytes the reader parsed.

Limitations

• JPX is passthrough. JpxFilter returns the original JPEG 2000 bitstream and extracts JP2 ihdr metadata (width / height / components / bit-depth). Decoding the codestream is left to downstream consumers — the WPF emitter writes it out as a .jp2 file and lets the OS image stack handle it.
• JBIG2 still has open corners. Symbol dictionaries with variable-length inline Huffman code-lengths (§7.4.3.2) are not yet supported and surface a clear error path. Generic regions, text regions (arithmetic and Huffman), refinement, pattern dicts, and halftones all decode.
• DCT (JPEG) is passthrough. PageImageItems reference the JPEG XObject by resource name; the reader hands consumers the encoded bytes and lets a JPEG decoder elsewhere produce pixels.
• Multimedia and 3D annotations are not surfaced. Movie, Screen, 3D, RichMedia, and TrapNet subtypes return null from the annotation builder. They're rare in non-multimedia workflows and the underlying payloads (Flash, U3D, RichMedia) need runtimes the reader doesn't host.
• Mesh-shading tessellation is incomplete. Types 4/5 decode to triangles; types 6/7 decode to patch lists with control points + corner colours. Bézier subdivision tessellation for types 6/7 is deferred — consumers that want pixel output need to tessellate themselves.
• No conformance validation on the read side. ReadDocument.Conformance reports the declaration only. Use the writer's Document.Validate() on a constructed document if you need rule-level checking.
• Reader is read-only. Mutating a document means projecting the ReadDocument into a writer-side Document and emitting fresh bytes. For operator-level edits, RawOperators + Page.EmitOperator round-trip every operator without re-interpretation.
• Non-seekable streams are buffered. The PDF random-access model requires it; the Stream overloads copy into a MemoryStream before parsing. Pass a byte[] directly to skip the copy.

Targets

• net8.0
• netstandard2.0
• net462

License

MIT.