Skip to content

Region compositing ​

Five operators combine the regions (silhouettes) of their children. Four are named after Figma's boolean operations; the fifth, atop, is the Porter-Duff operator of that name. The cut mark composes from intersect.

OperatorRegionChildrenSized to
unionA ∪ B ∪ ...2 or moreall the children
intersectA ∩ B ∩ ...2 or moretheir overlap
subtractA − B − ...2 or moreA
exclude(A − B) ∪ (B − A)exactly 2both children
atopA, with B ∩ A drawn over it2 or moreA

An operator reads its children and draws its result. It never draws a child as the child itself.

js
gf.atop([
  gf.rect({ x: 0, y: 0, w: 120, h: 120, fill: gf.color.blue[3] }),
  gf.rect({ x: 40, y: 40, w: 120, h: 120, fill: gf.color.red[3] }),
]).render(root, { w: 160, h: 160 });

Here A is the blue square and B is the red square. B is drawn only where it overlaps A, and the result is sized to A.

Region and paint ​

A child's region is its alpha as drawn: its fill, its stroke and its opacity. A child with .hidden() gives its region and draws no paint.

Without fill or stroke, the operator draws the children's own paint where it keeps them. Where two kept children overlap, union, intersect and atop draw the later child over the earlier one with blendMode.

With fill or stroke, the result is one new shape in that paint, and the children give their regions only. atop takes no fill.

js
gf.intersect({ fill: "#D1E4F6", stroke: "#467DA8", strokeWidth: 2 }, [
  gf.circle({ cx: 90, cy: 90, r: 70 }),
  gf.rect({ x: 80, y: 30, w: 120, h: 120 }),
]).render(root, { w: 220, h: 180 });

A painted intersect of two children draws one exact path when both trace their outlines in opaque paint (a rect with square corners, a circle, an ellipse, a ribbon, a region) and at least one of them is convex. Curves are flattened. Otherwise a fill is drawn over the overlap of the children's regions, and a stroke throws:

intersect: a stroke needs the exact outline of the result, and these operands
give none. ...

