Meziantou.Framework.Imaging 1.0.0

Meziantou.Framework.Imaging

A fully managed, performance-oriented image library for .NET 10 and .NET 11: PNG, animated PNG (APNG), GIF, JPEG, WebP (still and animated, lossless and lossy), QOI, BMP, TGA, Netpbm (PBM/PGM/PPM/PAM), TIFF/BigTIFF and ICO/CUR decoding and encoding, animation-aware processing, and bounded-memory streaming.

• Static PNG, animated PNG (APNG), GIF, baseline/progressive JPEG, WebP (still and animated, lossless and lossy), QOI, BMP, TGA, Netpbm (PBM/PGM/PPM/PAM), TIFF/BigTIFF and ICO/CUR decoding; PNG, APNG, GIF, baseline JPEG, WebP (lossless and lossy, still and animated), QOI, BMP, TGA, Netpbm, TIFF/BigTIFF and ICO/CUR encoding (unsupported modes, such as arithmetic or CMYK JPEG, RLE BMP, 16-bit TGA color maps or LZW TIFF, are rejected explicitly)
• ImageCollection for the images that are not animation frames: TIFF document pages and icon/cursor representations, read and written one entry at a time
• Animation-aware model: every frame is a full-canvas displayed image with exact rational timing
• Six working pixel formats (Rgba32, Bgra32, Rgb24, Rgba64, Gray8, Gray16) with 16-bit precision preserved
• Crop, resize (alpha-aware, Contain/Cover/Stretch), rotate, auto-orient, flip, grayscale and convolution matrices (sharpen, blur, edge detection) applied to all frames
• Bounded-memory sequential readers and writers for long animations
• Explicit policies for alpha, precision, metadata and color-profile losses; configurable resource limits

This document is the user guide: it describes what the library guarantees to its callers. Every C# example below is compiled and run by the test suite.

Table of contents

• Quick start
• Design highlights
• Platforms
• Supported formats
• Usage guide
  • Images, frames and animations
  • Pages and representations
  • Ownership, lifetimes and leases
  • Thread safety
  • Failure atomicity
  • Pixel formats, precision and alpha
  • Processing
  • Metadata, color profiles and orientation
  • Loading, identification and limits
  • Streaming readers and writers
  • Saving files
  • Errors
• Format reference
  • PNG and APNG
  • GIF
  • JPEG
  • WebP
  • QOI
  • BMP
  • TGA
  • Netpbm: PBM, PGM, PPM and PAM
  • TIFF and BigTIFF
  • ICO and CUR
• Limitations

Quick start

Namespaces: Meziantou.Framework.Imaging (images, I/O, processing, configuration), Meziantou.Framework.Imaging.Formats (encoders and their settings), Meziantou.Framework.Imaging.Metadata.

using Meziantou.Framework.Imaging;

using var image = Image.Load("animation.gif");
image.Resize(new ResizeOptions(320, 240));
image.Save("thumbnail.gif");

The output format follows the extension, and the timing and play count of the animation are kept. An explicit encoder chooses the format and its settings; formats that store one still image require the frame to be exported explicitly:

using Meziantou.Framework.Imaging;
using Meziantou.Framework.Imaging.Formats;

using var image = Image.Load("animation.gif");          // every displayed frame, exact timing
image.Resize(new ResizeOptions(320, 240));               // all frames, atomically
image.Save("thumbnail.png", new PngEncoder());           // APNG, because the image is animated

using var frame = image.CloneFrame(0);                    // JPEG stores one frame: export it explicitly
frame.Save("first.jpg", new JpegEncoder { Quality = 85, BackgroundColor = new Rgba32(255, 255, 255) });

Design highlights

• Full displayed frames. An image is one or more full-canvas frames sharing a size and pixel type; encoded delta rectangles, blending and disposal are codec internals. APNG poster frames are kept separately.
• Pages and representations are not frames. The pages of a TIFF document and the sizes inside an icon live in a separate ImageCollection, whose entries may differ in size and pixel format and never carry timing or looping.
• Explicit ownership. Image/Image<TPixel> are disposable owners; frames are borrowed views; clones, extracted frames and reader results are independent owned images. Eager loads never retain their input.
• Precision and alpha. Six working pixel formats (Rgba32, Bgra32, Rgb24, Rgba64, Gray8, Gray16), 16-bit precision preserved, straight alpha, alpha-aware resampling, and no silent alpha/precision/metadata/animation loss.
• Exact timing. Rational FrameDuration preserves GIF, APNG and WebP delays exactly; TotalPlays counts total plays.
• Atomic geometry. Crop, resize, rotate and auto-orient apply to every frame (and the poster) transactionally.
• Bounded streaming. Sequential readers and writers process long animations with memory bounded by one frame.
• Safety. Configurable resource limits, distinct exceptions for malformed data, unsupported features, limits, cancellation and I/O failures, and atomic file publication.

Platforms

Supported formats

Detection is content-based, never by extension. "Not supported" features are recognized and rejected explicitly, never decoded or encoded approximately; see Format reference and Limitations.

JPEG XL and AVIF are not supported.

Usage guide

Images, frames and animations

