Soenneker.Libvips.Util 4.0.79

Soenneker.Libvips.Util

A cross-platform .NET API for the bundled libvips command-line distributions.

Quick start

Install the package:

dotnet add package Soenneker.Libvips.Util

Register it and convert an image:

using Microsoft.Extensions.DependencyInjection;
using Soenneker.Libvips.Util.Abstract;
using Soenneker.Libvips.Util.Registrars;

await using ServiceProvider provider = new ServiceCollection()
    .AddLogging()
    .AddLibvipsUtilAsSingleton()
    .BuildServiceProvider();

ILibvipsUtil libvips = provider.GetRequiredService<ILibvipsUtil>();

await libvips.ConvertToWebp("images/photo.jpg", "images/photo.webp");

That is all the setup required. The package includes libvips for Windows x64 and Linux x64.

Everyday operations

The output extension selects the image format.

Convert

await libvips.Convert("photo.tif", "photo.jpg");
await libvips.ConvertToAvif("photo.jpg", "photo.avif");
await libvips.ConvertToWebp("photo.jpg", "photo.webp");
await libvips.ConvertToJpeg("photo.png", "photo.jpg");
await libvips.ConvertToPng("photo.jpg", "photo.png");

Resize

await libvips.Resize("photo.jpg", "small.webp", width: 1200);
await libvips.Resize("photo.jpg", "thumbnail.webp", width: 400, height: 400);

Images are not enlarged unless you explicitly request it.

Crop

await libvips.Crop("photo.jpg", "crop.jpg", left: 20, top: 20, width: 800, height: 600);
await libvips.SmartCrop("photo.jpg", "avatar.webp", width: 512, height: 512);

Transform

using Soenneker.Libvips.Util.Enums;

await libvips.AutoRotate("phone-photo.jpg", "upright.jpg");
await libvips.Rotate("photo.jpg", "rotated.jpg", LibvipsAngle.D90);
await libvips.Flip("photo.jpg", "mirrored.jpg", LibvipsDirection.Horizontal);
await libvips.Blur("photo.jpg", "blurred.jpg", sigma: 2.5);
await libvips.Sharpen("photo.jpg", "sharpened.jpg");
await libvips.Gamma("photo.jpg", "corrected.jpg");
await libvips.Invert("photo.jpg", "inverted.jpg");
await libvips.Flatten("transparent.png", "flat.jpg", [255, 255, 255]);

Control the output

The typed conversion methods accept format-specific options:

using Soenneker.Libvips.Util.Options;

await libvips.ConvertToAvif("photo.jpg", "photo.avif", new AvifOptions
{
    Quality = 85,
    Effort = 5,
    BitDepth = 10,
    StripMetadata = true
});

await libvips.ConvertToJpeg("photo.png", "photo.jpg", new JpegOptions
{
    Quality = 88,
    Progressive = true,
    OptimizeCoding = true,
    TrellisQuantization = true
});

AvifOptions, WebpOptions, JpegOptions, PngOptions, and TiffOptions expose all saver options reported by the bundled libvips build. Common controls such as metadata retention, ICC profiles, background values, and multipage height live on LibvipsOptions.

Advanced resizing

Use ResizeOptions to control enlargement, cropping, orientation, and linear-light resizing:

using Soenneker.Libvips.Util.Enums;
using Soenneker.Libvips.Util.Options;

await libvips.Resize("photo.jpg", "cover.webp", new ResizeOptions
{
    Width = 1200,
    Height = 630,
    Size = LibvipsSize.Both,
    Crop = LibvipsInteresting.Attention,
    AutoRotate = true
});

Chain operations

A pipeline runs several operations while encoding only the final image:

using Soenneker.Libvips.Util.Pipelines;
using Soenneker.Libvips.Util.Pipelines.Abstract;

using ILibvipsPipeline pipeline = new LibvipsPipeline()
    .AutoRotate()
    .SmartCrop(1200, 630)
    .Sharpen();

await libvips.Process("photo.jpg", "social-card.avif", pipeline);

Pipelines are reusable and safe to inspect asynchronously with GetCount() and GetSteps().

Inspect an image

using Soenneker.Libvips.Util.Dtos;

ImageInfo info = await libvips.Identify("photo.jpg");

Console.WriteLine($"{info.Width}x{info.Height}");
Console.WriteLine($"{info.PixelCount} pixels");
Console.WriteLine(info.Format);

Identify also provides bands, coding, colour interpretation, resolution, loader information, and a case-insensitive metadata dictionary.

Use any libvips operation

For operations without a dedicated method, build a structured command:

using Soenneker.Libvips.Util.Commands;
using Soenneker.Libvips.Util.Commands.Abstract;

ILibvipsCommand command = new LibvipsCommand("colourspace")
    .AddArgument("input.tif")
    .AddArgument("output.jpg")
    .AddArgument("srgb");

IReadOnlyList<string> output = await libvips.Execute(command, log: false);

Prefer Execute over the raw Run method when arguments contain paths or application-supplied values.

Useful behavior

• Missing output directories are created automatically.
• Output is written atomically, so a failed operation does not replace an existing image.
• Input and output may be the same path.
• Paths containing spaces are supported.
• Every asynchronous operation accepts a cancellation token.
• Missing inputs throw FileNotFoundException.
• Invalid options throw an argument exception.
• libvips failures throw InvalidOperationException with the native error output.