union, subtract and exclude have no exact outline yet, so a stroke on them throws too (#1201). The stroke is never quietly dropped or drawn around a box.

A croissant chart paints the intersection of a density curve with each cell of a partition, drawn in by region({ inset }).

Masks ​

A hidden child clips the others to its region. A Filter.luminanceToAlpha() child gives its luminance as its region, so a hidden one is a luminance mask.

js
gf.intersect([
  gf.ellipse({ cx: 80, cy: 60, w: 160, h: 120, fill: "white" }).hidden(),
  gf.rect({ x: 0, y: 0, w: 160, h: 120, fill: gf.color.blue[3] }),
]).render(root, { w: 160, h: 120 });

Signatures ​

ts
union(options?, [A, B, ...]);
intersect(options?, [A, B, ...]);
subtract(options?, [A, B, ...]);
exclude(options?, [A, B]);
atop(options?, [A, B, ...]);

Each child may be a mark or an already-built node, such as a ref(...). Marks are resolved against the incoming data.

Parameters ​

union ​

Draw the union of the regions: A ∪ B ∪ .... With no fill or stroke, each operand draws its own paint, and where two overlap the later one is drawn over the earlier with blendMode. With either, the union is one new shape in that paint. A stroke is an error for now: the result has no exact outline yet (#1201).

OptionTypeDefaultDescription
blendMode"normal" | "multiply" | "screen" | "overlay" | "color" | "luminosity""normal"How a later operand's paint mixes with an earlier one's where they overlap (CSS mix-blend-mode). Unused when the result has a fill or stroke.
fillstring | FieldExprFill color of the result, or a field name or accessor for a color scale. Given, the result is one new shape in this paint, and the operands give shape only. Default none when stroke is given.
strokestring | FieldExprStroke color of the result's outline, or a field name or accessor for a color scale. Default none. It needs an exact outline, which only intersect has: both operands must trace their shape in opaque paint (a rect, ellipse, polygon, ribbon, area or region, or a ref to one; not an image, a text or a group), and at least one of them must be convex. Otherwise it is an error.
strokeWidthnumber1Stroke width in pixels. Without stroke it draws nothing.
opacitynumber1Opacity of the whole result, 0 to 1.

intersect ​

Draw only where every region overlaps: A ∩ B ∩ .... With no fill or stroke, each operand draws its own paint inside the overlap, the later over the earlier with blendMode; a hidden operand gives its shape and no paint, so it clips the others. With either, the overlap is one new shape in that paint: an exact path when both operands trace their outlines in opaque paint and one of them is convex, else a fill of the overlapping ink, while a stroke is then an error.

OptionTypeDefaultDescription
blendMode"normal" | "multiply" | "screen" | "overlay" | "color" | "luminosity""normal"How a later operand's paint mixes with an earlier one's where they overlap (CSS mix-blend-mode). Unused when the result has a fill or stroke.
fillstring | FieldExprFill color of the result, or a field name or accessor for a color scale. Given, the result is one new shape in this paint, and the operands give shape only. Default none when stroke is given.
strokestring | FieldExprStroke color of the result's outline, or a field name or accessor for a color scale. Default none. It needs an exact outline, which only intersect has: both operands must trace their shape in opaque paint (a rect, ellipse, polygon, ribbon, area or region, or a ref to one; not an image, a text or a group), and at least one of them must be convex. Otherwise it is an error.
strokeWidthnumber1Stroke width in pixels. Without stroke it draws nothing.
opacitynumber1Opacity of the whole result, 0 to 1.

subtract ​

Draw the first region with the others removed: A − B − .... With no fill or stroke, A draws its own paint where no other operand is. With either, the result is one new shape in that paint. A stroke is an error for now: the result has no exact outline yet (#1201). The result is sized to A.

OptionTypeDefaultDescription
fillstring | FieldExprFill color of the result, or a field name or accessor for a color scale. Given, the result is one new shape in this paint, and the operands give shape only. Default none when stroke is given.
strokestring | FieldExprStroke color of the result's outline, or a field name or accessor for a color scale. Default none. It needs an exact outline, which only intersect has: both operands must trace their shape in opaque paint (a rect, ellipse, polygon, ribbon, area or region, or a ref to one; not an image, a text or a group), and at least one of them must be convex. Otherwise it is an error.
strokeWidthnumber1Stroke width in pixels. Without stroke it draws nothing.
opacitynumber1Opacity of the whole result, 0 to 1.

exclude ​

Draw where exactly one of two regions is: A − B and B − A. Two operands. With no fill or stroke, each operand draws its own paint where the other is not. With either, the result is one new shape in that paint. A stroke is an error for now: the result has no exact outline yet (#1201).

OptionTypeDefaultDescription
fillstring | FieldExprFill color of the result, or a field name or accessor for a color scale. Given, the result is one new shape in this paint, and the operands give shape only. Default none when stroke is given.
strokestring | FieldExprStroke color of the result's outline, or a field name or accessor for a color scale. Default none. It needs an exact outline, which only intersect has: both operands must trace their shape in opaque paint (a rect, ellipse, polygon, ribbon, area or region, or a ref to one; not an image, a text or a group), and at least one of them must be convex. Otherwise it is an error.
strokeWidthnumber1Stroke width in pixels. Without stroke it draws nothing.
opacitynumber1Opacity of the whole result, 0 to 1.

atop ​

Draw A, and each later operand over it, clipped to A: A, then B ∩ A, .... The later operands mix with A by blendMode. The result is sized to A. It takes no fill: it draws its operands' own paint.

OptionTypeDefaultDescription
blendMode"normal" | "multiply" | "screen" | "overlay" | "color" | "luminosity""normal"How a later operand's paint mixes with an earlier one's where they overlap (CSS mix-blend-mode). Unused when the result has a fill or stroke.
opacitynumber1Opacity of the whole result, 0 to 1.

Arity ​

exclude throws unless it has exactly two children. The other four throw with fewer than two.