Full displayed frames, not encoded deltas. An Image holds one or more frames; every frame is the complete canvas a viewer shows at that point of the animation, with the canvas size and the image's pixel type. Encoded delta rectangles, offsets, APNG blend/dispose operations and GIF disposal methods are resolved by the decoders (one compositor shared by eager and sequential decoding) and recomputed by the encoders from the displayed frames. They are not public state: editing, removing or reordering frames can never leave stale encoded instructions behind.

• Frames[i].Metadata.Duration is the frame's exact FrameDuration; Image.Animation (TotalPlays) holds the animation-wide settings. Animation settings are structural data, never removed by metadata policies.
• IsAnimated is true with several frames, a poster frame, or non-null Animation. Adding a second frame or a poster creates default settings (infinite loop); removing frames down to one keeps them, so the image stays animated until Animation is set to null (allowed only with one frame and no poster).
• Static outputs (static PNG, JPEG) reject animated images with UnsupportedImageFeatureException instead of silently saving the first frame; export a frame explicitly with CloneFrame.

Posters and playback. APNG can store a default image that is not part of the animation: decoders that do not support APNG show it, APNG players skip it. It is exposed as PosterFrame, excluded from Frames.Count, preserved by eager loads and by whole-image operations (geometry, flip, grayscale, convolution), and returned once by ImageReader.ReadPosterFrame before the first displayed frame. An APNG whose default image is frame zero has no poster. Only animated PNG output can store a poster; other outputs reject an image that has one (remove it with RemovePosterFrame).

Exact timing. FrameDuration is a normalized rational number of seconds: GIF delays (d/100) and APNG delays (num/den, den = 0 meaning /100) are kept exactly, zero durations included; no player minimum-delay heuristic is applied. TotalPlays counts the total number of plays including the first (null = infinite): a GIF NETSCAPE2.0 loop count L stores repetitions, so it maps to L + 1 plays (L = 0 is infinite, no loop extension is one play); APNG num_plays maps directly (0 is infinite). On export, FrameDurationRounding decides what happens when a duration is not representable: RequireExact throws, RoundToNearest picks the nearest representable value (APNG default: RequireExact; GIF default: RoundToNearest, to the nearest hundredth with ties up). Values beyond the format's range are always rejected, never clamped. ToTimeSpan rounds to the nearest 100 ns tick (ties up); TotalSeconds and TotalMilliseconds are floating-point approximations for display.

public static void BuildAnimation(string apngPath, string gifPath)
{
    using var animation = new Image<Rgba32>(64, 64, new Rgba32(255, 0, 0));
    animation.Frames[0].Metadata.Duration = FrameDuration.FromMilliseconds(100);

    var second = animation.AppendFrame(); // creates default animation settings (infinite loop)
    second.Metadata.Duration = new FrameDuration(1, 30); // exactly 1/30 s
    second.ProcessPixelRows(static pixels =>
    {
        for (var y = 0; y < pixels.Height; y++)
        {
            pixels.GetRowSpan(y).Fill(new Rgba32(0, 0, 255));
        }
    });

    animation.Animation!.TotalPlays = 3; // played three times in total

    animation.Save(apngPath, new PngEncoder { AnimationMode = PngAnimationMode.Animated });
    animation.Save(gifPath, new GifEncoder { Dithering = GifDithering.FloydSteinberg });
}

Pages and representations

Pages and representations are not frames. A TIFF document and an icon file hold images that are not an animation: the pages of a document in order, and the alternative sizes and color depths of one drawing. They live in a separate, disposable ImageCollection whose entries may differ in size, pixel format and metadata, and which never carries a duration, a blend or disposal operation or a loop count. A decoded entry is always a one-frame still image, and Image.OpenReader rejects TIFF, ICO and CUR explicitly, so a consumer that plays frames can never receive pages or icon sizes by accident.

• Loading (ImageCollection.Load from a path, a seekable stream or a span) reads only the container structure, so describing every entry of a large document costs a few kilobytes of reads. Each entry exposes its Size, PixelFormat, ColorModel, BitsPerComponent, MayHaveTransparency, PayloadFormat, Hotspot and Metadata; nothing is resized or converted implicitly.
• ImageCollectionEntry.Decode (or Decode<TPixel>) reads and decodes exactly one entry, with its own limits and allocation scope, and returns a normal independently owned Image.
• A loaded collection keeps its input open until it is disposed: a path stays open, a stream must be seekable and is seeked freely (its position afterward is unspecified), and a span is copied once. Loading is synchronous by design (a random-access decoder issues many small dependent reads); Image.LoadAsync and Image.IdentifyAsync do work on these formats, by buffering the input under MaxEncodedBytes.
• Entries are borrowed from their collection and are valid until it is disposed or they are removed. Add and Insert copy the image, so the caller keeps and disposes its own; RemoveAt and Move edit the order, and removed owned entries are released.
• Image.Load and Image.Identify use the first page of a document, or the largest (then deepest) representation of an icon, and report the number of entries in ImageInfo.CollectionEntryCount. ImageCollection.SelectBySize chooses a representation explicitly: the smallest one at least as large as the request, else the largest (ties by bit depth, then container order). Nothing is resized.
• ImageCollection.Save writes pages with TiffEncoder and representations with IcoEncoder; entries are materialized one at a time, and path destinations are published atomically.
• An icon or cursor representation stores at most 256 pixels per side. A cursor hotspot (ImageCollectionEntry.Hotspot) is metadata validated against its own representation, never a pixel offset.

