@tangram.gl/basemap-layers 0.0.0-stage → 0.0.1

package/src/line-blur-extension.ts

@@ -0,0 +1,237 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {LayerExtension} from '@deck.gl/core';
+import type {Layer, UpdateParameters} from '@deck.gl/core';
+import type {ShaderModule} from '@luma.gl/shadertools';
+
+export type LineBlurExtensionOptions = {
+  /**
+   * Reads `getBlur` per path, from an attribute. Otherwise `getBlur` must be a constant, which a
+   * uniform carries: a `PathLayer` with `PathStyleExtension`'s path dashes and offsets already
+   * uses all 16 vertex attributes that WebGL2 guarantees, and does not link with one more.
+   */
+  perFeature: boolean;
+};
+
+type LineBlurProps = {
+  blur: number;
+  gapOffset: number;
+  gapSide: number;
+};
+
+const UNIFORMS = `\
+layout(std140) uniform lineBlurUniforms {
+  float blur;
+  float gapOffset;
+  float gapSide;
+} lineBlur;
+`;
+
+/**
+ * Adds `getBlur` to the `PathLayer`s of a layer drawn with `antialiasing` (for a `GeoJsonLayer`,
+ * `lineAntialiasing`): per path, the CSS pixels over which the edges fade out, as MapLibre GL JS
+ * draws `line-blur`, and, with a blur of 0, every line's antialiasing. MapLibre fades each edge
+ * linearly from the edge, which its antialiasing moves out by half a device pixel, to `blur` plus
+ * one device pixel inside it. On deck.gl's antialiased stroke alone, that fade leaves a line
+ * narrower than a pixel too faint, so lines without an offset (which is measured in widths) are
+ * drawn half a device pixel wider on each side, with their dashes scaled back to the line's width,
+ * and faded from their own edge. The fade follows round caps and joins, as in MapLibre. Other
+ * sublayers, and
+ * layers drawn without `antialiasing`, are left unchanged. WebGL only; on WebGPU lines draw
+ * without blur.
+ *
+ * `blurGapSide` serves the two lines of a `line-gap-width`, drawn with `PathStyleExtension`'s
+ * offsets: 1 or -1, the side of the gap's center that this line is on (as `getLineOffset`'s
+ * `side`), with `blurGapOffset` the CSS pixels of the gap's center from the path (`line-offset`).
+ * The line draws nothing past the gap's center, so that where a blur wider than half the gap makes
+ * the two lines overlap, their fades do not draw over each other. MapLibre draws the gap as one
+ * stroke whose fade is symmetric about its center, so each line draws its half. The default 0
+ * clips nothing, and neither does a path whose gap is 0: its one line is centered on the gap's
+ * center (`getLineOffset`), which the shader tells per path from the offset and width it already
+ * has, so a gap that is 0 at a zoom or for a feature needs no attribute of its own.
+ */
+export class LineBlurExtension extends LayerExtension<LineBlurExtensionOptions> {
+  static extensionName = 'LineBlurExtension';
+  static defaultProps = {
+    getBlur: {type: 'accessor', value: 0},
+    blurGapSide: 0,
+    blurGapOffset: 0
+  };
+
+  constructor({perFeature = false}: Partial<LineBlurExtensionOptions> = {}) {
+    super({perFeature});
+  }
+
+  initializeState(this: Layer, context: unknown, extension: this) {
+    if (!isBlurredPathLayer(this) || !extension.opts.perFeature) {
+      return;
+    }
+    this.getAttributeManager()?.addInstanced({
+      instanceLineBlur: {size: 1, accessor: 'getBlur', defaultValue: 0}
+    });
+  }
+
+  updateState(this: Layer<any>, params: UpdateParameters<Layer<any>>, extension: this) {
+    if (!isBlurredPathLayer(this)) {
+      return;
+    }
+    const {getBlur, blurGapSide, blurGapOffset} = this.props;
+    const lineBlur: LineBlurProps = {
+      blur: extension.opts.perFeature ? 0 : Math.max(0, Number(getBlur) || 0),
+      gapOffset: Number(blurGapOffset) || 0,
+      gapSide: Math.sign(Number(blurGapSide) || 0)
+    };
+    this.setShaderModuleProps({lineBlur});
+  }
+
+  getShaders(this: Layer, extension: this) {
+    if (!isBlurredPathLayer(this)) {
+      return {};
+    }
+    // deck.gl appends these to the layer's and other extensions' code for the same hooks.
+    // `edgePixels` is PathLayer's signed distance to the stroke's edge in device pixels, and
+    // `fragColor.a` already carries its `smoothedge(0.0, edgePixels)` coverage, which this
+    // replaces with MapLibre's linear fade. `smoothedge` is 0 only where MapLibre's fade is 0.
+    // The fade measures its own distances, as `edgePixels` does but in Euclidean pixels: the
+    // length of the coordinate's screen gradient rather than `fwidth`, which is up to 1.41 times
+    // longer on diagonal lines and round caps, where it would shorten the fade. The body uses
+    // `vPathPosition.x` rather than its absolute value, whose gradient falls to 0 across the
+    // middle of the stroke, where a blur wider than the line keeps it translucent in MapLibre.
+    // Gradients are taken before any fragment of the quad is discarded.
+    const lineBlur: ShaderModule<LineBlurProps> = {
+      name: 'lineBlur',
+      inject: {
+        'vs:#decl': `${UNIFORMS}
+#ifdef LINE_BLUR_PER_FEATURE
+in float instanceLineBlur;
+#endif
+out float lineBlur_blur;
+out float lineBlur_gapCenter;
+out float lineBlur_gapSide;
+out float lineBlur_padPixels;
+// The line's width over the drawn stroke's (see DECKGL_FILTER_SIZE).
+float lineBlur_widthRatio = 1.0;
+`,
+        // MapLibre's fade reaches half a device pixel past the line. The stroke is drawn that much
+        // wider on each side, and the fade measured from the line's own edge, so that a line
+        // narrower than a pixel draws as in MapLibre: with multisampling, the fade would otherwise
+        // be cut at the stroke's edge. Dashes, measured in the drawn width, are scaled back in
+        // #main-end. Offsets are measured in it too, so offset lines keep their width.
+        'vs:DECKGL_FILTER_SIZE': `
+  lineBlur_padPixels = 0.0;
+#ifndef PATH_STYLE_OFFSET
+  if (size.x > 0.0) {
+    // \`size\` is half the stroke's width.
+    vec2 lineBlur_pad = vec2(0.5 / project.devicePixelRatio);
+    lineBlur_pad = path.billboard ? lineBlur_pad : project_pixel_size(lineBlur_pad);
+    lineBlur_widthRatio = size.x / (size.x + lineBlur_pad.x);
+    size.xy += lineBlur_pad;
+    lineBlur_padPixels = 0.5;
+  }
+#endif
+`,
+        'vs:#main-end': `
+#if defined(DASH_ENABLED) && !defined(PATH_STYLE_OFFSET)
+  // PathStyleExtension measured the dashes in the drawn stroke's widths, MapLibre in the line's.
+  // Offset lines are not widened, and keep the dash phase that the offset shader corrects.
+  vDashArray *= lineBlur_widthRatio;
+#ifdef HIGH_PRECISION_DASH
+  float lineBlur_dashUnit = vDashArray.x + vDashArray.y;
+  float lineBlur_dashPeriod = pathStyle.dashAlignMode == 0.0
+    ? lineBlur_dashUnit
+    : vDashPathLength / max(round(vDashPathLength / max(lineBlur_dashUnit, 0.0001)), 1.0);
+  vDashOffset = lineBlur_dashPeriod > 0.0 ? mod(dashOffsetAndLength.x, lineBlur_dashPeriod) : 0.0;
+#endif
+#endif
+#ifdef LINE_BLUR_PER_FEATURE
+  lineBlur_blur = instanceLineBlur;
+#else
+  lineBlur_blur = lineBlur.blur;
+#endif
+  // In device pixels.
+  lineBlur_blur *= project.devicePixelRatio;
+  // The gap's center across the stroke, in the units of vPathPosition.x: half the drawn width
+  // from the stroke's center. PathStyleExtension puts the path at 2 * instanceOffsets, and
+  // vPathPosition.x runs the other way to the offset.
+  lineBlur_gapCenter = 0.0;
+  lineBlur_gapSide = 0.0;
+#ifdef PATH_STYLE_OFFSET
+  if (widthPixels.x > 0.0) {
+    lineBlur_gapCenter = 2.0 * instanceOffsets - lineBlur.gapOffset / widthPixels.x;
+    // A path without a gap draws one line, centered on the gap's center: it is not clipped. A
+    // line of a gap is always off the center, by at least 0.01 pixels (MIN_GAP_LINE_CENTER).
+    if (abs(lineBlur_gapCenter) * widthPixels.x > 0.001) {
+      lineBlur_gapSide = lineBlur.gapSide;
+    }
+  }
+#endif
+`,
+        'fs:#decl': `${UNIFORMS}
+in float lineBlur_blur;
+in float lineBlur_gapCenter;
+in float lineBlur_gapSide;
+in float lineBlur_padPixels;
+`,
+        'fs:#main-start': `
+  float lineBlur_bodyGradient = max(
+    length(vec2(dFdx(vPathPosition.x), dFdy(vPathPosition.x))), 1e-6
+  );
+  float lineBlur_cornerCoord = length(vCornerOffset);
+  float lineBlur_cornerGradient = max(
+    length(vec2(dFdx(lineBlur_cornerCoord), dFdy(lineBlur_cornerCoord))), 1e-6
+  );
+`,
+        'fs:#main-end': `
+#ifdef ANTIALIASING
+  // The gap's other line draws past its center.
+  if (lineBlur_gapSide * (vPathPosition.x - lineBlur_gapCenter) > 0.0) {
+    discard;
+  }
+  float lineBlur_coverage = smoothedge(0.0, edgePixels);
+  // In device pixels, as edgePixels. A round cap or join is bounded by both its circle and the
+  // stroke's width, as PathLayer bounds it.
+  float lineBlur_edgePixels = (1.0 - abs(vPathPosition.x)) / lineBlur_bodyGradient;
+  if (isRound && isCorner) {
+    lineBlur_edgePixels = min(
+      lineBlur_edgePixels, (1.0 - lineBlur_cornerCoord) / lineBlur_cornerGradient
+    );
+  }
+  lineBlur_edgePixels -= lineBlur_padPixels;
+  // Picking colors keep the coverage PathLayer gave them.
+  if (lineBlur_coverage > 0.0 && !bool(picking.isActive)) {
+    fragColor.a *= clamp(
+      (lineBlur_edgePixels + 0.5) / (lineBlur_blur + 1.0), 0.0, 1.0
+    ) / lineBlur_coverage;
+  }
+#endif
+`
+      },
+      uniformTypes: {blur: 'f32', gapOffset: 'f32', gapSide: 'f32'}
+    };
+    return {
+      modules: [lineBlur],
+      defines: extension.opts.perFeature ? {LINE_BLUR_PER_FEATURE: true} : {}
+    };
+  }
+}
+
+function isBlurredPathLayer(layer: Layer): boolean {
+  return layer.context.device.type !== 'webgpu' && 'pathTesselator' in (layer.state || {});
+}
+
+/**
+ * The width to draw each of a gap's two lines with, so that their fades fall where MapLibre's do:
+ * MapLibre draws the two lines as one stroke whose inner edges fade into the gap and whose outer
+ * edges fade inward, each over the same `blur`. Drawing each line `blur` wider, and `blur / 2`
+ * closer to the gap (see `getLineOffset`), turns that into a fade inward from both of the line's
+ * edges. Lines without a gap, or without width, keep their width.
+ */
+export function getBlurredLineWidth(width: number, gapWidth: number, blur: number): number {
+  return width > 0 && gapWidth > 0 ? width + Math.max(0, blur) : width;
+}

