PeachImage 0.5.1

PeachImage

Pure .NET image format readers and writers for commonly used image formats on the web.

Targets .NET 8.0 and .NET 10.0. No native interop — every codec is managed code, using modern .NET APIs (System.Runtime.Intrinsics, Span<T>/ReadOnlySpan<T>) for performance instead of P/Invoke.

Status

• JPEG: decode (baseline sequential + progressive, grayscale/YCbCr/RGB/CMYK/YCCK, all standard chroma subsampling, restart markers) and encode (baseline sequential, grayscale/YCbCr) are implemented.
• BMP: decode (OS/2 1.x/2.x and Windows BITMAPINFOHEADER through BITMAPV5HEADER variants, 1/4/8bpp indexed color, 16/24/32bpp direct color, RLE4/RLE8 compression, arbitrary BI_BITFIELDS/BI_ALPHABITFIELDS masks) and encode (24bpp truecolor, 8bpp indexed grayscale with optional RLE8, 32bpp with an explicit alpha channel via BITMAPV4HEADER + BI_BITFIELDS) are implemented, including explicit alpha-channel support on both sides.
• PNG: decode and encode for all 5 color types (grayscale, truecolor, palette, grayscale+alpha, truecolor+alpha) at every valid bit depth (1/2/4/8/16 — including via Gray16/Rgb48/Rgba64 pixel formats), Adam7 interlacing, palette + tRNS transparency (both per-entry and single-color-key), optional opt-in gamma correction (PngDecoderOptions.ScreenGamma), and the common ancillary chunks (gAMA/cHRM/sRGB/iCCP/pHYs/tEXt/zTXt/iTXt/tIME/bKGD). Encoding can build an indexed palette automatically (PngEncoderOptions.ColorMode, default Auto): lossless whenever the source has at most MaxColors (default 256) distinct opaque colors and binary alpha, otherwise falling back to grayscale/truecolor(+alpha) unless ColorMode = Indexed forces palette output via median-cut quantization with optional Floyd-Steinberg dithering (Dither) — the same quantizer GIF encoding uses.
• GIF: decode (GIF87a/GIF89a, interlacing, transparency, multi-frame animation with per-frame disposal methods and the NETSCAPE2.0 loop count via AnimatedImage.Load) and encode (median-cut palette quantization, optional Floyd-Steinberg dithering, animation) are implemented.
• WebP: decode is implemented for both of WebP's bitstream codecs — VP8 (lossy) and VP8L (lossless) — including alpha (ALPH chunk / VP8L's own alpha) and animation (via AnimatedImage.Load, including the loop count) in the RIFF "simple" and "extended" container formats. Encode supports both bitstreams: lossless (VP8L, the default) with predictor-transform selection, palette/color-indexing detection, subtract-green, and a color cache; and lossy (VP8, opt in via WebpEncoderOptions { Lossless = false }) with quality-driven quantization. Alpha-bearing sources always encode as VP8L regardless of Lossless, since lossy WebP's alpha channel isn't implemented yet. Animated WebP encode (VP8X + ANIM/ ANMF, via AnimatedImage.Save) is also implemented, reusing the same per-frame VP8/VP8L encoder as still images; every frame is written full-canvas/non-blending, since AnimatedImageFrame only ever carries a fully composited frame.
• AVIF: decode is implemented for baseline still images — intra-frame AV1, the full in-loop filter chain (deblocking, CDEF, loop restoration), HEIF grid composite images, alpha via the auxiliary-item mechanism, both 8-bit and 10-bit depth, and screen-content tools (palette mode, IntraBC). Animated AVIF, film grain synthesis, gain maps, and 12-bit depth remain unimplemented and throw a clear AvifUnsupportedFeatureException rather than a silently wrong result. Encode is implemented for 8-bit still images (a single av01 item, or two — color plus an iref auxl-referenced monochrome alpha item — for a source with real transparency; no HEIF grid/avis animation on the output side even though decode supports reading them). Both a lossy path (Quality, DCT_DCT, fixed 4:2:0 chroma, every luma block a fixed 8x8 leaf) and a lossless path (Lossless, AV1's Walsh-Hadamard coded-lossless mode, forcing 4x4 transforms, full-resolution 4:4:4 chroma via an identity RGB→YUV matrix, a real cost-based partition-tree size search up to 64x64, and screen-content tools) are supported; lossless round-trips every pixel format exactly — see AvifEncoderOptions.Lossless's remarks. Every leaf gets a real, cost-based intra-mode search (all 13 AV1 intra modes plus angle_delta for the 8 directional ones, plus FILTER_INTRA) for luma; lossless chroma gets the same real mode search (non-lossless chroma stays DC_PRED, since its transform type is mode-dependent and this encoder's non-lossless chroma path doesn't yet implement the non-DCT transforms that searching a real mode there would need). Higher bit depths are rejected with a clear exception rather than silently dropped or downsampled. The forward RGB→YUV conversion, forward transform, and quantizer all use SIMD-tiered kernels (scalar/Vector128/Vector256, matching the JPEG/WebP encoders' own dispatch pattern) and pool their per-block working buffers rather than allocating per block.
• TIFF: decode only (no encode). Covers both byte orders (II/MM), uncompressed/LZW/PackBits compression, 1/2/4/8/16-bit depth, and grayscale (WhiteIsZero/BlackIsZero), RGB (with optional straight or premultiplied alpha), palette, and CMYK color, including the Predictor=2 horizontal-differencing variant LZW-compressed files commonly use. Tiled organization, planar (non-chunky) storage, any compression other than none/LZW/PackBits, BigTIFF, floating-point/signed samples, and photometric interpretations outside that set (YCbCr, LogLuv, Lab) are deliberately out of scope and throw a clear TiffUnsupportedFeatureException rather than a silently wrong result — the goal is correctness on real-world scanner/export-tool output, not every TIFF extension ever specified. An embedded ICC profile (tag 34675) is extracted into Image.Metadata, same as JPEG/PNG.
• JPEG XL: decode only (no encode; CanEncode is false). A from-scratch managed decoder for the ISO/IEC 18181 codestream and ISOBMFF container: lossless and lossy Modular (every predictor including the weighted predictor, RCT, palette/delta-palette and squeeze transforms, progressive passes) and VarDCT (every DCT size from 8x8 to 256x256, the rectangular, IDENTITY, DCT2x2/4x4/4x8 and AFV transforms, chroma-from-luma, adaptive quantization, custom dequantization tables, Gaborish and the edge-preserving filter), patches, splines, synthesized noise, 2x/4x/8x upsampling, DC frames, extra channels (alpha, spot colours rendered like the reference decoder, black/CMYK), premultiplied alpha (returned straight), and JPEG recompressions (YCbCr with any chroma subsampling, grayscale or RGB). Files made by losslessly recompressing a JPEG can also be turned back into that JPEG, byte for byte, with JxlJpegReconstruction (see below). Multi-frame images use full frame blending (cropped frames, every blend mode, reference frames) and decode through AnimatedImage as composited RGBA frames. XYB images are rendered in the file's own colour space: sRGB, any enumerated or custom primaries and white point, linear, gamma, BT.709, DCI, PQ and HLG, or an embedded RGB/gray ICC profile (CMYK images are returned as Cmyk32 with the profile attached; use Image.ConvertToSrgb). Samples above 8 bits decode to the 16-bit formats, floating-point or deeper samples to the new GrayF32/RgbF32/RgbaF32 formats. EXIF and XMP boxes (including Brotli-compressed ones) and the embedded ICC profile are exposed through Image.Metadata, and orientation is applied. Not supported (throws a clear JxlUnsupportedFeatureException): 32-bit integer samples, which the reference decoder rejects too. Grayscale XYB images with a non-D65 white point are rendered as plain luminance. Group decoding, the restoration filters, colour conversion and the splines/noise/upsampling stages run on all cores and use Vector<T> kernels (AVX2 on x64, NEON on ARM64).
• Other formats are not yet implemented. The public API (Image, AnimatedImage for multi-frame formats like GIF) is designed to support them without breaking changes when they're added. Codec selection is internal — there's no format-specific type or registration step in the public API.

See LIBRARY_COMPARISON.md for performance numbers against SkiaSharp.

Installing PeachImage

Install the PeachImage package from nuget.org

dotnet add package PeachImage

Usage

Single-frame images

The format is auto-detected from the file's contents for every operation below — no setup call needed.

using PeachImage;
using PeachImage.Formats.Jpeg;

// Load, inspect, and convert between formats.
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 });