public static Size WriteAndReadTiffDocument(string inputPath, string documentPath)
{
    using (var pages = ImageCollection.Create(ImageCollectionKind.Pages))
    {
        using var source = Image.Load(inputPath);
        using var first = source.CloneFrame(0); // a page is a still image, never an animation frame
        using var second = first.Clone();
        second.Resize(new ResizeOptions(first.Width / 2, first.Height / 2));

        // Add copies the image: the caller keeps and disposes its own
        pages.Add(first);
        pages.Add(second);
        pages.Save(documentPath, new TiffEncoder { Compression = TiffCompression.Deflate });
    }

    // Loading reads the directory structure only: the pixels of a page are read when that page is decoded
    using var document = ImageCollection.Load(documentPath);
    using var page = document[1].Decode();
    return page.Size; // the second page keeps its own size, never the first one's
}

public static Point WriteAndReadIcon(string inputPath, string iconPath, string cursorPath)
{
    using var loaded = Image.Load(inputPath);
    using var source = loaded.CloneFrame(0); // a representation is a still image, never an animation frame
    using var representations = ImageCollection.Create(ImageCollectionKind.Representations);
    foreach (var side in (int[])[16, 32, 256])
    {
        using var sized = source.Clone();
        sized.Resize(new ResizeOptions(side, side) { Mode = ResizeMode.Stretch, AllowUpscaling = true });
        representations.Add(sized, hotspot: new Point(side / 2, side / 2));
    }

    // An icon cannot store a hotspot, so the entry hotspots are unsupported metadata there
    representations.Save(iconPath, new IcoEncoder { MetadataHandling = MetadataHandling.DiscardUnsupported });
    representations.Save(cursorPath, new IcoEncoder { Kind = IconKind.Cursor });

    using var icon = ImageCollection.Load(iconPath);
    using var best = icon.SelectBySize(new Size(24, 24)).Decode(); // the 32x32 representation: nothing is resized
    using var cursor = ImageCollection.Load(cursorPath);
    return cursor.SelectBySize(new Size(16, 16)).Hotspot!.Value;
}

Ownership, lifetimes and leases

Owned and borrowed objects.

Leases. Pixels are accessed through exclusive scoped leases: ProcessPixelRows (typed rows), ProcessPixelBytes (raw native-endian bytes), the scalar indexer and CopyPixelDataTo/CopyPixelBytesTo. Row spans contain exactly the visible pixels of one row; rows are contiguous but the whole image is not, and no API exposes whole-image memory. The accessors are ref structs, so a callback cannot be asynchronous or keep a span. While a lease is active, disposing the image, structural edits and conflicting access throw InvalidOperationException (best-effort detection, not synchronization). Leases are released even when the callback throws. Static callbacks and the explicit state overloads allocate nothing per row.

public static void InvertColors(string path)
{
    using var image = Image.Load<Rgba32>(path);
    foreach (var frame in image.Frames)
    {
        frame.ProcessPixelRows(static pixels =>
        {
            for (var y = 0; y < pixels.Height; y++)
            {
                foreach (ref var pixel in pixels.GetRowSpan(y))
                {
                    pixel = new Rgba32((byte)(255 - pixel.R), (byte)(255 - pixel.G), (byte)(255 - pixel.B), pixel.A);
                }
            }
        });
    }

    image.Save(path);
}

public static long ComputeLuminanceSum(Image<Gray16> image)
{
    var total = new StrongBox<long>();
    image.Frames[0].ProcessPixelRows(total, static (pixels, state) =>
    {
        for (var y = 0; y < pixels.Height; y++)
        {
            foreach (var pixel in pixels.GetRowSpan(y))
            {
                state.Value += pixel.Value;
            }
        }
    });

    return total.Value;
}

public static byte[] RoundTripRawPixels(ReadOnlySpan<byte> rgba, int width, int height)
{
    using var image = Image.ImportPixelBytes<Rgba32>(rgba, width, height);
    image.Crop(new Rectangle(0, 0, width / 2, height));
    var result = new byte[image.Width * image.Height * 4];
    image.Frames[0].CopyPixelBytesTo(result);
    return result;
}

Memory accounting. Every library-controlled buffer is charged, at its actual rented capacity, to the allocation scope of its owner (an image, or a reader and the images it returns) and bounded by ImageResourceLimits.MaxLiveAllocationBytes. Images returned by a reader stay charged to the reader's scope until they are disposed, even after the reader is disposed. Scopes are safety bounds per owner, not process-wide memory or CPU caps.

Thread safety

Static methods (Load, Identify, DetectFormat, ...) are thread-safe, and so are the immutable types (configuration, limits, options, encoders, MetadataBlob, profiles). Distinct images can be processed concurrently. An Image and its frames must not be used concurrently while any thread mutates them or holds a lease. Readers and writers support one operation at a time: overlapping calls throw InvalidOperationException. Internal parallelism is off by default (ImageConfiguration.MaxDegreeOfParallelism = 1); with more workers, only large resizes and convolutions are split into row bands, with results identical to the sequential ones.

