---
title: "Apply an alpha mask to an image in C#"
url: https://recursiveai.org/oneimage/cookbook/apply-alpha-mask-to-image/
description: "Apply a same-size PNG mask in C# with OneImage. Keep, fade, or hide pixels by the mask’s alpha channel, then save the cutout as a PNG."
version: "1.11.1"
---

# 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.

[NuGet](https://www.nuget.org/packages/RecursiveAI.OneImage) · [GitHub](https://github.com/recursive-ai-oss/oneimage-csharp) · [Docs](https://recursiveai.org/oneimage/docs/) · [Download example (.zip)](https://recursiveai.org/oneimage/cookbook/apply-alpha-mask-to-image/apply-alpha-mask-to-image.zip)

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

```shell
dotnet add package RecursiveAI.OneImage
```

Requires [.NET 10](https://dotnet.microsoft.com/download/dotnet/10.0) (net10.0); .NET 9 and earlier aren’t supported.

```csharp
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](https://recursiveai.org/oneimage/cookbook/apply-alpha-mask-to-image/apply-alpha-mask-to-image.zip), 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

```csharp
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;`.

```csharp
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.

```csharp
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.

## Related recipes

- [Add a watermark to an image](https://recursiveai.org/oneimage/cookbook/add-watermark/)
- [Draw a vector path on an image](https://recursiveai.org/oneimage/cookbook/draw-vector-path-on-image/)

---

## 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](https://github.com/recursive-ai-oss/oneimage-csharp/blob/a0650f30eb30585a927ff4af0ae7d7e1dc7400cf/docs/guide.md#L204-L216), 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](https://recursiveai.org/oneimage/cookbook/resize-image/) 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.
