enclose
Draws an outline around a set of nodes, under them. The outline is a member of the Shape family: the padded bounding box (Shape.box(), the default), the smallest ellipse around them (Shape.oval()), the padded members with arc corners (Shape.fillet()), or a smooth region (Shape.blob(), Shape.hull(), Shape.spine()). Like line and ribbon, it reads geometry from nodes that are already placed, and it has a combinator form and a bag form. It also has a flow-step form.
const beaks = penguins.filter((d) => d["Beak Depth (mm)"] != null);
gf.chart(beaks, { axes: true })
.flow(gf.scatter({ x: "Beak Length (mm)", y: "Beak Depth (mm)" }))
.mark(gf.circle({ r: 2.5, fill: "Species" }).name("points"))
.layer(
gf
.chart(gf.selectAll("points"))
.flow(gf.group({ by: "Species" }))
.mark(
gf.enclose({
shape: gf.Shape.hull(),
padding: 6,
fill: "Species",
fillOpacity: 0.2,
})
)
)
.render(root, { w: 420, h: 320 });Signature
// Combinator form: around the given children.
enclose(options, [child1, child2, ...]);
// Bag form: around the refs a chart's data holds.
chart(selectAll(name)).mark(enclose(options));
// Flow-step form: around each group's subtree.
chart(data).flow(op1, enclose(options), op2).mark(mark);In the combinator form, a fresh child (a mark or an operator) is laid out the way layer lays out its children, and the outline is drawn around it. A ref(...) child, or an operand of a .relate() callback, is enclosed where it already is, without being moved.
In the bag form, the members are the refs of the chart's data. A flow(group({ by })) before the mark draws one outline per group, and fill, stroke or padding may name a field that is constant within each group.
In the flow-step form, enclose(options) sits between two operators in .flow(...). Each group's subtree is its one fresh child, so the operator before it lays out the outlined group: a pack packs the outline, and an outer enclose hugs it. The paint and padding are read once per group, as in the bag form. The same call is the bag form in .mark(...).
gf.chart(seafood)
.flow(
gf.pack({ by: "lake", spacing: 6 }),
gf.enclose({ shape: gf.Shape.fillet(), padding: 4, fill: "none" }),
gf.pack({ spacing: 2 })
)
.mark(gf.circle({ r: 12, fill: "species" }))
.render(root, { w: 420, h: 420 });// Fresh children: the box is laid out with them.
enclose(
{
padding: 20,
fill: "#252150",
stroke: "none",
shape: Shape.box({ rx: 16 }),
},
[
spread(
{ dir: "x", spacing: 50, alignment: "middle" },
planets.map((d) => circle(d))
),
]
);
// Operands of .relate(): a set that holds a and c but not b.
layer([a, b, c]).relate(({ a, b, c }) => [
enclose({ shape: Shape.spine(), avoiding: [b], clearance: 6, padding: 22 }, [
a,
c,
]),
]);A member is read by its shape: a circle is a disc, a line is its segments at its stroke width, and any other node is its bounding box. The outline paints under the members.
avoiding lists the nodes the outline keeps out of, for every shape: a list of nodes or refs, or one selectAll(name). The outline is cut so that it stays clearance (by default, the padding) from each of them. A box that avoids nodes is drawn as its cut outline, not as a rectangle.
A fresh member with no size of its own, such as a treemap or a region, fills the space it is given, so there is nothing to hug. Then enclose works the other way round: the outline is the space itself (Shape.box()) or the oval inscribed in it (Shape.oval()), and it hands the outline, drawn in by padding, down to the member as the shape to fill. Inside a Voronoi cell of a treemap, the space is that cell, so Shape.box() draws the cell and Shape.oval() the part of the oval inside it. Shape.fillet() and Shape.blob() hug the members, so around a member with no size they are an error that names Shape.box() and Shape.oval().
// A Voronoi treemap in a circle: the treemap fills the oval.
chart(countryPopulations, { axes: false, w: 480, h: 480 })
.flow(
enclose({ shape: Shape.oval, fill: "none" }),
treemap({ by: "continent", size: "pop", spacing: 5, tile: Tile.voronoi }),
treemap({ size: "pop", spacing: 1, tile: Tile.voronoi })
)
.mark(region({ fill: "continent" }));Parameters
Draw an outline around a set of nodes, under them: their padded bounding box (Shape.box(), the default), the smallest ellipse around them (Shape.oval()), the padded members with arc corners (Shape.fillet()), or a smooth region (Shape.blob(), Shape.hull(), Shape.spine()), kept out of the nodes in avoiding. Combinator form enclose(opts, children): fresh children are laid out as layer lays them out, and ref(...) children are enclosed where they already are. Bag form over a ref array (chart(selectAll(name)).mark(enclose(opts))), one outline per group when the flow groups the refs. Flow-step form .flow(..., enclose(opts), ...): an outline around each group's subtree, laid out with it, so the operator above packs or places the outlined group and an outer enclose hugs this outline; in a chart's operators, its IR is this mark's.
| Option | Type | Default | Description |
|---|---|---|---|
filter | Filter | string | A filter over this whole drawing: a Filter strategy (Filter.grayscale(), Filter.luminanceToAlpha()) or a raw CSS filter string ("blur(2px)", "url(#shadow)"). | |
padding | number | string | FieldExpr | 2 | Pixels between the members and the outline: a number, or a field name or accessor read once per enclosed group (constant within the group). For a blob or fillet, the distance from each member's own outline (around a line's whole length). Around a member with no size of its own, how far inside the outline the member's shape is. |
shape | Shape | The outline, made by a call in the Shape family: Shape.box({rx, ry}) draws the padded bounding box with rounded corners (the default). Shape.oval() draws the smallest-area ellipse around the padded members, rotated to follow them. Shape.fillet({radius, neck, holes}) draws the padded members with every concave corner a circular arc of radius, the contour of a bubble treemap. Shape.blob({convexity, connection, neck, holes, separate}) draws a smooth region: the members split into pieces by connection, each joined by a spanning tree of tubes and filled up to convexity (0 the tree, 1 the padded hull, 2 the oval). Shape.hull() is a blob with convexity 1 and neck 1 (the padded convex hull, rounded), and Shape.spine() is a blob with convexity 0 (the spanning tree of tubes alone); any option overrides the preset. Around a fresh member with no size of its own (a treemap, a region), the outline is the space it is given: Shape.box() is that space (a treemap's Voronoi cell, when it is in one) and Shape.oval() the oval inscribed in it, and the member fills the outline; Shape.fillet() and Shape.blob() are an error there. | |
avoiding | NodeSelectionIR | Nodes the outline stays out of, whatever its shape: a list of nodes or refs, or a selectAll(name) selection. A listed node that is also a member is ignored. The outline is cut around each avoided node grown by clearance, never into the padded members, and a blob's or fillet's links route around them. | |
clearance | number | Pixels kept between the outline and each avoided node, and between a piece of a blob with separate and the other pieces' padded members and links. Default: padding. | |
fill | string | FieldExpr | Fill color of the outline, or a field name or accessor for a color scale (constant within the enclosed group). | |
stroke | string | FieldExpr | Stroke color of the outline, or a field name or accessor for a color scale (constant within the enclosed group). Default a light gray. | |
strokeWidth | number | 1 | Stroke width in pixels. |
strokeDasharray | string | Raw SVG stroke-dasharray (e.g. "4 2") for a dashed outline. | |
opacity | number | 1 | Opacity of the whole outline, fill and stroke, 0 to 1. |
fillOpacity | number | Opacity of the fill alone, 0 to 1. The stroke keeps opacity, so a tinted region can keep a full-strength outline. |
shape takes a member of the Shape family.