package/src/line-glyphs.ts

@@ -0,0 +1,364 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/**
+ * Glyphs of a label along a line, each placed on the line and turned to the segment it lands on,
+ * as MapLibre GL JS's `placeGlyphsAlongLine`, `placeFirstAndLastGlyph` and `placeGlyphAlongLine`
+ * (symbol/projection.ts) place them in the label plane. Here the label plane is the map plane at
+ * the current zoom: the line, measured in pixels at the placement zoom, is scaled about the anchor.
+ *
+ * Coordinates are pixels with y pointing down. Angles returned are counter-clockwise on screen, in
+ * degrees, as deck.gl's `getAngle` takes them.
+ */
+
+/** A line a label is placed along, and where on it the label's anchor lies. */
+export type LabelLine = {
+  /** The line's vertices, `x, y` pairs in pixels at the placement zoom. */
+  points: ArrayLike<number>;
+  /** The segment the anchor lies on: from vertex `segment` to `segment + 1`. */
+  segment: number;
+  /** The anchor's position along that segment, from 0 to 1. */
+  t: number;
+};
+
+export type LineGlyphOptions = {
+  /**
+   * Each glyph's advance centre along the label, in pixels at the current zoom, from the anchor
+   * (MapLibre's `glyphOffsetArray` times the font scale).
+   */
+  offsets: ArrayLike<number>;
+  /** The label's `text-offset` in pixels: along the line, and across it (MapLibre's `lineOffset`). */
+  lineOffsetX?: number;
+  lineOffsetY?: number;
+  /** Pixels at the current zoom per pixel of `line.points`. */
+  scale: number;
+  /** Whether the label reads against the line's direction (turned upright). */
+  flip: boolean;
+};
+
+/** Where each glyph of a label is drawn, from the anchor, and the path its collision follows. */
+export type LineGlyphs = {
+  /** For each glyph: `dx, dy` in pixels from the anchor, and its angle. */
+  glyphs: Float32Array;
+  /**
+   * The path from the first glyph to the last along the line, `x, y` pairs in pixels from the
+   * anchor, as MapLibre builds the collision circles of a label along a line.
+   */
+  path: number[];
+};
+
+type PlacedGlyph = {x: number; y: number; angle: number; path: number[]};
+
+/** The anchor's position and the projected line, relative to the anchor and scaled. */
+type Projection = {
+  vertex: (index: number) => [number, number];
+  count: number;
+};
+
+function getProjection(line: LabelLine, scale: number): Projection {
+  const {points, segment, t} = line;
+  const ax = points[segment * 2] + (points[segment * 2 + 2] - points[segment * 2]) * t;
+  const ay = points[segment * 2 + 1] + (points[segment * 2 + 3] - points[segment * 2 + 1]) * t;
+  return {
+    vertex: index => [(points[index * 2] - ax) * scale, (points[index * 2 + 1] - ay) * scale],
+    count: points.length / 2
+  };
+}
+
+/** `transformToOffsetNormal`: the segment's normal, of length `offset * direction`. */
+function getOffsetNormal(
+  dx: number,
+  dy: number,
+  offset: number,
+  direction: number
+): [number, number] {
+  const length = Math.hypot(dx, dy);
+  const k = (offset * direction) / length;
+  // `Point.perp()` is (-y, x).
+  return [-dy * k, dx * k];
+}
+
+/** `findLineIntersection`: where lines a1-a2 and b1-b2 meet, or null if parallel. */
+function intersectLines(
+  a1: number[],
+  a2: number[],
+  b1: number[],
+  b2: number[]
+): [number, number] | null {
+  const aDx = a2[0] - a1[0];
+  const aDy = a2[1] - a1[1];
+  const bDx = b2[0] - b1[0];
+  const bDy = b2[1] - b1[1];
+  const denominator = bDy * aDx - bDx * aDy;
+  if (denominator === 0) {
+    return null;
+  }
+  const ua = (bDx * (a1[1] - b1[1]) - bDy * (a1[0] - b1[0])) / denominator;
+  return [a1[0] + ua * aDx, a1[1] + ua * aDy];
+}
+
+/**
+ * `placeGlyphAlongLine`: walks the line from the anchor until the distance travelled equals the
+ * glyph's offset, on the line moved `lineOffsetY` across it when that is set. Returns null when the
+ * glyph does not fit on the line.
+ */
+function placeGlyph(
+  projection: Projection,
+  anchorSegment: number,
+  offsetX: number,
+  lineOffsetX: number,
+  lineOffsetY: number,
+  flip: boolean,
+  offsets: Map<number, [number, number]>
+): PlacedGlyph | null {
+  const combinedOffsetX = flip ? offsetX - lineOffsetX : offsetX + lineOffsetX;
+  let direction = combinedOffsetX > 0 ? 1 : -1;
+  let angle = 0;
+  if (flip) {
+    direction *= -1;
+    angle = Math.PI;
+  }
+  if (direction < 0) {
+    angle += Math.PI;
+  }
+  let currentIndex = direction > 0 ? anchorSegment : anchorSegment + 1;
+  const anchor: [number, number] = [0, 0];
+  let currentVertex = anchor;
+  let previousVertex = anchor;
+  let offsetIntersectionPoint: [number, number] | undefined;
+  let offsetPreviousVertex: [number, number] | undefined;
+  let distanceFromAnchor = 0;
+  let currentSegmentDistance = 0;
+  const absOffsetX = Math.abs(combinedOffsetX);
+  const path: number[] = [];
+  let segmentX = 0;
+  let segmentY = 0;
+
+  while (distanceFromAnchor + currentSegmentDistance <= absOffsetX) {
+    currentIndex += direction;
+    if (currentIndex < 0 || currentIndex >= projection.count) {
+      return null;
+    }
+    distanceFromAnchor += currentSegmentDistance;
+    previousVertex = currentVertex;
+    offsetPreviousVertex = offsetIntersectionPoint;
+    currentVertex = projection.vertex(currentIndex);
+    if (lineOffsetY === 0) {
+      path.push(previousVertex[0], previousVertex[1]);
+      segmentX = currentVertex[0] - previousVertex[0];
+      segmentY = currentVertex[1] - previousVertex[1];
+    } else {
+      let normal: [number, number];
+      const dx = currentVertex[0] - previousVertex[0];
+      const dy = currentVertex[1] - previousVertex[1];
+      if (dx === 0 && dy === 0) {
+        // The anchor lies on a vertex: the next segment gives the normal.
+        const next = projection.vertex(currentIndex + direction);
+        normal = getOffsetNormal(
+          next[0] - currentVertex[0],
+          next[1] - currentVertex[1],
+          lineOffsetY,
+          direction
+        );
+      } else {
+        normal = getOffsetNormal(dx, dy, lineOffsetY, direction);
+      }
+      offsetPreviousVertex ||= [previousVertex[0] + normal[0], previousVertex[1] + normal[1]];
+      offsetIntersectionPoint = getOffsetIntersection(
+        projection,
+        currentIndex,
+        normal,
+        currentVertex,
+        offsetPreviousVertex,
+        lineOffsetY,
+        direction,
+        offsets
+      );
+      path.push(offsetPreviousVertex[0], offsetPreviousVertex[1]);
+      segmentX = offsetIntersectionPoint[0] - offsetPreviousVertex[0];
+      segmentY = offsetIntersectionPoint[1] - offsetPreviousVertex[1];
+    }
+    currentSegmentDistance = Math.hypot(segmentX, segmentY);
+  }
+
+  const k = (absOffsetX - distanceFromAnchor) / currentSegmentDistance;
+  const start = offsetPreviousVertex || previousVertex;
+  const x = start[0] + segmentX * k;
+  const y = start[1] + segmentY * k;
+  path.push(x, y);
+  return {
+    x,
+    y,
+    angle:
+      angle +
+      Math.atan2(currentVertex[1] - previousVertex[1], currentVertex[0] - previousVertex[0]),
+    path
+  };
+}
+
+/** `findOffsetIntersectionPoint`, with MapLibre's per-vertex cache of offset vertices. */
+function getOffsetIntersection(
+  projection: Projection,
+  index: number,
+  normal: [number, number],
+  currentVertex: [number, number],
+  offsetPreviousVertex: [number, number],
+  lineOffsetY: number,
+  direction: number,
+  offsets: Map<number, [number, number]>
+): [number, number] {
+  const cached = offsets.get(index);
+  if (cached) {
+    return cached;
+  }
+  const offsetCurrentVertex: [number, number] = [
+    currentVertex[0] + normal[0],
+    currentVertex[1] + normal[1]
+  ];
+  let result = offsetCurrentVertex;
+  const nextIndex = index + direction;
+  if (nextIndex >= 0 && nextIndex < projection.count) {
+    const next = projection.vertex(nextIndex);
+    const nextNormal = getOffsetNormal(
+      next[0] - currentVertex[0],
+      next[1] - currentVertex[1],
+      lineOffsetY,
+      direction
+    );
+    const begin = [currentVertex[0] + nextNormal[0], currentVertex[1] + nextNormal[1]];
+    const end = [next[0] + nextNormal[0], next[1] + nextNormal[1]];
+    result = intersectLines(offsetPreviousVertex, offsetCurrentVertex, begin, end) || result;
+  }
+  offsets.set(index, result);
+  return result;
+}
+
+/** Radians, clockwise on screen with y down, to deck.gl degrees, counter-clockwise. */
+function toDeckAngle(radians: number): number {
+  return (-radians * 180) / Math.PI;
+}
+
+/**
+ * Places each glyph of a label along `line`, as MapLibre GL JS draws text along a line. Returns
+ * null when the first or the last glyph does not fit on the line: MapLibre then hides the label.
+ * `flip` is decided by the caller (see {@link needsFlip}); MapLibre's own flip test is on screen.
+ */
+export function placeLineGlyphs(line: LabelLine, options: LineGlyphOptions): LineGlyphs | null {
+  const {offsets, flip, scale} = options;
+  const lineOffsetX = options.lineOffsetX || 0;
+  const lineOffsetY = options.lineOffsetY || 0;
+  const count = offsets.length;
+  const {segment} = line;
+  if (
+    !count ||
+    !(scale > 0) ||
+    !(segment >= 0) ||
+    segment * 2 + 3 >= line.points.length ||
+    !(line.t >= 0 && line.t <= 1)
+  ) {
+    return null;
+  }
+  const projection = getProjection(line, scale);
+  // MapLibre keeps one cache of offset vertices per label, whichever way a glyph walks: either way
+  // the offset vertex is where the same two offset segments meet.
+  const offsetVertices = new Map<number, [number, number]>();
+  const place = (offsetX: number) =>
+    placeGlyph(projection, segment, offsetX, lineOffsetX, lineOffsetY, flip, offsetVertices);
+  const first = place(offsets[0]);
+  const last = count > 1 ? place(offsets[count - 1]) : first;
+  if (!first || !last) {
+    return null;
+  }
+  const glyphs = new Float32Array(count * 3);
+  const write = (i: number, glyph: PlacedGlyph) => {
+    glyphs[i * 3] = glyph.x;
+    glyphs[i * 3 + 1] = glyph.y;
+    glyphs[i * 3 + 2] = toDeckAngle(glyph.angle);
+  };
+  write(0, first);
+  for (let i = 1; i < count - 1; i++) {
+    const glyph = place(offsets[i]);
+    if (!glyph) {
+      return null;
+    }
+    write(i, glyph);
+  }
+  write(count - 1, last);
+  // The collision path: the first glyph's path reversed, then the last glyph's, without the anchor
+  // each starts from (MapLibre's `placeCollisionCircles`).
+  const path: number[] = [];
+  for (let i = first.path.length - 2; i >= 2; i -= 2) {
+    path.push(first.path[i], first.path[i + 1]);
+  }
+  for (let i = 2; i < last.path.length; i += 2) {
+    path.push(last.path[i], last.path[i + 1]);
+  }
+  return {glyphs, path};
+}
+
+/**
+ * MapLibre's `requiresOrientationChange` for horizontal text: whether a label placed unflipped reads
+ * right to left on screen, its first glyph right of its last, on a flat map turned by `bearing`.
+ */
+export function needsFlip(unflipped: LineGlyphs, bearing: number): boolean {
+  const {glyphs} = unflipped;
+  const n = glyphs.length / 3;
+  const dx = glyphs[(n - 1) * 3] - glyphs[0];
+  const dy = glyphs[(n - 1) * 3 + 1] - glyphs[1];
+  // A direction of the map plane is drawn turned counter-clockwise by the bearing on screen, as in
+  // `getUprightAngle`: the chord's x on screen.
+  const radians = (bearing * Math.PI) / 180;
+  const x = dx * Math.cos(radians) + dy * Math.sin(radians);
+  return x < 0;
+}
+
+/**
+ * Collision circles along a path on screen, as MapLibre GL JS's `placeCollisionCircles` lays them
+ * out with its `PathInterpolator`: the path's ends inset by a quarter radius, circles at most 2.5
+ * radii apart, and one circle on a path shorter than half a radius (or at the middle of the path
+ * for a radius of 0). Returns `x, y, radius` triples.
+ */
+export function getPathCircles(path: ArrayLike<number>, radius: number): number[] {
+  const count = path.length / 2;
+  if (!count) {
+    return [];
+  }
+  const distances = [0];
+  for (let i = 1; i < count; i++) {
+    distances[i] =
+      distances[i - 1] +
+      Math.hypot(path[i * 2] - path[i * 2 - 2], path[i * 2 + 1] - path[i * 2 - 1]);
+  }
+  const length = distances[count - 1];
+  const padding = Math.min(radius * 0.25, length * 0.5);
+  const paddedLength = length - padding * 2;
+  // A label without height has one circle, at the middle of its path.
+  const circleCount =
+    !(radius > 0) || length <= 0.5 * radius ? 1 : Math.ceil(paddedLength / (radius * 2.5)) + 1;
+  const circles: number[] = [];
+  for (let k = 0; k < circleCount; k++) {
+    const t = circleCount === 1 && !(radius > 0) ? 0.5 : k / Math.max(circleCount - 1, 1);
+    if (count === 1) {
+      circles.push(path[0], path[1], radius);
+      continue;
+    }
+    const target = t * paddedLength + padding;
+    let index = 1;
+    while (distances[index] < target && index < count - 1) {
+      index++;
+    }
+    const segment = distances[index] - distances[index - 1];
+    const u = segment > 0 ? (target - distances[index - 1]) / segment : 0;
+    circles.push(
+      path[index * 2 - 2] * (1 - u) + path[index * 2] * u,
+      path[index * 2 - 1] * (1 - u) + path[index * 2 + 1] * u,
+      radius
+    );
+  }
+  return circles;
+}