Recursive AI

Create a layered image with masks in C#

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

A layer mask hides pixels without erasing them.

Terminal
dotnet add package RecursiveAI.OneImage

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

C#
using OneImage;
using OneImage.Layers;
using Path = OneImage.Drawing.Path;
 
using var doc = new Document(128, 96);
var layer = doc.CreatePixelLayer("paint");
doc.Add(layer);
layer.Pixels.Fill(
    new Rgba32(100, 200, 255, 255));
var mask = layer.AddMask(false, doc.Bounds);
mask.Pixels.Fill(
    new Rgba32(255, 255, 255, 255),
    Path.Circle(64, 48, 30));
mask.Feather = 3;
doc.Render().Save("masked.png");
Console.WriteLine("Wrote masked.png");
Text
Wrote masked.png

Unzip the example, then dotnet run.

The full program

The snippet at the top creates a blue circle on a transparent canvas. The full program creates two solid-color pixel layers, applies a circular feathered mask and Multiply blending, then changes the foreground color. It saves before.png and after.png; no input files are needed.

C#
using OneImage;
using OneImage.Layers;
using Path = OneImage.Drawing.Path;
 
using var doc = new Document(128, 96);
var background = doc.Add(doc.CreatePixelLayer("background"));
background.Pixels.Fill(new Rgba32(200, 200, 200, 255));
var foreground = doc.Add(doc.CreatePixelLayer("foreground"));
foreground.Pixels.Fill(new Rgba32(100, 200, 255, 255));
foreground.BlendMode = BlendMode.Multiply;
var mask = foreground.AddMask(revealAll: false, area: doc.Bounds);
mask.Pixels.Fill(new Rgba32(255, 255, 255, 255),
    Path.Circle(64, 48, 30));
mask.Feather = 3;
Image before = doc.Render();
before.Save("before.png");
var first = before.ToArray<Rgba32>()[48 * 128 + 64];
foreground.Pixels.Fill(new Rgba32(255, 100, 100, 255));
Image after = doc.Render();
after.Save("after.png");
var second = after.ToArray<Rgba32>()[48 * 128 + 64];
Console.WriteLine($"Rendered: {after.Width}x{after.Height}");
Console.WriteLine($"Center before: {first.R},{first.G},{first.B}");
Console.WriteLine($"Center after: {second.R},{second.G},{second.B}");

dotnet run prints:

Text
Rendered: 128x96
Center before: 78,157,200
Center after: 200,78,78

Keep the document alive until rendering and saving finish; it owns disposable pixel canvases and render resources.

Variations

Hide a layer without deleting it.

C#
using OneImage;
using OneImage.Layers;
 
using var doc = new Document(128, 96);
var layer = doc.CreatePixelLayer("paint");
doc.Add(layer);
layer.Pixels.Fill(
    new Rgba32(100, 200, 255, 255));
layer.Opacity = 0.5f;
layer.Visible = false;
doc.Render().Save("hidden.png");
Console.WriteLine("Wrote hidden.png");
Text
Wrote hidden.png

The short answer

Use OneImage.Layers.Document to hold editable layers. Create pixel layers through the document, add them to its root group, paint on their Pixels canvases and call Render() to obtain an image. A LayerMask controls coverage separately from the layer’s color pixels. The core package includes this document model; creating a layered composition does not require a file-format add-on.

The top example makes a masked layer from scratch. The full program goes further: two pixel layers remain independently editable, the upper layer multiplies into the lower one, and the second render reflects a color edit. The output PNGs are rendered images, not files that preserve the editable layer tree.

How do I create an image mask in C#?

Add a mask to the layer with revealAll: false, then paint white into the part you want to show. Black hides the layer and intermediate gray values provide partial coverage. The mask multiplies the layer’s alpha; it does not delete the layer’s stored colors. Disable the mask to see those colors again.

The example passes doc.Bounds so the mask canvas uses document coordinates. Its circle is centered at (64, 48), with radius 30 pixels. Feather = 3 blurs that coverage boundary with a Gaussian standard deviation of three pixels. This is a mask blur, not a blur of the foreground’s color content. Outside this initially hidden mask, coverage is zero.

Mask density can reduce the mask’s effect, while disabling it bypasses it entirely. These controls are useful when the shape is right but the transition needs editing. Mask coverage is evaluated after positioning the layer. That distinction matters when placing a photo at an offset: choose mask coordinates deliberately rather than assuming the mask always starts at the photo’s origin.

How to use layers for editing an image?

Keep the document rather than only its rendered image. Its root group holds layers bottom first, so insertion order determines what is behind what. Each pixel layer has its own canvas, position, visibility, opacity and blend mode. Multiply combines foreground and backdrop colors; normal blending lays the foreground over the backdrop using its alpha and opacity.

In the full program, the background is (200, 200, 200) and the first foreground is (100, 200, 255). At the fully revealed center, Multiply produces (78, 157, 200). Changing the foreground to (255, 100, 100) and rendering again produces (200, 78, 78). The dimensions stay 128 × 96. These are specific sample results, not a promise that every pixel in the feathered boundary has those colors.

Rendering is lazy. Save or read pixels while the document is still alive, as the using declaration does here. A document is single-writer; use a snapshot when a renderer needs a frozen state while editing continues. The snapshot describes a fixed layer state rather than an instruction to share mutable canvases between writers.

Use this approach for compositions that need later edits to layer colors, masks or placement. If all you need is one finished composite, a direct image composition pipeline may be enough. Loading an existing layered file and preserving its format-specific metadata is a separate task from creating and rendering this in-memory document.

All oneimage recipes