@davidsouther/agathon 0.0.0-stage → 0.0.0

package/src/layout/hierarchic/position.ts

@@ -0,0 +1,514 @@
+import { assert, assertExists } from "../../assert.ts";
+import { RNGon } from "../../geometry.ts";
+import { TsabreGraph } from "../../tsabre/graph.ts";
+import type { FullGraph, NodeId } from "../../types.ts";
+import * as util from "../util.ts";
+
+/**
+ * An alignment marks a set of blocks (vertical chains of edges) and classes
+ * (horizontal groupings of blocks).
+ */
+export interface Alignment {
+  root: Record<NodeId, NodeId>;
+  align: Record<NodeId, NodeId>;
+}
+
+/** A shorthand for tracking id to number. */
+export type Coordinates = Record<NodeId, number>;
+
+/**
+ * The coordinates of each node, from each of the diaganols.
+ */
+export interface CoordinateBounds {
+  ul: Coordinates;
+  ur: Coordinates;
+  dl: Coordinates;
+  dr: Coordinates;
+}
+
+/**
+ * Given a graph with nodes' rank and order filled in, determine their relative
+ * position, obeying size & label constraints. Y positions are trivially easy-
+ * all nodes with the same rank have the same Y value, and the next Y value is
+ * the prior Y value plus half the max node height of the current row plus half
+ * the max node height of the next row plus the graph's rankSep.
+ *
+ * X coordinates are much more complex, and lean heavily on the "balance and
+ * symmetry" aesthetic. Constraints to consider are balancing whitespace, length
+ * and straightness of edges, and balancing edges incident on one node. Given
+ * that vertical placement is fixed by ranks, above, X positions indeed only
+ * lay out in the horizontal direction.
+ *
+ * See [Brandes and Koepf] in docs/tsabre for more details.
+ */
+export function position(g: FullGraph): void {
+  const layerMatrix = util.buildLayerMatrix(g);
+
+  const ys = positionY(g, layerMatrix);
+  const xs = positionX(g, layerMatrix);
+
+  for (const node of g.allNodes) {
+    const x = xs[node.id] ?? 0;
+    const y = ys[node.id] ?? 0;
+    util.getNodeProps(node).geometry.moveTo({ x, y });
+  }
+}
+
+/**
+ * Calculate aesthetically pleasing X coordinates for nodes, given a SmartGraph
+ * with nodes having `order` and `rank` on their layout, as well as having
+ * virtual nodes indicating segments of multi-rank edge spans. Node layout
+ * should keep conceptual "columns" grouped, that is, keeping edges as vertical
+ * and as short as possible.
+ */
+function positionX(g: FullGraph, layers: NodeId[][]): Coordinates {
+  const conflicts = findType1Conflicts(g, layers);
+
+  // Positioning layouts have strong directional affinities. To mitigate this,
+  // we calculate all 4 layouts, and then take the median positions for the
+  // final balanced position. See [Brandes and Kopf 4.3].
+  const direction = {
+    ul: [...layers],
+    ur: [...layers].map((l) => [...l].reverse()),
+    dl: [...layers].reverse(),
+    dr: [...layers].map((l) => [...l].reverse()).reverse(),
+  };
+
+  const xss: CoordinateBounds = {
+    ul: makeBounds(direction.ul, (id: NodeId) => g.predecessors(id), false),
+    ur: makeBounds(direction.ur, (id: NodeId) => g.predecessors(id), true),
+    dl: makeBounds(direction.dl, (id: NodeId) => g.successors(id), false),
+    dr: makeBounds(direction.dr, (id: NodeId) => g.successors(id), true),
+  };
+
+  const smallestWidth = findSmallestWidthAlignment(g, xss);
+  alignCoordinates(xss, smallestWidth);
+  return balance(xss);
+
+  function makeBounds(
+    layers: NodeId[][],
+    neighborFn: (id: NodeId) => Set<NodeId>,
+    correction: boolean,
+  ) {
+    const align = verticalAlignment(layers, conflicts, neighborFn);
+    const xs = horizontalCompaction(g, layers, align);
+
+    if (correction) {
+      for (const [id, x] of Object.entries(xs)) {
+        xs[id] = -x;
+      }
+    }
+    return xs;
+  }
+}
+
+function positionY(g: FullGraph, layers: NodeId[][]): Coordinates {
+  const coordinates: Coordinates = {};
+  const { rankSep, staggerRows } = util.getGraphProps(g);
+  assert(staggerRows > 0);
+  // It's easiest to assign y position as the middle of the row + row sep + the
+  // middle of the next row. To normalize back to y=0 for the first row,
+  // subtract that first middle row height.
+  // All empty/undefined (virtual) nodes in layers are filtered out in
+  // buildLayerMatrix.
+  let prevY =
+    -0.5 * Math.max(...layers[0].map((id) => util.getNodeProps(g.node(id)!).geometry.height));
+  for (const layer of layers) {
+    const height = util.staggerRow(g, layer, coordinates, staggerRows);
+    for (const id of layer) {
+      coordinates[id] += prevY;
+    }
+    prevY += height + rankSep;
+  }
+  return coordinates;
+}
+
+/**
+ * Conflicts track which other nodes a node has conflicting edges with.
+ * Conflicts occur when two edge segments cross or share a vertex.
+ *
+ *  a b
+ *   X
+ *  c d
+ *
+ * a conflicts with c and d, b conflicts with c and d,
+ */
+type Conflicts = Map<NodeId, Set<NodeId>>;
+
+/**
+ * Type 1 conflicts are when a non-inner segment crosses an inner segment. An
+ * inner segment is one on which both incident nodes are marked `virtual`, and
+ * represents a portion of a longer edge which crosses multiple ranks. Inner
+ * segments should be kept vertical; otherwise, long edges will be "jagged".
+ *
+ * We scan layer by layer, starting at the second, looking for type-1 conflicts
+ * between the current and prior layer.
+ */
+function findType1Conflicts(g: FullGraph, layers: NodeId[][]): Conflicts {
+  const conflicts = new Map<NodeId, Set<NodeId>>();
+
+  for (let i = 1; i < layers.length; i++) {
+    const layer = layers[i];
+    const prev = layers[i - 1];
+
+    let k0 = 0;
+    let scanPos = 0;
+    const prevLength = prev.length;
+
+    for (let j = 0; j < layer.length; j++) {
+      const id = layer[j];
+
+      const target = findOtherInnerSegmentNode(g, id);
+      const k1 = target ? util.getNodeProps(g.node(target)!).order : prevLength;
+
+      if (target || id === layer[layer.length - 1]) {
+        for (const scanNodeId of layer.slice(scanPos, j + 1)) {
+          const scanNode = g.node(scanNodeId);
+
+          if (!scanNode) continue;
+
+          const vScanNode = util.getNodeProps(scanNode).virtual;
+          for (const pred of g.predecessors(scanNodeId)) {
+            const { order, virtual } = util.getNodeProps(g.node(pred)!);
+
+            const hasVScanNode = vScanNode !== false;
+            const hasVirtual = virtual !== false;
+
+            if ((order < k0 || k1 < order) && !(hasVirtual && hasVScanNode)) {
+              addConflict(conflicts, pred, scanNodeId);
+            }
+          }
+        }
+        scanPos = j + 1;
+        k0 = k1;
+      }
+    }
+  }
+
+  return conflicts;
+}
+
+function findOtherInnerSegmentNode(g: FullGraph, id: NodeId): NodeId | undefined {
+  const node = g.node(id);
+  if (node && util.getNodeProps(node).virtual !== false) {
+    return Array.from(g.predecessors(id)).find(
+      (id) => util.getNodeProps(g.node(id)!).virtual !== false,
+    );
+  }
+  return undefined;
+}
+
+function sortIds(a: NodeId, b: NodeId): [NodeId, NodeId] {
+  // Normalize source and target alphabetically
+  if (a > b) {
+    [b, a] = [a, b];
+  }
+  return [a, b];
+}
+
+/** Mark a conflict between any source/target pair. */
+function addConflict(conflicts: Conflicts, a: NodeId, b: NodeId): void {
+  const [source, target] = sortIds(a, b);
+  const conflictSet = conflicts.get(source) || new Set<NodeId>();
+  conflicts.set(source, conflictSet);
+  conflictSet.add(target);
+}
+
+/** Check if there is a conflict between any source/target pair. */
+function hasConflict(conflicts: Conflicts, a: NodeId, b: NodeId): boolean {
+  const [source, target] = sortIds(a, b);
+  if (!conflicts.has(source)) return false;
+  return conflicts.get(source)!.has(target);
+}
+
+/**
+ * Determine vertical alignment among nodes by finding the median positions of a
+ *
+ * See [Brandes and Kopf 4.1].
+ */
+function verticalAlignment(
+  layers: NodeId[][],
+  conflicts: Conflicts,
+  neighbors: (id: NodeId) => Set<NodeId>,
+): Alignment {
+  // The root mapping will point to the node's neighbor to the left.
+  const root: Record<NodeId, NodeId> = {};
+  // The align mapping will point to the node's neighbor to the right.
+  const align: Record<NodeId, NodeId> = {};
+  const pos: Coordinates = {};
+
+  for (const layer of layers) {
+    for (let i = 0; i < layer.length; i++) {
+      const id = layer[i];
+      root[id] = id;
+      align[id] = id;
+      pos[id] = i;
+    }
+  }
+
+  for (const layer of layers) {
+    let prevIdx = -1;
+    for (const id of layer) {
+      const ns = neighbors(id);
+      if (ns.size > 0) {
+        const ids = Array.from(ns).sort((a, b) => pos[a] - pos[b]);
+        // Update the median point
+        const mp = (ids.length - 1) / 2;
+        for (let i = Math.floor(mp), j = Math.ceil(mp); i <= j; i++) {
+          const targetId = ids[i];
+          if (
+            align[id] === id &&
+            prevIdx < pos[targetId] &&
+            !hasConflict(conflicts, id, targetId)
+          ) {
+            align[targetId] = id;
+            align[id] = root[id] = root[targetId];
+            prevIdx = pos[targetId];
+          }
+        }
+      }
+    }
+  }
+
+  return { root, align };
+}
+
+/**
+ * Given a vertical alignment, shrink it as tight as possible. This shrinking
+ * is facilitated by a block graph, that is, a graph that points each node at
+ * its predecessor on a rank. See [Brandes and Kopf 4.2].
+ */
+function horizontalCompaction(
+  graph: FullGraph,
+  layers: NodeId[][],
+  alignment: Alignment,
+): Coordinates {
+  const xs: Coordinates = {};
+  const { root, align } = alignment;
+
+  const blockG = buildBlockGraph();
+
+  iterate(pass1, (id) => blockG.predecessors(id));
+  iterate(pass2, (id) => blockG.successors(id));
+
+  for (const id of Object.keys(align)) {
+    xs[id] = xs[root[id]];
+  }
+
+  return xs;
+
+  /* Set x values to the maximum incoming edge weights, pushing the node to the
+   * far right of the vertical block. */
+  function pass1(id: NodeId) {
+    const edgeWeights = Array.from(blockG.inEdges(id)).map(
+      (e) => (xs[e.source] || 0) + blockG.edge(e)!.separation,
+    );
+    xs[id] = edgeWeights.reduce((max, e) => Math.max(max, e), 0);
+    if (isNaN(xs[id])) {
+      // This is a serious error that is unclear how best to handle. In lieu of
+      // a robust understanding of the problem, just shunt the node far-left.
+      // If this is happening, drop a debugger here and take a look.
+      xs[id] = -1;
+    }
+  }
+
+  /* Set x values to the minimum outgoing edge weights, pulling the node to the
+   * far left of the vertical block. */
+  function pass2(id: NodeId) {
+    const MAX = Number.POSITIVE_INFINITY;
+    const edgeWeights = Array.from(blockG.outEdges(id)).map(
+      (e) => xs[e.target] - blockG.edge(e)!.separation,
+    );
+    const min = edgeWeights.reduce((min, e) => Math.min(min, e), MAX);
+    if (min !== MAX) {
+      xs[id] = Math.max(xs[id], min);
+    }
+  }
+
+  // Utility to apply a function across the blockG nodes
+  function iterate(setXs: (id: NodeId) => void, nextNodes: (id: NodeId) => Set<NodeId>) {
+    const stack = Array.from(blockG.nodes);
+    const visited = new Set<NodeId>();
+    while (stack.length > 0) {
+      const id = stack.pop()!;
+      if (visited.has(id)) {
+        setXs(id);
+      } else {
+        visited.add(id);
+        stack.push(id, ...nextNodes(id));
+      }
+    }
+  }
+
+  function buildBlockGraph() {
+    const blockGraph = new TsabreGraph<
+      {},
+      { source: NodeId; target: NodeId; separation: number }
+    >();
+    const { nodeSep, edgeSep } = util.getGraphProps(graph);
+
+    for (const layer of layers) {
+      let tId: NodeId | undefined;
+      for (const sId of layer) {
+        const sRoot = root[sId];
+        blockGraph.setNode(sRoot, {});
+        if (tId) {
+          const tRoot = root[tId];
+          const ts = {
+            source: tRoot,
+            target: sRoot,
+            separation: separation(tId, sId),
+          };
+          const tsEdge = blockGraph.edge(ts);
+          if (tsEdge) {
+            ts.separation = Math.max(ts.separation, tsEdge.separation);
+          }
+          blockGraph.setEdge(ts, ts);
+        }
+        tId = sId;
+      }
+    }
+
+    return blockGraph;
+
+    /**
+     *  calculate the horizontal separation between two nodes in a graph.
+     * Horizontal separation is half of the width of each node, plus nodeSep,
+     * plus edgeSep for any virtual nodes created to break up long edges.
+     */
+    function separation(sid: NodeId, tid: NodeId): number {
+      const sNode = graph.node(sid);
+      const tNode = graph.node(tid);
+
+      // Occasionally, there are virtual nodes in the layers, that are used to
+      // build node-connecting lines, but don't take any space (0 width &
+      // height).
+      const virtualNodePlaceholder = {
+        width: 0,
+        virtual: true,
+        geometry: RNGon.point(),
+      };
+
+      const sLayout = sNode ? util.getNodeProps(sNode) : virtualNodePlaceholder;
+      const tLayout = tNode ? util.getNodeProps(tNode) : virtualNodePlaceholder;
+
+      let sum = 0;
+      sum += sLayout.geometry.width;
+      sum += sLayout.virtual ? edgeSep : nodeSep;
+      sum += tLayout.virtual ? edgeSep : nodeSep;
+      sum += tLayout.geometry.width;
+
+      return sum / 2;
+    }
+  }
+}
+
+/**
+ * Arrange the coordinates of each of the layout alignment bounds such that
+ * left-biased alignments have their minimum coordinate at the same point as
+ * the minimum coordinate of the smallest width alignment and right-biased
+ * alignments have their maximum coordinate at the same point as the maximum
+ * coordinate of the smallest width alignment.
+ */
+function alignCoordinates(xss: CoordinateBounds, alignTo: Coordinates): void {
+  const alignToVals = Object.values(alignTo);
+  const alignToMin = Math.min(...alignToVals);
+  const alignToMax = Math.max(...alignToVals);
+
+  function updateCoords(xs: Coordinates, left: boolean) {
+    if (xs === alignTo) return;
+    const vals = Object.values(xs) || {};
+    const delta = left ? alignToMin - Math.min(...vals) : alignToMax - Math.max(...vals);
+    for (const id of Object.keys(xs)) {
+      xs[id] += delta;
+    }
+  }
+
+  updateCoords(xss.ur, false);
+  updateCoords(xss.ul, true);
+  updateCoords(xss.dr, false);
+  updateCoords(xss.dl, true);
+}
+
+function getAlignment(bounds: CoordinateBounds, v: "u" | "d", h: "l" | "r") {
+  if (v === "u" && h === "l") return bounds.ul;
+  if (v === "u" && h === "r") return bounds.ur;
+  if (v === "d" && h === "l") return bounds.dl;
+  if (v === "d" && h === "r") return bounds.dr;
+  throw new Error(`Invalid alignment: ${v}${h}`);
+}
+
+/**
+ * Given a set of bounds, find the one with the smallest layout width.
+ */
+function findSmallestWidthAlignment(g: FullGraph, bounds: CoordinateBounds): Coordinates {
+  let best = Number.POSITIVE_INFINITY;
+  let bestCoords: Coordinates | undefined;
+
+  for (const coords of Object.values(bounds)) {
+    let max = Number.NEGATIVE_INFINITY;
+    let min = Number.POSITIVE_INFINITY;
+
+    const entries: Array<[NodeId, number]> = Object.entries(coords);
+    for (const [id, x] of entries) {
+      const node = g.node(id);
+      if (!node) continue;
+
+      const halfWidth = util.getNodeProps(node).geometry.width / 2;
+
+      max = Math.max(x + halfWidth, max);
+      min = Math.min(x - halfWidth, min);
+    }
+
+    const nextBest = max - min;
+    if (nextBest < best) {
+      best = nextBest;
+      bestCoords = coords;
+    }
+  }
+
+  return assertExists(bestCoords, "No best coordinates possible");
+}
+
+/**
+ * Layouts are created in 4 diagonal directions. Each biases sources to the
+ * corresponding corners. To even this out, a final balancing placed each node
+ * at the median of its 4 computed positions.
+ */
+function balance(xss: CoordinateBounds, align?: ["u" | "d", "l" | "r"]): Coordinates {
+  const balanced: Coordinates = {};
+  let minX = Number.MAX_VALUE;
+  for (const id of Object.keys(xss.ul)) {
+    if (align) {
+      balanced[id] = getAlignment(xss, align[0], align[1])[id];
+      minX = Math.min(minX, balanced[id]);
+    } else {
+      const xs = Object.values(xss)
+        .map((c) => c[id])
+        .sort((a, b) => a - b) as [number, number, number, number];
+      // Get the median value of the 4 entries
+      balanced[id] = (xs[1] + xs[2]) / 2;
+      minX = Math.min(minX, balanced[id]);
+    }
+  }
+
+  // Normalize all X values, so that minimum value is set to 0. Prevents the
+  // graph from shifting around during positioning, by fixing the left side
+  for (const id of Object.keys(balanced)) {
+    balanced[id] -= minX;
+  }
+  return balanced;
+}
+
+export const TEST_ONLY = {
+  addConflict,
+  alignCoordinates,
+  balance,
+  findSmallestWidthAlignment,
+  findType1Conflicts,
+  hasConflict,
+  horizontalCompaction,
+  positionX,
+  positionY,
+  verticalAlignment,
+};