Failure atomicity

• Geometry is atomic. Crop, Resize, Rotate and AutoOrient apply to every frame and the poster in one transaction: replacements are allocated (and charged) while the originals are live, and any failure before the commit (limit, allocation failure, cancellation) leaves dimensions, pixels, frame identities and order, and metadata unchanged.
• Pixel mutations may be partial. Flip, Grayscale, Convolve, row callbacks and ReadFrameInto write in place: a failure or a cancellation can leave some rows or frames updated, but the image stays structurally valid and disposable. Convolve rents its scratch rows first: exceeding the allocation limit leaves the image unchanged.
• Failed operations release every resource they acquired; nothing is leaked or returned to a pool while still visible.

Pixel formats, precision and alpha

Working formats. Six pixel types: Rgba32, Bgra32, Rgb24, Rgba64, Gray8, Gray16 (sequential Pack = 1 layouts, straight alpha, 16-bit components in native endianness; PixelFormats describes them). Untyped Load picks the format that preserves the source: for example 16-bit PNGs load as Gray16/Rgba64, palettes and transparency as Rgba32, JPEG as Gray8/Rgb24, GIF as Rgba32 (ImageInfo.PixelFormat tells it before decoding). Typed Load<TPixel> and CloneAs<TPixel> convert explicitly between any two formats: 8 to 16 bits is exact (v * 257), 16 to 8 bits rounds to nearest, color to gray uses Rec. 709 luma on the encoded values. A 16-bit path never goes through 8 bits.

No silent loss. Converting non-opaque pixels to a format without alpha throws UnsupportedImageFeatureException unless an opaque background is given; fully opaque pixels never need one. The controls:

public static void ConvertToGray16(string inputPath, string outputPath)
{
    using var image = Image.Load<Rgba64>(inputPath);
    image.AutoOrient();
    using var gray = image.CloneAs<Gray16>(new PixelConversionOptions
    {
        BackgroundColor = new Rgba64(65535, 65535, 65535),
        DiscardIncompatibleColorProfile = true,
    });
    gray.Save(outputPath, new PngEncoder());
}

public static void ExportFrameAsJpeg(string animatedPath, int frameIndex, string jpegPath)
{
    using var animation = Image.Load(animatedPath);
    using var frame = animation.CloneFrame(frameIndex);
    frame.Save(jpegPath, new JpegEncoder
    {
        Quality = 85,
        BackgroundColor = new Rgba32(255, 255, 255),
        AllowBitDepthReduction = true,
        MetadataHandling = MetadataHandling.DiscardUnsupported,
    });
}

Processing

In-place extension methods (ImageProcessingExtensions), applied to every frame and the poster: Crop (an in-canvas rectangle, never clamped), Resize, Rotate (exact 90/180/270 permutations), Flip, AutoOrient (all eight EXIF orientations), Grayscale (Rec. 709 at storage precision, ties upward; keeps the storage format and alpha, and rejects incompatible ICC profiles; use CloneAs<Gray8> to change the storage) and Convolve (a convolution matrix). Flip, Grayscale and Convolve also exist for one frame. Geometry changes preserve 16-bit precision and alpha, and reconcile the EXIF dimensions, orientation and thumbnail.

Resizing. ResizeOptions sets the target box and Mode: Contain (default: fit inside, never padded), Cover (fill exactly, cropped around Anchor, one of nine positions) or Stretch; AllowUpscaling = false keeps Contain within the original size and rejects Cover/Stretch enlargements. Target sizes are computed with exact rational arithmetic, rounded to nearest (ties up), and are at least 1 pixel. Filters: nearest neighbor, bilinear, bicubic Catmull-Rom (default) and Lanczos3, sampled at pixel centers with clamped edges, normalized weights, and a support widened when downsampling. Colors are filtered premultiplied by alpha, so hidden colors of transparent pixels never bleed (zero alpha becomes transparent black), and 16-bit images are filtered with 16-bit precision.

• ResizeWorkingSpace.Encoded (default) filters the stored sample values directly, like most image tools.
• ResizeWorkingSpace.LinearSrgb converts sRGB samples to linear light (IEC 61966-2-1 transfer) before filtering and back afterward (more physically correct averages, for example for thin bright lines). It accepts untagged images (assumed sRGB) and ICC profiles recognized as sRGB or sGray only; any other profile is rejected rather than misinterpreted. No ICC transform is applied in either space.

A resize to the current size leaves the image unchanged. Results do not depend on the worker count or on SIMD support: the vectorized and parallel kernels are bit-identical to the scalar reference.

public static void ResizeAnimation(string inputPath, string outputPath)
{
    using var image = Image.Load(inputPath);
    image.Resize(new ResizeOptions(320, 240) { Mode = ResizeMode.Contain, Filter = ResamplingFilter.Lanczos3 });

    // Same format as the extension; APNG/GIF timing and play count come from the decoded image
    image.Save(outputPath);
}

