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.
| Operator | Region | Children | Sized to |
|---|---|---|---|
union | A ∪ B ∪ ... | 2 or more | all the children |
intersect | A ∩ B ∩ ... | 2 or more | their overlap |
subtract | A − B − ... | 2 or more | A |
exclude | (A − B) ∪ (B − A) | exactly 2 | both children |
atop | A, with B ∩ A drawn over it | 2 or more | A |
An operator reads its children and draws its result. It never draws a child as the child itself.
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.
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.
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
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).
| Option | Type | Default | Description |
|---|---|---|---|
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. |
fill | string | FieldExpr | Fill 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. | |
stroke | string | FieldExpr | Stroke 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. | |
strokeWidth | number | 1 | Stroke width in pixels. Without stroke it draws nothing. |
opacity | number | 1 | Opacity 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.
| Option | Type | Default | Description |
|---|---|---|---|
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. |
fill | string | FieldExpr | Fill 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. | |
stroke | string | FieldExpr | Stroke 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. | |
strokeWidth | number | 1 | Stroke width in pixels. Without stroke it draws nothing. |
opacity | number | 1 | Opacity 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.
| Option | Type | Default | Description |
|---|---|---|---|
fill | string | FieldExpr | Fill 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. | |
stroke | string | FieldExpr | Stroke 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. | |
strokeWidth | number | 1 | Stroke width in pixels. Without stroke it draws nothing. |
opacity | number | 1 | Opacity 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).
| Option | Type | Default | Description |
|---|---|---|---|
fill | string | FieldExpr | Fill 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. | |
stroke | string | FieldExpr | Stroke 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. | |
strokeWidth | number | 1 | Stroke width in pixels. Without stroke it draws nothing. |
opacity | number | 1 | Opacity 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.
| Option | Type | Default | Description |
|---|---|---|---|
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. |
opacity | number | 1 | Opacity of the whole result, 0 to 1. |
Arity
exclude throws unless it has exactly two children. The other four throw with fewer than two.
