NetVips Documentation

Paint operations like DrawCircle and DrawLine are destructive; they modify the input image directly. Using them on shared images can lead to crashes or unpredictable behavior due to the way libvips manages memory and concurrency.

To use these operations safely, use the image.Mutate method. This creates a MutableImage that is unshared and only accessible within the scope of the provided delegate. Once the delegate finishes, the changes are applied back to the original image.

Workflow:

1. Call image.Mutate(mutable => { ... }).
2. Inside the delegate, use mutable (which is a MutableImage) to call draw operations.
3. The MutableImage is only valid inside the delegate.

using var mutated = image.Mutate(mutable =>
{
    for (var i = 0; i <= 100; i++)
    {
        var j = i / 100.0;
        mutable.DrawLine(new[] { 255.0 }, (int)(mutable.Width * j), 0, 0, (int)(mutable.Height * (1 - j)));
    }
});

Most libvips operations are exposed as PascalCase methods on the Image class (e.g., vips_add becomes Add).

Chaining and Memory Management

Operations return a new Image and can be chained. Warning: Chaining does not automatically dispose of temporary intermediate images. This can lead to high memory usage until the next GC cycle.

To manage memory correctly, use one of two patterns:

1. Explicit using statements: Wrap every intermediate image in a using block.
2. VipsArena: Wrap a sequence of operations in a VipsArena block to handle disposal automatically.

Argument Expansion

• Optional Arguments: NetVips uses nullable types to allow omitting optional libvips parameters.
• Constant Expansion: If an operation expects an image but you provide a constant (like an array or a single value), the wrapper automatically expands it to match the required shape (e.g., in Ifthenelse or Bandjoin).

// Pattern 1: Explicit using for memory safety
using var real = image.Real();
using var resultImage = real.Cos();

// Pattern 2: VipsArena for automatic disposal of intermediates
using (var arena = new VipsArena())
{
    var img = Image.NewFromFile("input.jpg");
    img = img.Real().Cos(); // Intermediates are cleaned up by the arena
}

// Constant expansion example: adding an alpha channel
using var rgba = rgb.Bandjoin(255);

You can monitor the progress of image operations by attaching progress handlers to an Image. This is useful for long-running computations where you want to report progress to a UI or cancel the operation if it takes too long.

Using IProgress<int>

You can pass an IProgress<int> to image.SetProgress(progress, cancellationToken). The progress handler will receive the completion percentage.

Using Signals

Alternatively, you can enable progress tracking with image.SetProgress(true) and connect to specific signals using image.SignalConnect. Supported signals include:

• Enums.Signals.PreEval: Before evaluation starts.
• Enums.Signals.Eval: During evaluation.
• Enums.Signals.PostEval: After evaluation completes.

Handlers receive a VipsProgress struct containing fields like Run (run time), Eta (estimated time of arrival), TPels (total pixels), NPels (pixels processed), and Percent (percent complete).

Interrupting Computation

To stop a computation early based on progress, use image.SetKill(true) inside a signal handler.

// Example: Using IProgress and CancellationToken
using var image = Image.Black(1, 500);
var progress = new Progress<int>(percent =>
{
    Console.Write($"\r{percent}% complete");
});

var cts = new CancellationTokenSource();
cts.CancelAfter(5000);

image.SetProgress(progress, cts.Token);
var avg = image.Avg();

// Example: Using Signals and SetKill
image.SetProgress(true);
image.SignalConnect(Enums.Signals.Eval, (img, progress) => 
{
    if (progress.Percent > 50) 
    {
        img.SetKill(true);
    }
});
var avg = image.Avg();

Images in NetVips are immutable. To modify metadata, you must use the Mutate method.

Reading Metadata

• Use image.Get("field-name") to retrieve specific metadata (e.g., iptc-data, exif-ifd0-DateTime).
• Use image.GetFields() to list all available field names.
• Common properties like .Width are available as direct C# properties.

Writing/Modifying Metadata

• Use image.Mutate(mutable => { ... }) to perform changes. Inside the delegate, use mutable.Set(key, value) or mutable.Remove(key).

Cloning Images

Because libvips shares images between parts of your program, you cannot modify an image unless you own the only reference. Use image.Copy(xres, yres) to create a private clone.

// Reading metadata
var iptcString = image.Get("iptc-data");

// Creating a private clone with new resolution
using var newImage = image.Copy(xres: 12, yres: 13);

// Modifying metadata (removing all except icc-profile-data)
using var mutated = image.Mutate(mutable =>
{
    foreach (var field in image.GetFields())
    {
        if (field == "icc-profile-data") continue;
        mutable.Remove(field);
    }
});