Skip to content

Layers and masks

A mask says where an edit applies; a layer adds pixels, a colour or an edit on top of the photo, with any of the W3C blend modes. Both are values, like operations, so they get undo, proxy previews and JSON for free.

Try it

Pick a selective edit and a layer. The edit runs only through its mask, in one pass over the rows the mask reaches; the layer is composited on top through its blend mode, opacity and mask.

Live
A generated 900 × 600 scene; every change renders the document again.
Took —
Estimated peak 5.1 MB
The edit as JSON 903 chars

The document

{
  "format": "bmage-document",
  "version": 1,
  "sourceSize": [
    900,
    600
  ],
  "pipeline": [
    {
      "type": "masked",
      "operation": {
        "type": "pipeline",
        "operations": [
          {
            "type": "exposure",
            "ev": -0.8
          },
          {
            "type": "saturation",
            "amount": 0.35
          }
        ]
      },
      "mask": {
        "type": "linearGradient",
        "feather": 12,
        "units": "Relative",
        "start": [
          0,
          0
        ],
        "end": [
          0,
          0.55
        ]
      }
    }
  ],
  "layers": [
    {
      "type": "fill",
      "id": "47257ce2-a64f-4674-a705-773db47096ff",
      "name": "Colour wash",
      "blendMode": "Color",
      "opacity": 0.6,
      "color": "#286edcff"
    }
  ],
  "annotations": []
}

Selective edit


Layer

Selective edits

Masked applies any operation, or a whole sub-pipeline, only where a mask covers the image, fading with its coverage. Where the mask is 0 the pixels are untouched, where it is 255 they are exactly what the edit alone produces. A run of adjustments goes in one pass, and only across the rows and columns the mask can reach, so darkening a sky never touches the ground.

// Darken and enrich the sky, fading out towards the horizon.
pipeline.Masked(Mask.Gradient(new(0, 0), new(0, 0.55f)), sky => sky.Exposure(-0.8f).Saturation(0.35f));

// Spotlight a subject: darken everything outside a soft ellipse.
var subject = new RadialGradientMask(new Vector2(0.3f, 0.55f), 0.22f, 0.38f) { Units = MaskUnits.Relative };
pipeline.Masked(subject.Invert(), around => around.Exposure(-1.2f));

// Recover blown highlights only.
pipeline.Masked(new LuminanceRangeMask(0.8f, 1f), p => p.Exposure(-0.5f));

// A cut-out from a background removal model's matte.
pipeline.ApplyMask(new BitmapMask(matte) { Feather = 1.5f });
MaskCovers
RectangleMask, EllipseMaskA shape, optionally with rounded corners. Mask.Ellipse() is the one inscribed in the whole image.
PolygonMask, PathMaskA lasso, or any vector outline - text from a font included, for a knockout.
BrushMaskBrush strokes, painted and erased in order, as a selective-adjustment brush paints.
LinearGradientMaskA graduated filter: covered up to its start, fading to nothing at its end.
RadialGradientMaskA radial filter, rotatable, solid within its hardness and fading to its edge.
LuminanceRangeMaskPixels by brightness: recover the highlights, lift the shadows.
ColorRangeMaskPixels close to a colour, by perceptual distance.
FloodMaskThe magic wand: the region of similar colour connected to a point, or every pixel of its colour. See retouching and selections.
BitmapMaskAnother image's alpha or luminance, stretched over the photo: the output of a segmentation or background removal model.
CombinedMaskTwo masks united, intersected, subtracted or excluded - a.Union(b).
MorphedMaskAnother mask grown, shrunk or outlined by an exact distance - a.Expand(4), a.Contract(3), a.Border(6).

Every mask takes Feather, Inverted and Opacity, and its coordinates are in pixels or, with Units = MaskUnits.Relative, fractions of the image, so one pipeline fits uploads of any size. ApplyMask multiplies the alpha by a mask instead: a round avatar is .Cover(512, 512).ApplyMask(Mask.Ellipse()).

Layers and blend modes

An ImageDocument composites its layers onto the pipeline's output, bottom first, and draws the annotations over them. A layer has a blend mode, an opacity, an optional mask and a visibility, and the editor previews and exports it like any other edit.

var document = ImageDocument.Create(photo)
    .AddOperation(new CropOperation(0, 0, 1600, 900))
    // A logo, blended into the photo.
    .AddLayer(new ImageLayer { Image = logo, Bounds = new RectangleF(1380, 680, 180, 180), BlendMode = BlendMode.Overlay })
    // A warm glow rising from the horizon.
    .AddLayer(new FillLayer(new Rgba32(255, 120, 40)) { BlendMode = BlendMode.Screen, Opacity = 0.5f, Mask = Mask.Gradient(new(0, 0.75f), new(0, 0.3f)) })
    // More contrast in the shadows only.
    .AddLayer(new AdjustmentLayer(ImagePipeline.Create().Contrast(0.3f)) { Mask = new LuminanceRangeMask(0f, 0.35f) });