using PeachImage;

// Read dimensions/format without decoding pixel data.
using var stream = File.OpenRead("photo.avif");
ImageInfo info = Image.Identify(stream);
Console.WriteLine($"{info.Width}x{info.Height} {info.PixelFormat} ({info.FormatName})");

using PeachImage;

// Zero-copy access to the decoded pixel buffer.
using var image = Image.Load("photo.png");
Span<byte> pixels = image.GetPixelSpan();
Span<byte> firstRow = image.GetRowSpan(0);

Bytes already in memory (e.g. a buffered upload) load directly — no need to wrap them in a MemoryStream first; a byte[] converts implicitly to ReadOnlySpan<byte>, and decoding reads straight out of that memory with no intermediate copy:

using PeachImage;

byte[] uploadedBytes = await ReadUploadIntoMemoryAsync();
using var image = Image.Load(uploadedBytes);

SaveAsync exists for async I/O call paths. Encoding itself is CPU-bound, not I/O-bound, so only the actual stream/file write is awaited — same as LoadAsync otherwise:

using PeachImage;

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

Disposal & buffer pooling

Image implements IDisposable: most instances rent their pixel buffer from a shared ArrayPool, and Dispose returns it for reuse by the next decode/resize/etc. This is a performance optimization, not a correctness requirement — an un-disposed Image is simply garbage-collected like any other object, with no leak or corruption risk. It matters most under concurrent load (e.g. a service resizing many uploads at once), where reusing pooled buffers meaningfully cuts allocation and GC pressure compared to a fresh buffer per call. AnimatedImage/AnimatedImageFrame don't need disposal: a frame pulled from AnimatedImage.Frames aliases decoder-internal state rather than owning a pooled buffer (disposing it anyway is a safe no-op), and only AnimatedImageFrame.Clone()/Image.Clone() results own one.

