JetsonPDF.Tiff 1.1.0

JetsonPDF.Tiff

Pure-managed TIFF reader and writer for .NET. No GDI+, no System.Drawing, no native dependencies — just decompressed RGBA8888 pixels and a small writer that emits baseline TIFF strips. Built originally so JetsonPDF.OpenSilver could display .tif files inside a WebAssembly browser app (where neither GDI+ nor <img src="*.tif"> works), but the surface is general-purpose — any .NET app that needs to read or write TIFF frames without a native codec can use it directly.

using JetsonPDF.Tiff;

// Read: decode every page, hand the first one to anything that takes PNG.
TiffImage image = TiffImage.Decode(File.ReadAllBytes("scan.tif"));
File.WriteAllBytes("page0.png", image.Frames[0].EncodePng());

// Write: encode RGBA buffers back out as multi-page TIFF.
byte[] tiffBytes = TiffWriter.Encode(
    image.Frames.Select(TiffEncodeFrame.From),
    new TiffWriteOptions { Compression = TiffCompression.Deflate });
File.WriteAllBytes("round-tripped.tif", tiffBytes);

Contents

• Overview
• Quick start
• Reading TIFFs
• Writing TIFFs
• Compression matrix
• Photometric and bit-depth coverage
• Predictor support
• Interop with other JetsonPDF assemblies
• Out of scope
• Limitations
• Targets
• License

Overview

JetsonPDF.Tiff is a baseline TIFF (Rev 6) implementation written entirely in managed C#. The reader produces row-major RGBA8888 frames; the writer accepts the same RGBA layout and emits a strip-based, little-endian (II) TIFF. Decoding is eager — TiffImage.Decode reads the whole file and decodes every IFD up front, because TIFF is offset-driven random access and not stream- friendly by nature.

The library reuses the heavy-lifting filter implementations from JetsonPDF.Reader via InternalsVisibleTo:

• CCITT (CcittFaxFilter) for compression codes 2 / 3 / 4
• LZW (LzwFilter) for compression code 5
• Flate / Deflate for codes 8 and 32946

A small managed PNG encoder (PngEncoder) ships in the assembly so any frame can be converted to a standalone PNG without taking on a third-party image dependency — TiffFrame.EncodePng() and TiffFrame.ToDataUri() are how the OpenSilver TiffViewer puts a .tif on a web page.

Quick start

using JetsonPDF.Tiff;

// Decode from bytes (e.g. an in-memory blob, an HTTP response, etc.).
TiffImage img = TiffImage.Decode(bytes);

// Or from a Stream — TIFF needs random access, so the stream is copied to
// memory up front. The stream is NOT disposed by Decode.
using FileStream fs = File.OpenRead("scan.tif");
TiffImage img2 = TiffImage.Decode(fs);

Console.WriteLine($"{img.Frames.Count} page(s)");
foreach (TiffFrame frame in img.Frames)
{
    Console.WriteLine(
        $"  {frame.Width}x{frame.Height} " +
        $"{frame.Photometric} compression={frame.Compression} " +
        $"{frame.BitsPerSample} bpp x {frame.SamplesPerPixel} samples");
}

// Hand a frame to any consumer that takes PNG.
byte[] png = img.Frames[0].EncodePng();

Reading TIFFs

Decoding

TiffImage TiffImage.Decode(byte[] data);
TiffImage TiffImage.Decode(Stream stream);

Both overloads return a TiffImage whose Frames collection has been populated eagerly — one TiffFrame per IFD, in source order.

Decode can throw:

TiffFrame

Each decoded page exposes:

Compression, Photometric, BitsPerSample, and SamplesPerPixel describe the source layout — they're not what the writer will produce if you re- encode. After decode, pixels are always in 8-bit RGBA regardless of the source bit depth or photometric interpretation.

Encoding frames to PNG / data URI

byte[] EncodePng();      // RGBA -> PNG. Throws if this frame is a JPEG passthrough.
byte[] EncodeImage();    // PNG, or the original JPEG bytes if passthrough.
string ToDataUri();      // "data:image/png;base64,..." or "data:image/jpeg;base64,..."

EncodePng() produces a standalone PNG with full RGBA. EncodeImage() is the JPEG-aware variant — for compression-7 passthrough frames it returns the original JPEG bytes (no re-encode), and for everything else it produces PNG. ToDataUri() wraps the bytes in a data: URI suitable for an HTML <img> tag or an OpenSilver BitmapImage. Building the URI involves a base64 encode of the payload, so cache the result if you call it repeatedly.

Writing TIFFs

public static class TiffWriter
{
    public static byte[] Encode(
        IEnumerable<TiffEncodeFrame> frames,
        TiffWriteOptions? options = null,
        Action<int>? onFrameEncoded = null);

    public static void Encode(
        Stream output,
        IEnumerable<TiffEncodeFrame> frames,
        TiffWriteOptions? options = null,
        Action<int>? onFrameEncoded = null);

    public static byte[] Encode(
        int width, int height, byte[] rgba8888,
        TiffWriteOptions? options = null);
}

The byte-returning overload is the primary one — it does the full encode in memory and hands back the result. The Stream overload is a thin wrapper that calls the byte overload and writes the result to the supplied stream (the stream is not closed). The (width, height, rgba) overload is a convenience for the common "one frame, no options" case.