using var rendered = new DocumentRenderer().Render(document, photo);

// In the editor, the same through the BmageEditorContext a Toolbar, Panel or Footer receives:
await context.AddLayerAsync(new FillLayer(new Rgba32(40, 110, 220)) { BlendMode = BlendMode.Color, Opacity = 0.4f });
await context.UpdateLayerAsync(layer with { Opacity = value }, transient: true);   // while a slider is dragged
LayerWhat it adds
ImageLayerPixels placed in a rectangle, rotated, after a pipeline of their own: a logo, a texture, a sticker.
FillLayerA colour over the whole image, usually shaped by a mask: a colour wash, a gradient fade, a duotone.
AdjustmentLayerAn edit of everything beneath it, which can be reordered, hidden or faded without touching anything else.
PaintLayerBrush strokes with hardness and pen pressure, and an eraser that removes the layer's own paint - kept as strokes, not pixels.
GroupLayerOther layers, bottom first, shown, hidden, faded, masked and moved as one - groups nest up to ten deep.

Every layer has a Name, a BlendMode, an Opacity, an optional Mask, IsVisible and IsLocked, and can be clipped to the layer below it. The document edits them by id, into and out of groups as well:

document = document
    .UpdateLayer(logo with { Opacity = 0.5f, IsVisible = true })
    .MoveLayer(logo.Id, 0)                       // to the bottom of the stack
    .DuplicateLayer(glow.Id, out var copyId)
    .RemoveLayer(copyId!.Value);

var found = document.FindLayer(logo.Id);         // also inside groups

Groups and clipping

A group passes through by default: its layers blend onto what is beneath exactly as they would without it, an adjustment layer inside it edits everything below, and the group's opacity and mask fade the result back. Set Isolated, or give the group a blend mode other than SourceOver, and its layers composite on their own first - an adjustment inside then edits only the group - and that picture is blended in as one.

ClipToLayerBelow limits a layer to where the nearest unclipped layer below it - its base - has pixels: a texture inside lettering, a colour on one sticker, an adjustment of one layer alone. The Clipped group above is both: a fill clipped to the badge, so only the badge takes the gradient, grouped so the blend mode and opacity apply to the pair.

// Group layers already in the document, then fade them together.
document = document.GroupLayers([plate.Id, caption.Id], out var groupId, name: "Caption");
document = document.UpdateLayer(document.FindLayer(groupId!.Value)! with { Opacity = 0.8f });

document = document.MoveLayerIntoGroup(logo.Id, groupId.Value);   // on top of the group's layers
document = document.MoveLayerOutOfGroup(logo.Id);                 // directly above the group again
document = document.Ungroup(groupId.Value);                       // its layers, where it was

// Or build one: a texture shown only inside lettering, and the pair blended as one picture.
var title = new GroupLayer(
[
    new ImageLayer { Image = lettering, Bounds = titleArea },
    new ImageLayer { Image = woodTexture, Bounds = titleArea, ClipToLayerBelow = true },
]) { Isolated = true, BlendMode = BlendMode.Overlay };

The blend modes are those of CSS mix-blend-mode: Multiply, Screen, Overlay, Darken, Lighten, ColorDodge, ColorBurn, HardLight, SoftLight, Difference, Exclusion, Hue, Saturation, Color and Luminosity, with Add for light effects. ImageCanvas.DrawImage takes them too, and LayerCompositor.Flatten builds an image from layers alone.

Saving and replaying an edit

BmageJson writes a document - pipeline, layers, masks and annotations - as plain JSON, and reads it back as the same edit. Send the edit rather than the pixels, and replay it on the original file at full resolution on the server, or store it and reopen the editor where the user left off. It uses no reflection, so it is safe to trim and to compile ahead of time; images are referenced, never embedded.

// In the browser: the edit, not the pixels, goes to the server.
var json = BmageJson.Serialize(editor.Document!, new BmageJsonOptions
{
    ImageReferences = image => uploads.IdOf(image),
});

// On the server: replay it on the original upload at full resolution.
var document = BmageJson.DeserializeDocument(json, new BmageJsonOptions
{
    ImageResolver = id => uploads.Load(id),
});
using var original = await processor.DecodeAsync(upload);
using var rendered = new DocumentRenderer(fonts).Render(document, original);

// Or reopen the editor where the user left off, through its BmageEditorContext.
await context.RestoreDocumentAsync(document);

Malformed input is refused with an ImageDocumentFormatException that names where it went wrong, such as $.pipeline[2].rectangle. A custom operation, mask, layer or annotation is written once it has a codec (BmageJsonOptions.Add, shown on Pipelines); until then serialising one throws rather than silently dropping a step.

When the images should travel with the edit, BmageProject writes the original, the document and every image it refers to into one .bmage file that reopens with every layer, mask and stroke still editable - Retouching and selections saves and opens one.

An unhandled error has occurred. Reload 🗙