Pragmatic.Imaging

Image processing for .NET via a Rust native library.

Pragmatic.Imaging is designed for AOT-friendly server-side image work: decode, encode, resize, crop, rotate, filter, inspect, and generate QR codes without pulling in large managed imaging stacks.

Status: implemented preview package. The runtime is real and tested. The main packaging limitation today is platform coverage: the NuGet package currently ships a win-x64 native binary, while Linux and macOS still require building the native artifact yourself.

Features

• Decode and encode: PNG, JPEG, WebP, AVIF, GIF, BMP, TIFF
• Transform: resize, thumbnail, crop, rotate, flip
• Filters: grayscale, blur, sharpen, brightness, contrast
• QR code generation
• Metadata stripping through re-encoding
• Batch processing with bounded concurrency
• Safety limits through ImagingOptions

Installation

dotnet add package Pragmatic.Imaging

Quick Start

Fluent pipeline

using Pragmatic.Imaging;

using var pipeline = ImagePipeline.Load(imageBytes, ImagingOptions.Strict);

var webp = pipeline
    .Thumbnail(1200, 800)
    .Grayscale()
    .Encode(ImageFormat.WebP, quality: 85);

One-liner helpers

var thumb = await ImageConverter.ThumbnailAsync(
    imageBytes,
    maxWidth: 400,
    maxHeight: 400,
    format: ImageFormat.Jpeg,
    quality: 90);

var info = ImageInfo.FromBytes(imageBytes);
var qr = QrCode.GeneratePng("https://www.pragmaticdesign.net");

Batch processing

var converted = await ImageBatch.ConvertAsync(
    images,
    ImageFormat.WebP,
    quality: 80,
    maxConcurrency: 4);

Safety and Limits

Use ImagingOptions to protect upload and processing paths:

• ImagingOptions.Default
• ImagingOptions.Strict
• ImagingOptions.Relaxed

These limits guard against oversized inputs and decompression-bomb style payloads by capping input bytes and decoded megapixels.

Runtime Notes

Platform	Package artifact
Windows x64	shipped in the package
Linux x64	build native artifact from source
macOS arm64	build native artifact from source

If the native library is missing at runtime, image operations will fail on first use.

DI

AddPragmaticImaging() exists as an extension point for future configuration. The main APIs today are static or fluent and do not require DI.

Architecture

C# API -> LibraryImport P/Invoke -> Rust native library -> image codecs and transforms

Important public entrypoints:

• ImagePipeline
• ImageConverter
• ImageBatch
• ImageInfo
• QrCode
• ImagingOptions

Operational notes

• Native buffer lifecycle. The Rust native backend exposes images via managed wrappers (ImagePipeline, ImageBatch) that own native handles. Dispose them explicitly (using var pipeline = ... or await using) — skipping disposal leaks native memory the .NET GC cannot reclaim. Wrappers are safe inside a single pipeline; concurrent mutation across threads is not supported.

Documentation

• Concepts — architecture, pipeline model, safety limits, thread safety
• Getting Started — five concrete scenarios
• Operations Reference — full catalogue of transforms and filters
• Native Deployment — platforms, AOT, Docker
• Common Mistakes
• Troubleshooting

Samples:

• Pragmatic.Imaging.Samples

License

Part of the Pragmatic.Design ecosystem — see Licensing. Pragmatic.Imaging is licensed under the PolyForm Small Business 1.0.0 license (free for small businesses; commercial license above the threshold).