Animated images

Multi-frame formats (GIF and WebP) use AnimatedImage instead, with the same load/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 });

Animated WebP works the same way (AnimatedImage.Save(stream, "webp", new WebpEncoderOptions())); WebP's single dispose-to-background bit means FrameDisposalMethod.RestoreToPrevious collapses to DoNotDispose on round-trip through WebP, unlike GIF which represents all three disposal methods natively.

Resizing

Image.Resize/AnimatedImage.Resize support 15 resampling filters via ResamplingFilter — Bicubic is the default; also available: Box, CatmullRom, Hermite, Lanczos2/Lanczos3/Lanczos5/Lanczos8, MitchellNetravali, NearestNeighbor, Robidoux, RobidouxSharp, Spline, Bilinear, and Welch.

using PeachImage;

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

// Bicubic by default.
using var thumbnail = image.Resize(200, 150);

// Or pick a specific filter.
using var sharpened = image.Resize(200, 150, new ResizeOptions { Filter = ResamplingFilter.Lanczos3 });

// ResizeMode.Max treats width/height as a bounding box instead of an exact target: scales down to the
// largest size that fits while preserving aspect ratio, and never upscales — if the source already fits,
// the same instance is returned unchanged rather than allocating a needless copy (so this may end up
// disposing `image` itself — safe, since disposing twice is a no-op, but don't keep using `image`
// afterward without checking for that case first).
using var thumbnailWithinBox = image.Resize(200, 200, new ResizeOptions { Mode = ResizeMode.Max });

AnimatedImage.Resize resizes every frame — lazily, as Frames is enumerated — preserving each frame's duration and disposal method; ResizeOptions.Mode works the same way there too:

using PeachImage;

var animation = AnimatedImage.Load("clip.gif");
var resized = animation.Resize(160, 120, new ResizeOptions { Filter = ResamplingFilter.MitchellNetravali });

using var output = File.Create("resized.gif");
resized.Save(output, "gif");

Recovering the original JPEG from a JPEG XL file

JPEG XL files made from a JPEG (as cjxl does for JPEG input) carry the information needed 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 where a JPEG can be embedded as-is (for example in a PDF) instead of being decoded and encoded again:

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 files that were not made from a JPEG (those decode through Image.Load as usual).

Converting pixel formats

