PeachImage

PeachImage is the pure .NET image codec library PeachPDF decodes every raster image with, and that PeachDrawing encodes the bitmaps it saves with. It reads and writes the formats the web uses (JPEG, PNG, GIF, WebP, AVIF, BMP and JPEG XL, plus TIFF for reading) as managed code only: no native library, no P/Invoke, no platform imaging API, so the same code runs on Windows, Linux, macOS, Android and in the browser. It targets .NET 8 and .NET 10.

PeachImage is a project of its own, released under the MIT license, and it is not versioned with PeachPDF. This page describes the version PeachPDF is built with (0.7.4), and the API reference for it is generated from that exact release, so what you read here and there is what you get by installing PeachPDF.

dotnet add package PeachImage

You do not need to add it to use PeachPDF: PeachPDF depends on it, so it arrives with the package. Reference it directly when your own code loads, converts or resizes images, as in the examples below.

Formats

Format Decode Encode Notes
JPEG yes yes Baseline and progressive decode and encode; grayscale, YCbCr, RGB, CMYK and YCCK on decode.
PNG yes yes Every color type and bit depth, Adam7 interlacing, transparency, the common ancillary chunks, optional palette quantization.
GIF yes yes GIF87a and GIF89a, transparency, animation; palette quantization with optional dithering on encode.
WebP yes yes Lossy (VP8) and lossless (VP8L), alpha, animation. Lossless is the default on encode.
AVIF yes yes Still images; lossy and lossless encode. Animated AVIF is not supported.
BMP yes yes Every common header variant and bit depth, RLE, bit-field masks.
TIFF yes no Uncompressed, LZW and PackBits; RGB, grayscale, palette and CMYK.
JPEG XL yes yes Lossy (VarDCT) and lossless (Modular) on decode and encode; alpha, 16-bit and floating-point samples and ICC profiles both ways. Decode also covers animation, HDR (PQ/HLG), wide-gamut color and CMYK; encode is stills only. Files made by recompressing a JPEG can be turned back into that exact JPEG. See JPEG XL.

The format is detected from the file’s contents, so nothing needs registering, and a file with the wrong extension still loads. A feature a codec does not implement throws a descriptive exception instead of producing a wrong image. Ask the library what it supports at run time with Image.SupportedFormats, which lists each format’s name, file extensions, MIME types, and whether it can decode and encode.

Loading, converting and saving

Image is a decoded raster: its Width, Height and PixelFormat, its pixels, and its metadata. Load from a path, a Stream, or bytes already in memory (no MemoryStream needed), and save in any format that can encode by naming it:

using PeachImage;
using PeachImage.Formats.Jpeg;

using var image = Image.Load("photo.webp");
Console.WriteLine($"{image.Width}x{image.Height} {image.PixelFormat}");

using var output = File.Create("resaved.jpg");
image.Save(output, "jpeg", new JpegEncoderOptions { Quality = 85 });

Each format has its own encoder options type under PeachImage.Formats.<Format>: JpegEncoderOptions (quality, chroma subsampling, progressive), PngEncoderOptions (compression level, color mode, palette size, dithering, interlacing), GifEncoderOptions, WebpEncoderOptions (lossless or lossy, quality), AvifEncoderOptions, BmpEncoderOptions and JxlEncoderOptions (lossless or lossy, quality, effort). SaveAsync and LoadAsync exist for async I/O paths; the encode and decode themselves are CPU-bound, so only the stream read or write is awaited.

To learn what a file is without decoding it, use Image.Identify, which reads only the header:

using PeachImage;

using var stream = File.OpenRead("photo.avif");
ImageInfo info = Image.Identify(stream);
Console.WriteLine($"{info.Width}x{info.Height} {info.PixelFormat} ({info.FormatName})");

ImageInfo also answers a few questions a caller usually wants settled before it decodes:

Image.TryLoad is the non-throwing form for untrusted input, returning false for a stream that is not an image it can read.

Pixels

The pixel buffer is exposed without copying:

using PeachImage;

using var image = Image.Load("photo.png");
Span<byte> pixels = image.GetPixelSpan();
Span<byte> firstRow = image.GetRowSpan(0);

PixelFormat says how to read it: Gray8, Rgb24, Rgba32, Cmyk32, the 16-bit-per-channel Gray16, Rgb48 and Rgba64, and the 32-bit floating-point GrayF32, RgbF32 and RgbaF32 that high-dynamic-range sources decode to. A decoder keeps the source’s format by default (a CMYK JPEG stays CMYK, so its separations are not thrown away); pass decoder options to have the image converted to a format you ask for in the same pass.