Convolution matrices. Convolve replaces every sample by the weighted sum of the same sample of the neighboring pixels: sharpening, blurring, embossing and edge detection are all matrices. A ConvolutionKernel has odd dimensions, so its middle weight is the one of the pixel itself, and holds its weights row by row. It is applied as written (the top-left weight multiplies the top-left neighbor; it is not flipped) and the weights are used as given: divide them by their sum to keep the overall brightness. ConvolutionOptions then chooses:

• EdgeMode, the pixels read outside the image: Clamp (default, the nearest edge pixel), Mirror (the image reflected about its border), Wrap (the image tiled) or Zero (nothing: transparent black).
• PreserveAlpha. By default the filter is alpha-aware, like resizing: colors are filtered premultiplied by alpha, alpha is filtered too, and a pixel whose alpha becomes zero is transparent black, so hidden colors never bleed. A matrix whose weights add up to zero (edge detection) therefore turns every pixel transparent: set PreserveAlpha = true to filter the colors as stored and leave alpha untouched. Pixel formats without alpha are not concerned.
• WorkingSpace: Encoded (default) or LinearSrgb, with the same meaning and the same ICC profile rule as ResizeWorkingSpace.

Sums are computed in double precision at the storage precision (16-bit images are filtered with 16-bit precision), rounded to nearest (ties up) and clamped to the sample range: negative sums become 0. The image is rewritten in place, with a scratch of a few rows per worker proportional to the matrix height, charged to the allocation limit; the pixel format, the size, the frames and the metadata are kept (the EXIF thumbnail, now stale, is removed). As for resizing, results do not depend on the worker count or on SIMD support. The cost grows with the number of non-zero weights: there is no dedicated fast path for separable matrices such as large blurs.

public static void SharpenAndDetectEdges(string inputPath, string sharpenedPath, string edgesPath)
{
    using var image = Image.Load(inputPath);

    // The matrix is applied as written, row by row; weights that add up to 1 keep the overall brightness
    var sharpen = new ConvolutionKernel(3, 3, [0, -1, 0, -1, 5, -1, 0, -1, 0]);
    using (var sharpened = image.Clone())
    {
        sharpened.Convolve(new ConvolutionOptions(sharpen));
        sharpened.Save(sharpenedPath);
    }

    // Weights that add up to 0 would also filter alpha down to 0 (transparent black): keep the alpha instead
    var laplacian = new ConvolutionKernel(3, 3, [0, 1, 0, 1, -4, 1, 0, 1, 0]);
    image.Convolve(new ConvolutionOptions(laplacian) { PreserveAlpha = true, EdgeMode = ConvolutionEdgeMode.Mirror });
    image.Save(edgesPath);
}

There is no ICC color conversion, HDR processing, drawing, text rendering or custom processor.

Metadata, color profiles and orientation

Image.Metadata holds the source format (informational only), the EXIF orientation, the resolution, ICC/EXIF/XMP profiles (byte-for-byte payloads) and text entries.

• Color profiles are preserved, never applied. A profile labels the pixels; untagged pixels are assumed sRGB. Decoders keep it, encoders write it (for example PNG iCCP, JPEG APP2), conversions keep it only when it can still label the converted pixels (gray profile for gray formats, RGB profile for color formats). There is no color management.
• Transfer functions are labels too. Metadata.TransferFunction is Srgb (the default: sRGB samples, or as described by the ICC profile) or Linear (linear-light samples, declared by a QOI colorspace of 1). No operation converts the pixels; linear-light resizing filters Linear samples directly. Only QOI stores the label: the other encoders treat Linear as metadata they cannot store, so the samples are never silently relabeled as sRGB.
• Orientation is reported, never applied by decoders. Metadata.Orientation reports the EXIF orientation; AutoOrient() transforms the pixels for all eight orientations and resets it to TopLeft. On save, the typed orientation is authoritative: EXIF orientation and dimension tags are rewritten and thumbnails made stale by geometry changes are removed.
• Saving follows ImageEncoder.MetadataHandling: Strict (default) throws UnsupportedImageFeatureException for metadata the format cannot store, DiscardUnsupported drops it, Strip writes no optional metadata. Animation timing is never affected. A malformed caller-supplied EXIF, ICC or XMP payload is rejected at save time.
• Decoded metadata is bounded: payloads, decompressed text included, are charged to MaxMetadataBytes.

TIFF stores the resolution, the orientation, an ICC profile and XMP (no EXIF block, no text entries); ICO and CUR store no metadata. Unknown chunks, segments and extensions are skipped on decode and not round-tripped.

public static void EditMetadata(string path)
{
    using var image = Image.Load(path);
    image.Metadata.TextEntries.Add(new ImageTextEntry("Title", "Sunset"));
    image.Metadata.Resolution = new ImageResolution(300, 300);
    image.Save(path, new PngEncoder { MetadataHandling = MetadataHandling.Strict });
}

Loading, identification and limits