Image.ConvertTo converts between the gray, RGB and RGBA formats at 8-bit, 16-bit and 32-bit float depth (for example an HDR RgbaF32 JPEG XL decode to Rgb24 before encoding it). Integer targets round and clamp, colour to gray uses BT.601 luma, and a target without alpha discards the alpha channel. Values are converted as stored, with no tone mapping. CMYK images go through ConvertToSrgb instead.

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

Building & testing

dotnet build PeachImage.slnx
dotnet test PeachImage.slnx

The first dotnet test run automatically fetches JPEG, BMP, PNG, TIFF, and JPEG XL test corpora (the Imazen codec-corpus conformance sets, image-rs/jpeg-decoder's test assets, and — for BMP — the bmp-conformance subset of codec-corpus, itself generated from Jason Summers' bmpsuite; for PNG — the pngsuite subset of codec-corpus, a mirror of Willem van Schaik's classic PngSuite conformance set; for TIFF — the tiff-conformance subset of codec-corpus, sourced from libtiff's, image-tiff's, and image-rs's own test suites; for JPEG XL — the libjxl conformance test cases and testdata, each decoded and compared with its reference image under the suite's own thresholds) into the gitignored tests/corpus/ directory — no separate script needed. Set PEACHIMAGE_SKIP_CORPUS_FETCH=1 to skip network access; corpus-driven tests report as skipped rather than failing.

TIFF also has a decode-correctness check against ffmpeg's independent TIFF decoder (SkiaSharp has no TIFF codec, so it can't serve as the differential oracle the other formats' corpus tests use). This baseline is checked in (tests/PeachImage.Tests/Formats/Tiff/Corpus/TiffFfmpegReference.baseline.tsv) and regenerating it requires ffmpeg/ffprobe on PATH — set PEACHIMAGE_TIFF_FFMPEG_BASELINE=write and run dotnet test --filter TiffFfmpegReferenceTests, then review the diff before committing. Normal test runs never invoke ffmpeg; they only compare against the checked-in baseline.

AVIF and WebP decode are additionally checked against ffmpeg's own, independent decoders (libdav1d for AVIF; libwebp itself for WebP) via a checked-in pixel baseline (AvifFfmpegReference.baseline.tsv/ WebpFfmpegReference.baseline.tsv) — a real correctness oracle, not just a self-referential "did the decoder's output change" regression check. For AVIF this is the only independent oracle available at all (SkiaSharp, this repo's oracle for the other bitmap formats, has no AVIF codec); for WebP it's a supplementary cross-check alongside the existing SkiaSharp differential, scoped to single-frame VP8L (lossless) files, where the comparison can be exact rather than tolerance-based (see AvifFfmpegReferenceBaseline's and WebpFfmpegReferenceBaseline's own remarks for why AVIF needs a tolerance and WebP's lossy bitstream is out of scope for this specific check). Normal test runs only read the checked-in baseline and never invoke ffmpeg; regenerating it after a corpus or decoder change requires ffmpeg/ffprobe on PATH and PEACHIMAGE_AVIF_FFMPEG_BASELINE=write/PEACHIMAGE_WEBP_FFMPEG_BASELINE=write respectively.

JPEG XL decode is additionally checked against ffmpeg built with libjxl (the reference implementation) as a live oracle: the tests encode synthetic images with libjxl (lossless and lossy, every effort level, 8/16-bit and float input, alpha, HDR transfer functions and wide-gamut primaries) and require the decoder to match libjxl's own decode. They skip when ffmpeg is not on PATH.

With libjxl's reference decoder djxl available (put it on PATH or point PEACHIMAGE_DJXL at it), every file of the JPEG XL corpus, and every JPEG XL file in the test project, is also decoded by both and compared sample for sample at 16-bit (animations as float): almost everything agrees to within one 16-bit unit, and the few known, understood differences have their own tolerances.

Benchmarking

dotnet run -c Release --project bench/PeachImage.Benchmarks

Compares PeachImage's decode/encode throughput against SkiaSharp (a dev-only dependency of the benchmark project only — never referenced by the shipped library). See LIBRARY_COMPARISON.md for the latest results.

License

MIT — see LICENSE. One algorithm's numerical structure (the AAN fast DCT/IDCT butterfly wiring) was referenced from libjpeg-turbo during implementation; see THIRD-PARTY-LICENSES.md.