line halo

Author: Fil

docs/marks/line.md

@@ -361,6 +361,12 @@ Points along the line are connected in input order. Likewise, if there are multi
 
 The line mark supports [curve options](../features/curves.md) to control interpolation between points, and [marker options](../features/markers.md) to add a marker (such as a dot or an arrowhead) on each of the control points. The default curve is *auto*, which is equivalent to *linear* if there is no [projection](../features/projections.md), and otherwise uses the associated projection. If any of the **x** or **y** values are invalid (undefined, null, or NaN), the line will be interrupted, resulting in a break that divides the line shape into multiple segments. (See [d3-shape’s *line*.defined](https://d3js.org/d3-shape/line#line_defined) for more.) If a line segment consists of only a single point, it may appear invisible unless rendered with rounded or square line caps. In addition, some curves such as *cardinal-open* only render a visible segment if it contains multiple points.
 
+The line mark supports a **halo** option that draws an outline around each series, increasing legibility when lines overlap. The following halo options are supported:
+
+* **halo** - if true, draws a halo; if a color, sets the halo color; if a number, sets the halo radius
+* **haloColor** - the halo color; defaults to *var(--plot-background)*
+* **haloRadius** - the halo radius in pixels; defaults to 2
+
 ## line(*data*, *options*) {#line}
 
 ```js

src/marks/halo.js

@@ -0,0 +1,51 @@
+import {isColor} from "../options.js";
+
+const defaultColor = "var(--plot-background)";
+const defaultRadius = 2;
+
+let nextHaloId = 0;
+
+function getHaloId() {
+  return `plot-halo-${++nextHaloId}`;
+}
+
+export function applyHalo(selection, {halo}) {
+  if (!halo) return;
+  const {color, radius} = halo;
+  const filters = new WeakMap();
+  selection.attr("filter", function () {
+    const id = getHaloId();
+    filters.set(this, id);
+    return `url(#${id})`;
+  });
+  selection
+    .append("filter")
+    .attr("id", function () {
+      return filters.get(this.parentNode);
+    })
+    .call((filter) =>
+      filter
+        .append("feMorphology")
+        .attr("in", "SourceAlpha")
+        .attr("result", "dilated")
+        .attr("operator", "dilate")
+        .attr("radius", radius)
+    )
+    .call((filter) => filter.append("feFlood").style("flood-color", color))
+    .call((filter) => filter.append("feComposite").attr("in2", "dilated").attr("operator", "in"))
+    .append("feMerge")
+    .call((merge) => {
+      merge.append("feMergeNode");
+      merge.append("feMergeNode").attr("in", "SourceGraphic");
+    });
+}
+
+export function maybeHalo(halo, color, radius) {
+  if (halo === undefined) halo = color !== undefined || radius !== undefined;
+  if (!halo) return false;
+  if (color === undefined) color = isColor(halo) ? halo : defaultColor;
+  else if (!isColor(color)) throw new Error(`Unsupported halo color: ${color}`);
+  if (radius === undefined) radius = typeof halo === "number" && !isNaN(halo) ? halo : defaultRadius;
+  else if (isNaN(+radius)) throw new Error(`Unsupported halo radius: ${radius}`);
+  return {color, radius};
+}

src/marks/line.d.ts

@@ -22,6 +22,23 @@ export interface LineOptions extends MarkOptions, MarkerOptions, CurveAutoOption
    * **fill** if a channel, or **stroke** if a channel.
    */
   z?: ChannelValue;
+
+  /**
+   * Draw a halo around the line to help separate overlapping lines. If true,
+   * draws a halo with the plot background color and a 2px radius. If a color,
+   * uses that color. If a number, uses that radius.
+   */
+  halo?: boolean | string | number;
+
+  /**
+   * The halo’s color; defaults to background color.
+   */
+  haloColor?: string;
+
+  /**
+   * The halo’s radius in pixels; defaults to 2.
+   */
+  haloRadius?: number;
 }
 
 /** Options for the lineX mark. */

src/marks/line.js

@@ -1,4 +1,4 @@
-import {line as shapeLine} from "d3";
+import {group, line as shapeLine} from "d3";
 import {create} from "../context.js";
 import {curveAuto, maybeCurveAuto} from "../curve.js";
 import {Mark} from "../mark.js";
@@ -12,6 +12,7 @@ import {
   groupIndex
 } from "../style.js";
 import {maybeDenseIntervalX, maybeDenseIntervalY} from "../transforms/bin.js";
+import {applyHalo, maybeHalo} from "./halo.js";
 
 const defaults = {
   ariaLabel: "line",
@@ -25,7 +26,7 @@ const defaults = {
 
 export class Line extends Mark {
   constructor(data, options = {}) {
-    const {x, y, z, curve, tension} = options;
+    const {x, y, z, curve, tension, halo, haloColor, haloRadius} = options;
     super(
       data,
       {
@@ -38,6 +39,7 @@ export class Line extends Mark {
     );
     this.z = z;
     this.curve = maybeCurveAuto(curve, tension);
+    this.halo = maybeHalo(halo, haloColor, haloRadius);
     markers(this, options);
   }
   filter(index) {
@@ -50,32 +52,44 @@ export class Line extends Mark {
     }
   }
   render(index, scales, channels, dimensions, context) {
-    const {x: X, y: Y} = channels;
+    const {x: X, y: Y, z: Z} = channels;
     const {curve} = this;
-    return create("svg:g", context)
+    const shape =
+      curve === curveAuto && context.projection
+        ? sphereLine(context.path(), X, Y)
+        : shapeLine()
+            .curve(curve)
+            .defined((i) => i >= 0)
+            .x((i) => X[i])
+            .y((i) => Y[i]);
+
+    const segments = groupIndex(index, [X, Y], this, channels);
+
+    const g = create("svg:g", context)
       .call(applyIndirectStyles, this, dimensions, context)
-      .call(applyTransform, this, scales)
-      .call((g) =>
-        g
+      .call(applyTransform, this, scales);
+
+    // When adding a halo to multiple series, nest by series so each
+    // gets its own halo filter; otherwise render paths directly into g.
+    (this.halo && Z
+      ? g
           .selectAll()
-          .data(groupIndex(index, [X, Y], this, channels))
+          .data(group(segments, (I) => Z[I.find((i) => i >= 0)]))
           .enter()
-          .append("path")
-          .call(applyDirectStyles, this)
-          .call(applyGroupedChannelStyles, this, channels)
-          .call(applyGroupedMarkers, this, channels, context)
-          .attr(
-            "d",
-            curve === curveAuto && context.projection
-              ? sphereLine(context.path(), X, Y)
-              : shapeLine()
-                  .curve(curve)
-                  .defined((i) => i >= 0)
-                  .x((i) => X[i])
-                  .y((i) => Y[i])
-          )
-      )
-      .node();
+          .append("g")
+      : g.datum([, segments])
+    )
+      .call(applyHalo, this)
+      .selectAll()
+      .data(([, d]) => d)
+      .enter()
+      .append("path")
+      .call(applyDirectStyles, this)
+      .call(applyGroupedChannelStyles, this, channels)
+      .call(applyGroupedMarkers, this, channels, context)
+      .attr("d", shape);
+
+    return g.node();
   }
 }