Detection is content-based (never by extension); Image.DetectFormat needs at most Image.FormatDetectionPrefixLength (18) bytes, because TGA has no signature and is recognized from a strictly plausible 18-byte header, consulted last. Load exists in synchronous and asynchronous, path, stream and span, typed and untyped forms, with identical results and error categories. Identify returns an ImageInfo without decoding pixels: Header mode reads up to the first pixel data, FullScan walks the whole structure (chunks, blocks, markers, CRCs, rows). Unknown values stay null and are never guessed (a GIF header never yields a frame count).

public static string Describe(Stream stream)
{
    var info = Image.Identify(stream, new ImageIdentifyOptions { Mode = ImageIdentifyMode.FullScan });
    var frames = info.FrameCount?.ToString(CultureInfo.InvariantCulture) ?? "unknown";
    return $"{info.Format} {info.Size} {info.PixelFormat}, frames: {frames}, orientation: {info.Metadata.Orientation}";
}

Limits versus prefix selection. ImageResourceLimits (canvas width/height, pixels per frame, frames, total pixels, encoded bytes, metadata bytes, live allocations) are safety bounds: exceeding one throws ImageResourceLimitException (Kind, Limit, Requested) and is never turned into a successful truncation. FrameLimit (decode and reader options) is deliberate prefix selection: decoding stops after that many displayed frames and the rest of the input is neither examined nor validated. Limits are inclusive and enforced before allocating or consuming.

TIFF, ICO and CUR are random-access containers: on a seekable source, only the bytes their structure points at are read (the stream position afterward is unspecified), and a non-seekable or asynchronous load buffers the input, bounded by MaxEncodedBytes.

Streaming readers and writers

Readers and writers process long animations frame by frame with memory bounded by about one frame of decoder or encoder state, plus the images the caller keeps.

Streams. Every stream API starts at the stream's current position and consumes what it reads (no rewinding). Non-seekable streams are supported for input (bounded prefix replay) and output (no seeking, except for the WebP animations and TIFF files described below). Caller streams are left open: eager APIs never close them, and readers/writers close them only with LeaveOpen = false (for a reader, ownership then transfers even when opening fails). Path overloads own and close their files. Asynchronous methods use asynchronous I/O and accept a CancellationToken; argument errors are thrown synchronously.

Readers (Image.OpenReader<TPixel>):

• Info is a header snapshot: format, canvas, frame count when the header declares it (null for GIF), animation settings and the metadata before the first frame.
• ReadPosterFrame returns the APNG poster (or null); it is allowed once, before the first displayed frame. A poster that is not read is still validated and counted against MaxFrames.
• ReadFrame returns an owned single-frame still image (with its duration and image metadata; animation-wide settings are in Info), or null at the clean end of the animation or when FrameLimit is reached.
• ReadFrameInto(destination) overwrites a caller-owned image instead of allocating one. The destination must have the canvas size, exactly one frame, no poster and no animation settings; its duration and metadata are refreshed. It returns false at the clean end (destination unchanged); after a failure the destination may be partially updated but stays valid, and it stays charged to its own owner.
• null/false always means a clean end. Malformed data, limits, I/O errors and cancellation throw and fault the reader (later calls throw InvalidOperationException); argument errors leave it usable.
• TIFF, ICO and CUR are rejected explicitly: their entries are pages or representations, not a frame sequence (use ImageCollection).

Writers (Image.CreateWriter<TPixel>): an optional WritePosterFrame (animated PNG only, before the first frame), then WriteFrame for each frame, then Complete, which is mandatory: disposing a writer without a successful Complete aborts the output, it is never finalized implicitly. Complete is idempotent. The options (canvas, encoder, metadata, animation settings) are snapshotted when the writer is created, and the metadata policy is applied before any output.

Complete checks that at least one frame was written and that the count matches. Errors detected before any work (state, order, frame size or pixel type, a frame duration the format cannot store) leave the writer usable; a failure once encoding started faults it.

public static async Task StreamingResizeAsync(Stream input, Stream output, CancellationToken cancellationToken)
{
    await using var reader = await Image.OpenReaderAsync<Rgba32>(input, cancellationToken: cancellationToken);
    var info = reader.Info;
    var size = new Size(info.Width / 2, info.Height / 2);

    await using var writer = Image.CreateWriter<Rgba32>(output, new ImageWriterOptions(size)
    {
        Encoder = new GifEncoder(),
        Animation = info.Animation, // e.g. preserve the number of plays
        Metadata = info.Metadata,
    });

    while (await reader.ReadFrameAsync(cancellationToken) is { } frame)
    {
        using (frame)
        {
            frame.Resize(new ResizeOptions(size) { Mode = ResizeMode.Stretch }, cancellationToken);
            await writer.WriteFrameAsync(frame.Frames[0], cancellationToken);
        }
    }

    await writer.CompleteAsync(cancellationToken); // mandatory: disposing without Complete aborts the output
}

