ZeroDep.Color 2.1.0

Zero External Dependencies. Pure PDF Processing.

A 100% dependency-free .NET engine for PDF structural analysis.

ZeroDep reads PDF files directly from bytes using only the .NET Base Class Library — no iText, no Pdfium, no SkiaSharp, no native binaries, no transitive packages. It extracts the structure of a document — image resolution, text and OCR layers, interactive forms, encryption metadata — and emits a typed, versioned JSON graph. It is built for document-processing pipelines: ingestion, archive validation, compliance checks, and large-corpus analysis.

The guiding principle is "analyze, don't render." Almost everything that forces a normal PDF stack to pull in a native dependency is a rendering concern (rasterizing pages, decoding JPEG/JBIG2 pixels, hinting glyph outlines). By restricting itself to structural analysis, ZeroDep keeps the zero-dependency promise while still answering the questions that matter for document workflows.

Why ZeroDep

• Zero supply-chain surface. One managed assembly. No native assets, no RID-specific builds, no third-party CVEs to track. Trivial to vendor, audit, and deploy.
• Broad reach. Multi-targets netstandard2.0 (so it runs on .NET Framework 4.6.1+) alongside modern net8.0 and net10.0.
• Deterministic and inspectable. Pure managed code, stream-based and memory-conscious. The same bytes always produce the same typed result.
• Safe by default. Corrupted files are rejected with a structured reason rather than silently producing plausible-but-wrong data. Encryption and authentication failures are structured results, not crashes.

Features

Scope: analyze, don't render

Install

dotnet add package ZeroDep

<PackageReference Include="ZeroDep" Version="1.0.0" />

Quick start

The entry point is the static PdfAnalyzer in the ZeroDep namespace. Every method takes a readable Stream and an optional password.

Analyze a whole document

using ZeroDep;
using ZeroDep.Abstractions;

using FileStream pdf = File.OpenRead("invoice.pdf");
DocumentAnalysis result = PdfAnalyzer.Analyze(pdf);

if (result.Status == DocumentStatus.Rejected)
{
    Console.WriteLine($"Rejected: {result.Rejection!.Reason}");
    return;
}

Console.WriteLine($"Pages: {result.PageCount}");
Console.WriteLine($"Encrypted: {result.Security.IsEncrypted} ({result.Security.Algorithm})");
Console.WriteLine($"Images: {result.Images.Count}, text runs: {result.TextRuns.Count}");
Console.WriteLine($"Form fields: {result.Form.Fields.Count}");

Extract text (including the OCR layer)

using FileStream pdf = File.OpenRead("scanned.pdf");

foreach (TextRunInfo run in PdfAnalyzer.ExtractText(pdf))
{
    string layer = run.IsOcrLayer ? "[ocr]" : "";
    Console.WriteLine($"p{run.PageIndex} ({run.X:F0},{run.Y:F0}) {layer} {run.Text}");
}

// or a simple line-grouped plain-text rendering:
string text = PdfAnalyzer.ExtractPlainText(File.OpenRead("scanned.pdf"));

Flag low-resolution images

using FileStream pdf = File.OpenRead("archive-scan.pdf");

foreach (ImageDpiInfo image in PdfAnalyzer.AnalyzeImageDpi(pdf, dpiThreshold: 150))
{
    if (image.IsBelowThreshold && image.PageAreaFraction >= 0.5)
    {
        Console.WriteLine($"Low-quality scan on page {image.PageIndex}: {image.EffectiveDpi:F0} DPI");
    }
}

Read interactive form fields

using FileStream pdf = File.OpenRead("sf1449.pdf");
AcroFormReport form = PdfAnalyzer.ExtractForm(pdf);

foreach (FormFieldInfo field in form.Fields)
{
    string value = field.IsChecked is bool b ? (b ? "[X]" : "[ ]") : field.Value ?? "";
    Console.WriteLine($"{field.FullyQualifiedName} = {value}");
}

Open an encrypted document

// Supplied password, or null for the empty/default user password.
DocumentAnalysis result = PdfAnalyzer.Analyze(File.OpenRead("secure.pdf"), password: "secret");

Emit the JSON schema

string json = PdfAnalyzer.ToJson(File.OpenRead("invoice.pdf"), indent: true);
File.WriteAllText("invoice.json", json);

Decode a JPEG to pixels

using ZeroDep.Filters;

byte[] jpeg = File.ReadAllBytes("photo.jpg");   // or a /DCTDecode image stream

JpegMetadata meta = JpegReader.ReadMetadata(jpeg);    // dimensions, mode, components — no pixel decode
Console.WriteLine($"{meta.Width}x{meta.Height}, {meta.Mode}");

RasterImage image = JpegDecoder.Decode(jpeg);   // baseline, progressive, or CMYK/YCCK → RGB/grayscale
// image.Samples is row-major, interleaved; image.Components is 1 (gray) or 3 (RGB)

Rasterize a glyph from an embedded font

using ZeroDep.Fonts;
using ZeroDep.Raster;

byte[] program = /* an embedded /FontFile, /FontFile2, or /FontFile3 stream */;

FontProgram font = FontProgram.Load(program);   // sniffs TrueType / CFF / Type 1
int gid = font.MapCodepointToGlyph('A');        // (TrueType cmap; CID fonts use GlyphIdForCid)

GlyphOutline outline = font.GetGlyph(gid);       // cubic/quadratic contours, font units
GlyphBitmap bmp = GlyphRenderer.Render(font, gid, pixelSize: 48);   // 8-bit AA coverage
// bmp.Coverage is row-major Width*Height; bmp.Left/Top are the pen-relative placement

