---
title: "Create a layered image with masks in C#"
url: https://recursiveai.org/oneimage/cookbook/create-layered-image-document/
description: "A layer mask hides pixels without erasing them."
version: "1.11.1"
---

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

[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/create-layered-image-document/create-layered-image-document.zip)

A layer mask hides pixels without erasing them.

```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;
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](https://recursiveai.org/oneimage/cookbook/create-layered-image-document/create-layered-image-document.zip), 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.

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

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

## Related recipes

- [Convert PSD to PNG](https://recursiveai.org/oneimage/cookbook/psd-to-png/)
- [Add a watermark](https://recursiveai.org/oneimage/cookbook/add-watermark/)

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