public static void StreamingWithReusedBuffer(string inputPath, string outputPath)
{
    using var reader = Image.OpenReader<Rgba32>(inputPath);
    var info = reader.Info;
    var frameCount = info.FrameCount ?? throw new InvalidOperationException("PNG output requires a known frame count.");

    using var writer = Image.CreateWriter<Rgba32>(outputPath, new ImageWriterOptions(info.Size)
    {
        Encoder = new PngEncoder { AnimationMode = PngAnimationMode.Animated },
        ExpectedFrameCount = frameCount,
        Animation = info.Animation,
    });

    if (reader.ReadPosterFrame() is { } poster)
    {
        using (poster)
        {
            writer.WritePosterFrame(poster.Frames[0]);
        }
    }

    using var buffer = new Image<Rgba32>(info.Width, info.Height);
    while (reader.ReadFrameInto(buffer))
    {
        buffer.Grayscale();
        writer.WriteFrame(buffer.Frames[0]);
    }

    writer.Complete(); // publishes outputPath atomically
}

Saving files

Save(stream, encoder) requires an encoder. Save(path) infers it from the extension: .png (APNG when the image is animated), .apng (always APNG), .gif, .jpg/.jpeg, .webp (lossless by default), .qoi, .bmp/.dib, .tga/.icb/.vda/.vst, .pnm/.pam/.ppm/.pgm, .tif/.tiff, .ico and .cur; anything else throws ArgumentException. An eager save validates the whole image against the output (animation, poster, durations, alpha, precision, metadata) before writing anything.

Path outputs, eager or through writers, are written to a temporary file in the destination directory and published by a rename only after a successful Complete: on any failure, cancellation or uncompleted writer, an existing destination is left untouched and only the library's own temporary file is deleted. No crash durability (fsync) is claimed. Stream outputs are written as they go; after a failure, the bytes already written remain and nothing is finalized.

Errors

Content errors derive from ImageException:

Other failures use the standard exceptions: ArgumentException (invalid arguments, mismatched frames), NotSupportedException (an unsupported TPixel, before any I/O), InvalidOperationException (invalid state, lease conflicts, overlapping or faulted reader/writer calls), ObjectDisposedException, OperationCanceledException, and IOException from the stream, propagated unchanged. Malformed data and resource failures are never reported as a clean end of input.

public static Image? TryLoad(string path, ImageConfiguration configuration)
{
    try
    {
        return Image.Load(path, new ImageDecodeOptions { Configuration = configuration });
    }
    catch (UnknownImageFormatException)
    {
        return null; // not an image
    }
    catch (UnsupportedImageFeatureException ex)
    {
        Console.Error.WriteLine($"Unsupported {ex.Format} feature: {ex.Feature}");
        return null;
    }
    catch (ImageResourceLimitException ex)
    {
        Console.Error.WriteLine($"Limit {ex.Kind} exceeded ({ex.Requested} > {ex.Limit})");
        return null;
    }
    catch (InvalidImageContentException)
    {
        return null; // corrupted or truncated file
    }
}

Format reference

Every codec works eagerly (Load, Save) and sequentially (readers, writers) with the same results, and streams with bounded memory unless stated otherwise.

PNG and APNG

PngEncoder.AnimationMode: Auto writes an APNG for animated images (several frames, a poster or animation settings), Animated and the .apng extension always do; the static mode rejects animated images.

GIF

JPEG

WebP

WebPEncoder.Compression chooses the bitstream for every frame: Lossless (the default) keeps every 8-bit sample, including the colors of fully transparent pixels (ClearTransparentColors opts into transparent black); Lossy is VP8 with 4:2:0 chroma, controlled by Quality (0-100), and keeps alpha losslessly. Effort (0-9, default 5) trades encoding time for size and never changes lossless pixels. Gray images are stored as RGB; 16-bit images need AllowBitDepthReduction.

A still image streams to any destination. An animation (several frames, animation settings, or a writer without ExpectedFrameCount = 1) declares its size before its frames, so it needs a seekable destination: frames are written as they come and the RIFF size and alpha flag are patched at the end. Non-seekable streams are rejected with an ArgumentException before anything is written (there is no spooling); path outputs are always seekable and atomic. Durations are rounded to the nearest millisecond by default (DurationRounding), and the loop count holds 1 to 65,535 plays or infinite.

public static void SaveWebP(string photoPath, string webpPath, string animatedPath, string animatedWebPPath)
{
    using (var photo = Image.Load(photoPath))
    {
        photo.Save(webpPath, new WebPEncoder
        {
            Compression = WebPCompression.Lossy,
            Quality = 80, // 0-100: size versus fidelity
            Effort = 6,   // 0-9: encoding time versus size
            AllowBitDepthReduction = true, // 16-bit sources are written with 8 bits
        });
    }

    // Every sample is kept, including the colors of fully transparent pixels. An animation needs a seekable
    // destination (the file size is patched at the end): a path, a FileStream or a MemoryStream.
    using var animation = Image.Load(animatedPath);
    animation.Save(animatedWebPPath, new WebPEncoder { Compression = WebPCompression.Lossless });
}

Decoding: lossless images decode exactly; lossy images decode to the exact VP8 reconstruction (RFC 6386) converted to RGB with a documented BT.601 contract and centered bilinear chroma upsampling (within one unit of libwebp). Still images without alpha load as Rgb24, others and every animation as Rgba32. Animation frames are full-canvas displayed images (alpha blending with an exact OVER contract, mixed lossy and lossless frames, exact millisecond durations); disposed areas become transparent black and the ANIM background color is never painted. The container walker buffers one image's payloads at most, skips unknown chunks, and charges the canvas to the limits before any image. ICC (RGB profiles), EXIF and XMP are read from and written to extended files; text and resolution have no WebP chunk. VP8 interframes and hidden frames are not supported.

