Recursive AI

Apply an alpha mask to an image in C#

OneImage is a free, open-source image library for .NET from Recursive AI. MIT or Apache-2.0, no native dependencies.

An alpha mask makes a cutout by controlling which pixels stay visible.

Terminal
dotnet add package RecursiveAI.OneImage

Requires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.

C#
using OneImage;
var image = Image.Load("blue.png").AddAlpha();
var mask = Image.Load("mask.png");
image.Composite(mask, alpha:
    AlphaComposition.DestIn).Save("cutout.png");
Console.WriteLine("Wrote cutout.png");

Unzip the example, then dotnet run.

Text
Wrote cutout.png

Both inputs are in the download. blue.png is a 3×1 row of solid blue pixels; mask.png is three white pixels with alpha values 255, 128, 0 from left to right.

The full program

C#
using OneImage;
var image = Image.Load("blue.png").AddAlpha();
var mask = Image.Load("mask.png");
image.Composite(mask, alpha:
    AlphaComposition.DestIn).Save("cutout.png");
Console.WriteLine("Wrote cutout.png");
 
var saved = Image.Load("cutout.png");
var pixels = new Rgba32[3];
saved.CopyPixelsTo<Rgba32>(pixels, new ImageRect(0, 0, 3, 1));
Console.WriteLine($"Alpha left to right: {pixels[0].A}, {pixels[1].A}, {pixels[2].A}");

dotnet run prints:

Text
Wrote cutout.png
Alpha left to right: 255, 128, 0

Without AddAlpha(), an RGB base like blue.png throws ImageOperationException when you use DestIn.

Variations

Shift the mask left. With x: -1, only the first two pixels of the base are under the mask. The third stays opaque. This snippet uses the same files and using OneImage;.

C#
var image = Image.Load("blue.png").AddAlpha();
var mask = Image.Load("mask.png");
image.Composite(mask, x: -1,
    alpha: AlphaComposition.DestIn)
    .Save("shifted.png");

Use a grayscale mask. If your mask is a grayscale PNG without alpha, use its gray channel as the alpha channel. This example generates a three-pixel grayscale mask: white keeps, middle gray fades, and black hides.

C#
using OneImage;
 
var image = Image.Load("blue.png").AddAlpha();
var gray = Image.FromPixels<Gray8>(
    [new(255), new(128), new(0)], 3, 1);
var mask = Image.CombineChannels([gray, gray]);
image.Composite(mask, alpha:
    AlphaComposition.DestIn).Save("from-gray.png");

For a grayscale PNG of your own, load it in place of Image.FromPixels. In CombineChannels, the first image supplies gray and the second supplies alpha.


The short answer

Give the base image an alpha channel with AddAlpha(), then call Composite with the mask as the overlay and alpha: AlphaComposition.DestIn. Save the result to PNG to keep the transparency. Match the mask to the base’s pixel dimensions and leave its offset at (0, 0) to apply it to the entire image.

What is an alpha mask?

An alpha mask stores how much of the base image to keep at each position. The opacity comes from the mask’s alpha channel, the A in RGBA, not from the color you see when you open the mask. In the example, all three mask pixels have the same white RGB color but produce three different opacities. With an opaque base, a mask value of 255 leaves the pixel opaque, 128 keeps it roughly half opaque, and 0 hides it. If the base is already partially transparent, DestIn multiplies its existing alpha by the mask’s coverage; the mask can’t make the base more opaque.

A black-and-white picture with no transparency is not an alpha mask yet. Even a black pixel is fully opaque if it has no alpha channel. If your mask is stored as shades of gray, use the grayscale variation above to copy those shades into alpha; adding an opaque alpha channel alone won’t make its black areas transparent.

How do you apply an alpha mask to an image without painting over it?

In OneImage’s compositing guide, the ordinary Composite call defaults to source-over, which draws the overlay onto the base. DestIn instead keeps the destination (the base image) where the source (the mask) covers it. The mask’s opacity controls coverage but its RGB color doesn’t paint the base. For a faded edge, make the mask’s alpha gradually fall toward zero rather than changing its RGB from white to black.

Check the mask’s dimensions before applying it to a whole image. Composite doesn’t stretch it to fit. If the sizes differ, resize the mask to the base’s width and height first. Pixels outside the overlap are left alone, not cleared. That’s why the offset variation keeps the rightmost blue pixel fully visible. If you want only a small cutout on a large canvas, start with a full-size mask whose alpha is zero everywhere outside the cutout.

All oneimage recipes