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.
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 });
| Mask | Covers |
|---|---|
RectangleMask, EllipseMask | A shape, optionally with rounded corners. Mask.Ellipse() is the one inscribed in the whole image. |
PolygonMask, PathMask | A lasso, or any vector outline - text from a font included, for a knockout. |
BrushMask | Brush strokes, painted and erased in order, as a selective-adjustment brush paints. |
LinearGradientMask | A graduated filter: covered up to its start, fading to nothing at its end. |
RadialGradientMask | A radial filter, rotatable, solid within its hardness and fading to its edge. |
LuminanceRangeMask | Pixels by brightness: recover the highlights, lift the shadows. |
ColorRangeMask | Pixels close to a colour, by perceptual distance. |
FloodMask | The magic wand: the region of similar colour connected to a point, or every pixel of its colour. See retouching and selections. |
BitmapMask | Another image's alpha or luminance, stretched over the photo: the output of a segmentation or background removal model. |
CombinedMask | Two masks united, intersected, subtracted or excluded - a.Union(b). |
MorphedMask | Another 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
| Layer | What it adds |
|---|---|
ImageLayer | Pixels placed in a rectangle, rotated, after a pipeline of their own: a logo, a texture, a sticker. |
FillLayer | A colour over the whole image, usually shaped by a mask: a colour wash, a gradient fade, a duotone. |
AdjustmentLayer | An edit of everything beneath it, which can be reordered, hidden or faded without touching anything else. |
PaintLayer | Brush strokes with hardness and pen pressure, and an eraser that removes the layer's own paint - kept as strokes, not pixels. |
GroupLayer | Other 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.