QOI

QOI is a small lossless format for one 8-bit RGB or RGBA still image. QoiEncoder keeps every 8-bit sample, including the colors of fully transparent pixels; pixel formats with alpha are written with 4 channels, the others with 3 (gray as RGB), and 16-bit images need AllowBitDepthReduction. Its output is byte-identical to the qoi.h reference encoder. QOI stores no metadata: ICC, EXIF, XMP, orientation, resolution and text follow MetadataHandling (rejected by default). The header colorspace is written from Metadata.TransferFunction (Strip writes 0) and decoded back into it. Encoding and decoding stream: the decoder keeps one row and consumes the input as it arrives, the encoder writes bounded bands to any destination.

public static void SaveQoi(string inputPath, string qoiPath, string linearQoiPath, string pngPath)
{
    using var image = Image.Load(inputPath);
    using var frame = image.CloneFrame(0); // QOI stores one still image
    frame.Save(qoiPath, new QoiEncoder { AllowBitDepthReduction = true });

    // A QOI colorspace of 1 (linear samples) is reported as a label, never applied: other formats cannot store it, so
    // saving the pixels elsewhere requires an explicit decision instead of silently relabeling them as sRGB
    using var linear = Image.Load(linearQoiPath);
    if (linear.Metadata.TransferFunction == ColorTransferFunction.Linear)
    {
        linear.Save(pngPath, new PngEncoder { MetadataHandling = MetadataHandling.DiscardUnsupported });
    }
}

Decoding: 3-channel files load as Rgb24 (opaque, whatever alpha values the chunks carry), 4-channel files as Rgba32. Every chunk form is supported, runs may cross rows, and bytes after the end marker are not read. Zero dimensions, other channel counts or colorspaces, a run past the last pixel, a missing end marker and truncation are InvalidImageContentException; dimensions above 2^31 - 1 or the configured limits are ImageResourceLimitException before any allocation.

BMP

BMP, TGA and Netpbm are uncompressed (or run-length) formats for desktop interchange (BMP), asset pipelines (TGA) and tooling fixtures (Netpbm). Each stores one still image, and each encoder makes its format-specific choices explicit.

public static void SaveAssetFormats(string inputPath, string bmpPath, string tgaPath, string pnmPath)
{
    using var image = Image.Load(inputPath);
    using var frame = image.CloneFrame(0); // BMP, TGA and Netpbm store one still image

    // BMP: 32-bit with an explicit alpha mask for pixel formats with alpha, 24-bit otherwise. Forcing 24-bit discards
    // alpha, so it needs a background color.
    frame.Save(bmpPath, new BmpEncoder { PixelLayout = BmpPixelLayout.Bgr24, BackgroundColor = new Rgba64(65535, 65535, 65535), AllowBitDepthReduction = true });

    // TGA: run-length packets are lossless and usually smaller on graphic content
    frame.Save(tgaPath, new TgaEncoder { Compression = TgaCompression.RunLength, AllowBitDepthReduction = true });

    // Netpbm: the variant follows the pixel format (PGM, PPM, or PAM when the pixels have alpha), and MAXVAL follows
    // the precision, so 16-bit images keep every bit
    frame.Save(pnmPath, new PnmEncoder());
}

TGA

TGA has no signature, so it is recognized from a strictly plausible 18-byte header and checked last; give DetectFormat 18 bytes (Image.FormatDetectionPrefixLength). The TGA 2.0 developer area, extension area and footer are located by offsets stored at the end of the file, which a forward-only decoder cannot follow: they are not read, so a TGA with a trailer leaves its trailing bytes unread, and a prefix that holds the whole raster is a valid TGA 1.0 file with the same pixels (truncation is only detected before the end of the image data).

Netpbm: PBM, PGM, PPM and PAM

MAXVAL up to 255 gives 8-bit samples, above it 16-bit, normalized with round(value * targetMax / MAXVAL). Only the first image of a concatenation is read, and it is never reported as an animation.

TIFF and BigTIFF

Use ImageCollection for multi-page documents (see Pages and representations); Image.Load reads the first page and Image.Save writes one. TiffEncoder writes a conservative subset whose sample layout follows the pixel format losslessly, which is why it has neither a background color nor a bit-depth switch. It needs a seekable destination, because a directory stores the offsets of the strips it describes.

LZW, PackBits, CCITT and JPEG compression, palette, CMYK, YCbCr and L*a*b* data, planar storage, reversed fill order, the floating-point predictor, signed or floating-point samples, other sample widths, more than one extra sample and premultiplied or unspecified extra samples are recognized and rejected with UnsupportedImageFeatureException.

ICO and CUR

Use ImageCollection to read and write every representation (see Pages and representations); Image.Load reads the largest (then deepest) one.

.ani animated cursors are a different container and are not supported.

Limitations

Everything below is rejected explicitly (never decoded or encoded approximately) or documented as lossy.