onFrameEncoded fires with a 1-based frame index after each frame's strips have been compressed — useful for driving a progress bar on a multi-page encode.

TiffEncodeFrame

One page of input. Pixels are row-major RGBA8888 — the same shape TiffFrame.Rgba8888 produces, so an encoder → decoder round trip is trivially symmetric.

new TiffEncodeFrame(int width, int height, byte[] rgba8888);
TiffEncodeFrame.From(TiffFrame frame);  // convenience: build from a decoded frame

The constructor validates that rgba8888.Length == width * height * 4. From throws if the source TiffFrame is a JPEG passthrough (no RGBA payload to hand to the encoder).

TiffWriteOptions

TiffEncodePixelFormat

The pixel-format choice is independent of the compression choice — any of the four pixel formats can be combined with any supported write compression.

Multi-frame output

TiffWriter.Encode takes an IEnumerable<TiffEncodeFrame> and emits a single TIFF file whose IFDs are chained via the next-IFD pointer in source order. Strip data for every frame is written first, then each frame's IFD payloads and the IFD itself; the chain pointers are patched at the end. The result is a single file that opens as a multi-page document in any viewer that supports baseline TIFF.

var frames = new[]
{
    new TiffEncodeFrame(w, h, page0Rgba),
    new TiffEncodeFrame(w, h, page1Rgba),
    new TiffEncodeFrame(w, h, page2Rgba),
};

byte[] multiPage = TiffWriter.Encode(frames, new TiffWriteOptions
{
    Compression = TiffCompression.Deflate,
    PixelFormat = TiffEncodePixelFormat.Rgb,
    RowsPerStrip = 64,
});

Compression matrix

The reader is permissive (it handles every baseline strip compression and JPEG passthrough); the writer is intentionally narrow.

* Compression 7 is read as a single self-contained JPEG strip — the original JPEG bytes come back via TiffFrame.PassthroughJpeg. Split-JPEG frames using the JPEGTables tag (split tables / per-strip entropy coding) throw NotSupportedException.

Asking the writer for an unsupported compression throws NotSupportedException with a message listing the supported set:

TIFF writer does not yet support compression Lzw.
Supported: None, PackBits, Deflate, AdobeDeflate.

Photometric and bit-depth coverage

Supported bits-per-sample on read: 1, 2, 4, 8. Anything else (notably 16-bit and 32-bit / floating-point samples) throws.

Supported sample arrangements: chunky only. PlanarConfig = 2 (separate planes per sample) throws.

ExtraSamples is honoured for both unassociated (2) and associated / premultiplied (1) alpha — premultiplied alpha is un-premultiplied on the way to RGBA.

FillOrder = 2 (LSB-first bit order, common on CCITT fax data) is reversed byte-by-byte before decoding.

Predictor support

The writer does not emit a predictor (predictor = 1 is the default and isn't written). For files that compress well with Deflate + predictor 2, encoding through this library trades a bit of ratio for predictor-free output.

Interop with other JetsonPDF assemblies

Out of scope

The following are intentionally unsupported. The decoder throws NotSupportedException with an explanatory message when it encounters them, rather than producing wrong pixels:

• BigTIFF (8-byte offsets, magic 43 instead of 42).
• Tiled images (tag 322 TileWidth / 324 TileOffsets) — strip-based layouts only.
• 16-bit and 32-bit samples, including IEEE float — only 1 / 2 / 4 / 8 bpp.
• Planar configurations (PlanarConfig = 2) — chunky only.
• YCbCr (photometric 6), CIELab (photometric 8), TransparencyMask (photometric 4), and LogLuv (photometrics 32844 / 32845).
• Old-style JPEG (compression code 6) — the obsolete TIFF 6 JPEG mode.
• JPEG-in-TIFF with split JPEG tables (compression 7 with the JPEGTables tag) — only single-strip self-contained JPEG passthrough is supported.
• JBIG (compressions 34661 / 34715) and JPEG 2000-in-TIFF (33003 / 33005).
• Floating-point predictor (predictor 3).
• CCITT T.6 "uncompressed mode" (T6Options bit 1) — almost no encoders produce this; throws.
• GeoTIFF, EXIF, XMP, and other auxiliary metadata IFDs — the reader reads the baseline image IFDs and ignores extension tags.

Limitations

• Decode is eager. TiffImage.Decode reads the entire file and decodes every IFD up front; there is no lazy / on-demand frame path. TIFF needs random access across the whole file, so streamed decoding would buffer internally anyway. For huge multi-page documents where you only want one page, an external pre-split is still cheaper than feeding the whole file through this decoder.
• The writer is narrower than the reader. Encoding CCITT or LZW would duplicate codecs that mostly exist as legacy compatibility — for a modern general-purpose ratio use Deflate, and for a guaranteed-round-trip option use PackBits.
• CMYK → RGB is naive. Pure (1 - C)(1 - K) math, no ICC profile, no black-point compensation. Acceptable for display previews; not for colour- managed workflows.
• No metadata round-trip. Tags outside the baseline image-data set (XMP, EXIF, GeoTIFF, IPTC, custom IFDs) are read and discarded. The writer emits only the minimum required tags plus resolution.
• Resolution unit is fixed at inches (tag 296 = 2). Centimetre-unit output isn't exposed in TiffWriteOptions.

Targets

• net8.0
• netstandard2.0
• net462

License

MIT.