Recover text from a scanned page (OCR)

ZeroDep.Ocr is an opt-in, dependency-free package. You supply the OCR engine by implementing IOcrEngine (over Tesseract, PaddleOCR, a cloud API — your choice); ZeroDep decodes the page image, drives your engine, and merges the result as OcrGenerated text.

using ZeroDep;
using ZeroDep.Abstractions;
using ZeroDep.Ocr;

sealed class MyEngine : IOcrEngine
{
    public OcrResult Recognize(DecodedImage image, OcrOptions options) => /* call your OCR engine */;
}

using var pdf = File.OpenRead("scanned.pdf");
DocumentAnalysis analysis = PdfAnalyzer.Analyze(pdf);

pdf.Position = 0;
IReadOnlyList<PdfImageInfo> images = PdfAnalyzer.ExtractImages(pdf);

DocumentAnalysis withOcr = OcrProcessor.Augment(analysis, images, new MyEngine(), new OcrOptions { MinConfidence = 0.6 });

foreach (TextRunInfo run in withOcr.TextRuns)
{
    if (run.Source == TextSource.OcrGenerated)
        Console.WriteLine($"[ocr {run.Confidence:P0}] {run.Text}");   // tagged, never mistaken for embedded text
}

OCR accuracy — measured, not asserted

OCR ships against a measured accuracy benchmark, not on faith. The reference adapter was scored against two independent labeled sets of real multilingual form documents — one spanning five European languages, one an independent set of noisy low-resolution scans — using length-weighted Character Error Rate (CER) after Unicode/whitespace/case normalization.

The key property is calibrated confidence: on every set, error falls monotonically as the engine's reported confidence rises — so at confidence ≥ 0.9 the reference adapter is 95–99% character-accurate, and lower-confidence output is honestly flagged rather than passed off as correct. Because confidence is surfaced on every recovered run, you can threshold on it with trust.

Accuracy depends on the engine you plug in, which is the point of a pluggable IOcrEngine. The default reference adapter targets Latin-script scans; for dense CJK (Chinese, Japanese) a second reference adapter cuts the character error by roughly half to two-thirds on the same pages — so you pick the engine that fits your documents without touching the dependency-free core. Both reference adapters reach their engine out-of-process (a CLI binary / a worker process), so neither bundles native binaries.

Command-line tool

A thin, zero-dependency console front-end ships alongside the library.

# Analyze one file (human-readable, or --json)
zerodep document.pdf
zerodep document.pdf --json --password=secret

# Batch-process a directory tree (recursive)
zerodep batch ./corpus --output=./batch-out

The batch verb is resumable and parallel. It writes three things under the output folder: a resumable ledger, optional per-file JSON (--no-perfile to skip), and a publishable aggregate.json containing aggregates and counts only — no file names, extracted text, or field values. Useful flags: --concurrency=N, --threshold=N, --no-resume, --no-perfile.

Batch from code

using ZeroDep.Batch;

var summary = await new BatchProcessor().RunAsync(new BatchOptions
{
    InputDirectory = "./corpus",
    OutputDirectory = "./batch-out",
});

Console.WriteLine($"Processed {summary.Total}, rejected {summary.Rejected}");
foreach (var category in summary.Statistics.Categories)
{
    Console.WriteLine($"  {category.Category}: {category.Count} ({category.Percent}%)");
}

Each document is classified into a content-free, structural category — DigitalText, ScannedImageOnly, ScannedWithOcr, FormBased, Mixed, EncryptedUnreadable, or Rejected — derived only from how the file is built, never from what it says.

Supported frameworks

Crypto uses the in-box System.Security.Cryptography (AES, MD5, SHA-2 ship with every target); RC4 is implemented in-house. Building from source requires the .NET SDK 10.0.300+.

Output schema (overview)

PdfAnalyzer.ToJson emits a stable, versioned envelope. Top-level status lets a pipeline branch in a single read; every page-level array is always present (possibly empty); undecodable assets are reported with flags rather than dropped silently.

{
  "schemaVersion": "1.2",
  "status": "Processed",            // Processed | Rejected
  "rejection": null,                // { "reason": "TruncatedStream", "detail": "..." } when Rejected
  "pageCount": 3,
  "imageAreaFraction": 0.94,
  "security": { "isEncrypted": true, "algorithm": "AES-256", "authentication": "UserPassword", "...": "..." },
  "images":   [ { "page": 0, "effectiveDpi": 200.0, "belowThreshold": false, "pageAreaFraction": 0.94 } ],
  "textRuns": [ { "page": 0, "text": "Invoice", "renderMode": 0, "isOcrLayer": false } ],
  "form":     { "hasAcroForm": true, "hasXfa": false, "fields": [ /* ... */ ] }
}

Architecture

ZeroDep is a layered pipeline; each layer depends only on the layers below it:

bytes → lexer → object resolver → security/decryption → filters
      → document model → content interpreter → feature engines → typed result → JSON

Roadmap

Each release is additive and keeps the shipped public API backward-compatible. The core engine stays 100% dependency-free — only the OCR stage introduces an opt-in dependency, isolated in its own package.

Contributing

Issues and pull requests are welcome. Please run dotnet test ZeroDep.slnx -c Release before submitting; all targets must build clean (warnings are treated as errors).

License

Licensed under the Apache License 2.0.