Imaging — Resize, Convert & Optimize Images

Granit.Imaging provides a fluent image processing pipeline for transformations such as resize, crop, compress, format conversion, and watermarking. Call StripMetadata() in the pipeline to remove GPS coordinates and camera details from uploaded photos (GDPR). The Magick.NET implementation supports JPEG, PNG, WebP, AVIF, GIF, BMP, and TIFF with built-in security hardening (resource limits, format allowlisting, input size validation).

Package structure

DirectoryGranit.Imaging/ Image processing abstractions, fluent pipeline API
- Granit.Imaging.MagickNet Magick.NET implementation (JPEG/PNG/WebP/AVIF/GIF/BMP/TIFF)

Package	Role	Depends on
`Granit.Imaging`	`IImageProcessor`, `IImagePipeline` fluent API	`Granit`
`Granit.Imaging.MagickNet`	`MagickNetImageProcessor` (singleton)	`Granit.Imaging`

Setup

[DependsOn(typeof(GranitImagingMagickNetModule))]
public class AppModule : GranitModule { }

builder.AddGranitImagingMagickNet();

Customize resource limits via the options callback:

builder.AddGranitImagingMagickNet(options =>
{
    options.MaxMemoryBytes = 512 * 1024 * 1024;  // 512 MB (default: 256 MB)
    options.MaxWidthPixels = 8192;                // 8K px (default: 16384)
    options.MaxHeightPixels = 8192;
    options.MaxInputBytes = 25 * 1024 * 1024;     // 25 MB (default: 50 MB)
    options.MaxListLength = 16;                   // GIF frames (default: 32)
});

MagickNetImageProcessor is registered as a singleton — Magick.NET is thread-safe and initializes its native codec once per process.

IImageProcessor

IImageProcessor.Load() opens an image and returns an IImagePipeline. The pipeline holds native resources and must be disposed after use:

public class PatientPhotoProcessor(IImageProcessor imageProcessor)
{
    public async Task<ImageResult> CreateThumbnailAsync(
        Stream sourceImage,
        CancellationToken cancellationToken)
    {
        await using IImagePipeline pipeline = imageProcessor.Load(sourceImage);

        return await pipeline
            .Resize(200, 200, ResizeMode.Crop)
            .StripMetadata()
            .Compress(quality: 80)
            .ConvertTo(ImageFormat.WebP)
            .ToResultAsync(cancellationToken);
    }
}

Pipeline operations

Method	Description
`Resize(width, height, mode)`	Resize with configurable strategy
`Crop(rectangle)`	Crop to rectangular region
`Compress(quality)`	Set output quality (0-100)
`ConvertTo(format)`	Change output format
`Watermark(data, position, opacity)`	Composite watermark overlay
`StripMetadata()`	Remove EXIF, IPTC, XMP metadata (GDPR)
`ToResultAsync()`	Terminal: encode and return `ImageResult`
`SaveToStreamAsync(stream)`	Terminal: encode and write to stream

Resize modes

Mode	Behavior
`Max`	Fit within bounds, preserving aspect ratio (may be smaller than target)
`Pad`	Fit within bounds with transparent padding to exact dimensions
`Crop`	Fill exact dimensions by resizing and center-cropping overflow
`Stretch`	Stretch to exact dimensions (distorts aspect ratio)
`Min`	Resize to minimum bounds covering target dimensions entirely

Convenience methods

await pipeline.SaveAsWebPAsync(cancellationToken);  // ConvertTo(WebP) + ToResultAsync
await pipeline.SaveAsAvifAsync(cancellationToken);   // ConvertTo(AVIF) + ToResultAsync
await pipeline.SaveAsJpegAsync(cancellationToken);   // ConvertTo(JPEG) + ToResultAsync
await pipeline.SaveAsPngAsync(cancellationToken);    // ConvertTo(PNG) + ToResultAsync

Supported formats

Format	Read	Write	Notes
JPEG	Yes	Yes	Lossy, no transparency
PNG	Yes	Yes	Lossless, transparency
WebP	Yes	Yes	Modern lossy/lossless, smaller than JPEG
AVIF	Yes	Yes	Next-gen, best compression ratio
GIF	Yes	Yes	256 colors, animation support
BMP	Yes	Yes	Uncompressed bitmap
TIFF	Yes	Yes	Lossless, medical imaging

StripMetadata() removes all EXIF, IPTC, and XMP metadata from images. This is critical for GDPR compliance: uploaded photos often contain GPS coordinates, camera serial numbers, timestamps, and other personally identifiable information.

await using IImagePipeline pipeline = imageProcessor.Load(uploadedPhoto);
ImageResult sanitized = await pipeline
    .StripMetadata()
    .SaveAsWebPAsync(cancellationToken);

Combining with blob storage

A typical pattern: subscribe to BlobValidatedEvent events to post-process images asynchronously after upload validation. The Wolverine handler downloads the validated blob, applies the image pipeline, and re-uploads the result:

public static class BlobValidatedEventHandler
{
    public static async Task HandleAsync(
        BlobValidatedEvent @event,
        IBlobStorage blobStorage,
        IImageProcessor imageProcessor,
        CancellationToken cancellationToken)
    {
        if (@event.ContainerName != "patient-photos")
            return;

        PresignedDownloadUrl download = await blobStorage
            .CreateDownloadUrlAsync("patient-photos", @event.BlobId,
                cancellationToken: cancellationToken)
            .ConfigureAwait(false);

        // fetch image from download.Url, process with imageProcessor,
        // re-upload thumbnail to "patient-photos-thumbs" container
    }
}

This keeps the upload path fast (202 Accepted) while image processing runs in the background. See Blob Storage domain events for the full event list.

Security

Granit.Imaging.MagickNet applies three layers of defense against malicious image uploads:

Format allowlisting

Before passing any data to the native ImageMagick decoder, Load() validates magic bytes against a safe raster format allowlist (JPEG, PNG, GIF, BMP, TIFF, WebP, AVIF). Dangerous formats that ImageMagick can parse — SVG (SSRF via xlink:href), MSL (file I/O), MVG, PDF, EPS — are rejected before native code executes.

Resource limits

ImageMagick resource limits are configured at startup to prevent decompression bomb attacks (a 42 KB crafted JPEG can inflate to 4+ GB). Default limits:

Limit	Default	Description
`MaxMemoryBytes`	256 MB	Pixel cache memory ceiling
`MaxWidthPixels`	16384	Maximum image width
`MaxHeightPixels`	16384	Maximum image height
`MaxListLength`	32	Maximum frames (GIF animation)
`MaxInputBytes`	50 MB	Pre-decode input size check

Input validation

Resize / Crop: negative or zero dimensions are rejected with ArgumentOutOfRangeException (prevents integer overflow from int → uint cast)
Compress: quality is validated in the 0–100 range
Non-seekable streams: automatically buffered before validation

Public API summary

Category	Key types	Package
Module	`GranitImagingModule`, `GranitImagingMagickNetModule`	—
Processor	`IImageProcessor`, `IImagePipeline`, `ImageResult`	`Granit.Imaging`
Formats	`ImageFormat`, `ImageSize`	`Granit.Imaging`
Modes	`ResizeMode`, `CropRectangle`, `WatermarkPosition`	`Granit.Imaging`
Options	`ImagingMagickNetOptions`	`Granit.Imaging.MagickNet`
Extensions	`AddGranitImagingMagickNet()`	`Granit.Imaging.MagickNet`