Converting pixel formats

Image.ConvertTo converts between the gray, RGB and RGBA formats at 8-bit, 16-bit and floating-point depth, for example an HDR RgbaF32 decode down to Rgb24 before encoding it. Integer targets round and clamp, color to gray uses BT.601 luma, and a target without alpha discards the alpha channel. Values are converted as stored, with no tone mapping. Every encoder except JPEG XL’s rejects the floating-point formats, so convert first. CMYK images go through ConvertToSrgb, which applies the image’s embedded profile, instead.

using PeachImage;

using var hdr = Image.Load("photo.jxl");            // may be RgbaF32 for an HDR file
using var jpegReady = hdr.ConvertTo(PixelFormat.Rgb24);

Orientation

Cameras and phones often store a photo sideways and record the turn needed to show it upright. ImageInfo.Orientation reports that value as an ImageOrientation, whose members use the EXIF numbering: Normal (1), MirrorHorizontal (2), Rotate180 (3), MirrorVertical (4), Transpose (5), Rotate90 (6), Transverse (7) and Rotate270 (8). It is read from JPEG and TIFF EXIF, a PNG eXIf chunk (one placed after the image data is not seen by Identify), a WebP EXIF chunk, AVIF irot/imir properties and the JPEG XL header.

No decoder applies it. The pixels and the width and height are always as stored, so a sideways photo loads sideways. Apply the orientation yourself with Image.ApplyOrientation, which comes in three forms: one that returns a new image (or the same instance for Normal), one that writes into a destination image you supply without allocating, and ApplyOrientationInPlace, which works for any size with MirrorHorizontal, Rotate180 and MirrorVertical and for square images with the rest. The result’s EXIF orientation is reset to 1 and its resolution values are swapped for a rotation; orientation stored in XMP is not rewritten.

using PeachImage;

ImageInfo info = Image.Identify(File.OpenRead("phone-photo.jpg"));
using var image = Image.Load("phone-photo.jpg");
using var upright = image.ApplyOrientation(info.Orientation);

PeachPDF does not use ApplyOrientation: it draws the stored pixels through a rotation matrix so that an embedded JPEG stays byte-for-byte unchanged. See the image-orientation property and Image orientation.

Early previews

DecoderOptions.PreviewAvailable is an Action<Image> that Load calls, synchronously on the decoding thread, with a lower-fidelity version of the image while the full decode is still running. ImageInfo.HasPreview says whether a file can produce one:

The callback owns each image it is given and must dispose it, and an exception thrown from it aborts the decode. Previews honor TargetPixelFormat, and the final image is identical with or without a callback. An interlaced GIF, an AVIF thumbnail and a TIFF reduced-resolution image do not produce previews.

using PeachImage;

var options = new DecoderOptions
{
    PreviewAvailable = preview =>
    {
        using (preview)
        {
            ShowPlaceholder(preview);   // your own code
        }
    },
};

using var image = Image.Load("large-progressive.jpg", options);

JPEG XL

The decoder is written in managed code and covers both coding modes (VarDCT and Modular), alpha, premultiplied alpha, extra channels (spot colors, CMYK), patches, splines, noise, upsampling, animation with full frame blending, PQ and HLG transfer functions, wide-gamut color and embedded ICC profiles. Samples above 8 bits decode to the 16-bit formats, and floating-point or deeper samples to GrayF32, RgbF32 and RgbaF32; 32-bit integer samples are not supported (the reference decoder rejects them too). A multi-frame file loads as an AnimatedImage; EXIF, XMP and the ICC profile are exposed through Image.Metadata. Like every decoder here, it reports the stored orientation through ImageInfo.Orientation rather than rotating the pixels.

The encoder writes still images only; animation encoding is not available. Set Lossless for the Modular coder, which reproduces every sample exactly (float samples are stored bit for bit, though lossless compression of float data is poor), or leave it off for lossy VarDCT, where Quality (0 to 100, default 75) sets the fidelity and Effort (1 to 9, default 5) trades encode time for file size. AdaptiveQuantization is off by default because it made files larger at the same perceptual score on photographs. Sources can be 8-bit, 16-bit or 32-bit float gray, RGB or RGBA (a fully opaque RGBA image is stored without an alpha channel), and the image’s ICC profile, EXIF and XMP are stored when IncludeMetadata is set. Tuned against SSIMULACRA2, lossy output is roughly level with libjxl at effort 7.

using PeachImage;
using PeachImage.Formats.Jxl;

using var image = Image.Load("photo.png");

using var lossy = File.Create("photo.jxl");
image.Save(lossy, "jxl", new JxlEncoderOptions { Quality = 85, Effort = 7 });

using var lossless = File.Create("photo-lossless.jxl");
image.Save(lossless, "jxl", new JxlEncoderOptions { Lossless = true });

A JPEG XL file made by losslessly recompressing a JPEG (what cjxl does with JPEG input) carries enough information to rebuild that exact JPEG file, including its progressive scans, restart intervals, Huffman tables, ICC profile, EXIF and XMP. JxlJpegReconstruction returns those original bytes without decoding any pixels, which is useful wherever a JPEG can be embedded as-is, such as in a PDF:

using PeachImage.Formats.Jxl;

using var stream = File.OpenRead("photo.jxl");
if (JxlJpegReconstruction.TryReconstructJpeg(stream, out byte[]? jpeg))
{
    File.WriteAllBytes("photo.jpg", jpeg);   // identical to the JPEG that was recompressed
}

HasJpegReconstructionData tells whether a file qualifies without rebuilding it, and ReconstructJpeg throws JxlUnsupportedFeatureException for a file that was not made from a JPEG (those decode through Image.Load as usual).

Animated images

GIF and WebP with more than one frame load as an AnimatedImage with the same load and save shape:

using PeachImage;
using PeachImage.Formats.Gif;

var animation = AnimatedImage.Load("clip.gif");

foreach (AnimatedImageFrame frame in animation.Frames)
{
    Console.WriteLine($"{frame.Duration.TotalMilliseconds}ms, disposal={frame.Disposal}");
}

using var output = File.Create("resaved.gif");
animation.Save(output, "gif", new GifEncoderOptions { MaxColors = 128, Dither = true });

Frames come out fully composited, with their duration and disposal method. Image.IsAnimated and ImageInfo.IsAnimated tell you before you choose which loader to use.

Resizing

Resize offers fifteen resampling filters through ResamplingFilter, Bicubic by default, including Lanczos3, CatmullRom, MitchellNetravali, Box and NearestNeighbor. ResizeMode.Max treats the size as a bounding box: it scales down to fit, keeps the aspect ratio and never upscales.

using PeachImage;

using var image = Image.Load("photo.jpg");

using var thumbnail = image.Resize(200, 150);
using var sharper = image.Resize(200, 150, new ResizeOptions { Filter = ResamplingFilter.Lanczos3 });
using var fitted = image.Resize(200, 200, new ResizeOptions { Mode = ResizeMode.Max });

When the source already fits a ResizeMode.Max box, the same instance comes back rather than a copy, so do not keep using the original after disposing the result in that case. AnimatedImage.Resize resizes every frame as the frames are enumerated, keeping each one’s duration and disposal.

Color profiles and metadata

Image.Metadata carries what the file embedded: an ICC profile (GetIccColorProfile()), and the raw EXIF, XMP and other profile blocks as RawMetadataProfile entries. PeachPDF reads the ICC profile to embed an image with its color space intact, and ImageInfo.IsAdobeInvertedCmyk and IsYcck tell it when a JPEG’s CMYK samples are stored inverted. See Color and ICC profiles for what PeachPDF does with them.

Disposal

Image implements IDisposable, and most instances rent their pixel buffer from a shared pool that Dispose returns it to. Not disposing one is safe: it is collected like any other object, with no leak. Disposing matters for throughput under concurrent load, such as a service resizing many uploads at once, where reusing buffers cuts allocation and garbage collection. An AnimatedImage and the frames of its Frames need no disposal.

PeachImage in PeachPDF and PeachDrawing

API reference

The PeachImage API reference documents every public type and member. It sits beside the references for PeachPDF, PeachDrawing.Core, PeachDrawing, PeachDrawing.PDF, PeachDrawing.Svg, PeachDrawing.Skia, PeachDrawing.Win2D, PeachDrawing.Text and PeachBrackets, and the pages of one link to the pages of another where they meet: a RasterCanvas.Save page links to the EncoderOptions it takes here.

License

PeachImage is MIT-licensed. Its license, and the notice for the one algorithm it references from libjpeg-turbo, are in its repository; see the license page for the components PeachPDF itself carries.