@davidsouther/agathon 0.0.0-stage → 0.0.0

package/src/geometry.ts

@@ -0,0 +1,61 @@
+import { checkExhaustive } from "./assert.ts";
+
+import { CircleGeometry, type CircleParams } from "./geometry/circle.ts";
+import {
+  RectangleGeometry,
+  type RectangleParams,
+  SquareGeometry,
+  type SquareParams,
+} from "./geometry/rectangle.ts";
+import { RNGon, type RNGonParams } from "./geometry/rngon.ts";
+import type { Geometry } from "./geometry/types.ts";
+
+export { CircleGeometry } from "./geometry/circle.ts";
+export { origin } from "./geometry/geometry.ts";
+export { FULL_BOX, straightLinePath } from "./geometry/path.ts";
+export { RectangleGeometry, SquareGeometry } from "./geometry/rectangle.ts";
+export { RNGon } from "./geometry/rngon.ts";
+
+const GeometryType = {
+  RECTANGLE: "rectangle",
+  SQUARE: "square",
+  CIRCLE: "circle",
+  RNGON: "rngon",
+} as const;
+
+interface ParseCircleParams extends CircleParams {
+  type: typeof GeometryType.CIRCLE;
+}
+interface ParseRectangleParams extends RectangleParams {
+  type: typeof GeometryType.RECTANGLE;
+}
+interface ParseRNGonParams extends RNGonParams {
+  type: typeof GeometryType.RNGON;
+}
+interface ParseSquareParams extends SquareParams {
+  type: typeof GeometryType.SQUARE;
+}
+
+/** JSON parameters to parse a geometry */
+export type GeometryParams =
+  | ParseCircleParams
+  | ParseRectangleParams
+  | ParseRNGonParams
+  | ParseSquareParams;
+
+/** Parse an object describing a geometry into the full object instance. */
+export function parseGeometry(params: GeometryParams): Geometry {
+  const { type } = params;
+  switch (type) {
+    case GeometryType.CIRCLE:
+      return new CircleGeometry(params);
+    case GeometryType.SQUARE:
+      return new SquareGeometry(params);
+    case GeometryType.RECTANGLE:
+      return new RectangleGeometry(params);
+    case GeometryType.RNGON:
+      return new RNGon(params);
+    default:
+      return checkExhaustive(type);
+  }
+}

package/src/highlight/highlight.ts

@@ -0,0 +1,85 @@
+import { segmentId } from "../tsabre/graph.ts";
+import type { Edge, FullGraph, NodeId, Segment } from "../types.ts";
+
+/**
+ * Class to track which nodes and edges should be considered highlighted.
+ */
+export abstract class HighlightManager {
+  protected readonly highlighted = new Set<string>();
+
+  protected graph?: FullGraph;
+  constructor(graph?: FullGraph) {
+    this.graph = graph;
+  }
+
+  setGraph(graph: FullGraph): void {
+    this.clear();
+    this.graph = graph;
+  }
+
+  clear(): void {
+    this.highlighted.clear();
+  }
+
+  isNodeHighlighted(id: NodeId): boolean {
+    return this.highlighted.has(id);
+  }
+
+  isSegmentHighlighted(segment: Segment): boolean {
+    return this.highlighted.has(segmentId(segment));
+  }
+
+  abstract markNode(id?: NodeId): void;
+  abstract unmarkNode(id?: NodeId): void;
+
+  abstract markSegment(segment?: Segment<Edge>): void;
+  abstract unmarkSegment(segment?: Segment<Edge>): void;
+}
+
+/**
+ * A highlight manager which tracks a single highlighted node and its one-hop
+ * neighborhood at a time. Marking a second node will clear the first, and only
+ * add the second node's neighborhood.
+ */
+export class SingleHighlightManager extends HighlightManager {
+  markNode(id?: NodeId): void {
+    this.clear();
+
+    if (!id) return;
+    if (!this.graph) return;
+
+    this.highlighted.add(id);
+    for (const segment of this.graph.nodeSegments(id)) {
+      for (const edge of segment.edges) {
+        for (const s of this.graph.edgeSegments(edge)) {
+          this.highlighted.add(s.source);
+          this.highlighted.add(s.target);
+          this.highlighted.add(segmentId(s));
+        }
+      }
+    }
+  }
+
+  markSegment(segment?: Segment<Edge>): void {
+    this.clear();
+
+    if (!segment) return;
+    if (!this.graph) return;
+
+    for (const edge of segment.edges) {
+      for (const s of this.graph.edgeSegments(edge)) {
+        this.highlighted.add(s.source);
+        this.highlighted.add(s.target);
+        this.highlighted.add(segmentId(s));
+      }
+    }
+  }
+
+  override unmarkNode(id?: NodeId): void {
+    this.clear();
+  }
+
+  override unmarkSegment(s?: Segment): void {
+    this.clear();
+  }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * as assert from "./assert.ts";
+export * as geometry from "./geometry.ts";
+export * as layout from "./layout.ts";
+export * as tsabre from "./tsabre.ts";
+export * as types from "./types.ts";

package/src/layout/grid/manager.ts

@@ -0,0 +1,55 @@
+import type { Geometry } from "../../geometry/types.ts";
+import type { NodeId } from "../../types.ts";
+import { layout as hullLayout } from "../hulls/hulls.ts";
+import { assignSegmentPoints } from "../hulls/segments.ts";
+import { AbstractLayoutManager } from "../manager/manager.ts";
+import type { LayoutNode } from "../types.ts";
+import { getNodeProps } from "../util.ts";
+
+const SEPARATION = 50;
+const RADIUS = 10;
+
+/**
+ * A linear layout manager, for ease of testing. Puts nodes into a square, as
+ * best it is able.
+ */
+export class GridLayoutManager extends AbstractLayoutManager {
+  /**
+   * Rerun the layout.
+   * @param triggeredNodeId - See manager/manager.ts::run(). ID of the
+   * expanded/collapsed node. Each such event triggers a partial layout
+   * recalculation. If no event fired and/or we need the complete layout
+   * recalculation, no triggeredNodeId is passed.
+   */
+  protected doLayout(triggeredNodeId?: NodeId): void {
+    const nodes = this.graph.children();
+    const nodesPerRow = Math.ceil(Math.sqrt(nodes.size));
+    let col = 0;
+    let row = 0;
+
+    hullLayout(this.graph, triggeredNodeId);
+
+    for (const id of nodes) {
+      if (col >= nodesPerRow) {
+        col = 0;
+        row += 1;
+      }
+
+      const node = this.getNode(id);
+      const { geometry } = getNodeProps(node);
+      geometry.moveTo({ x: col * SEPARATION, y: row * SEPARATION });
+      geometry.resize(node.expanded ? geometry.height / 2 : RADIUS);
+
+      col += 1;
+    }
+
+    assignSegmentPoints(this.graph);
+  }
+
+  protected override assignNode(node: LayoutNode, position: Geometry): void {
+    const { geometry } = getNodeProps(node);
+    geometry.moveTo(position);
+
+    super.assignNode(node, position);
+  }
+}

package/src/layout/grid.ts

@@ -0,0 +1 @@
+export * as grid from "./grid/manager.ts";

package/src/layout/hierarchic/README.md

@@ -0,0 +1,21 @@
+# Graph Layout
+
+Given a graph G, assign <x, y> to each node to result in an efficient and
+aesthetically pleasing layout.
+
+"Aesthetically Pleasing" is not a subjective concept, but rather a collection of
+mathematical principles driven in the goal of an accurate layout which serves to
+bring forth information present in the graph proper. From Gansner, these
+attributes to maintain are:
+
+- A1) Expose hierarchical structure in the graph.
+- A2) Avoid visual anomolies which do not convey information.
+- A3) Keep edges short.
+- A4) Favor symmetry and balance.
+
+This happens in 3 phases - ranking (vertical positioning), ordering (horizontal
+positioning), and positioning (converting rank and order to a compact <x, y>).
+See layout.ts for the high-level orchestration, and links to other files in
+order for implementation & notes.
+
+See docs/tsabre for full details and references.

package/src/layout/hierarchic/acyclic.ts

@@ -0,0 +1,249 @@
+import { assertExists } from "../../assert.ts";
+import { EDGE_KEY_DELIM, edgeId, TsabreGraph } from "../../tsabre/graph.ts";
+import type { Edge, FullGraph, Node, SmartGraph } from "../../types.ts";
+import { getEdgeProps, getGraphProps } from "../util.ts";
+
+import { debugFas } from "./debug.ts";
+
+/**
+ * Given an arbitrary graph find a small set of edges such that removing them
+ * results in an acyclic graph, and then flip those edges. Leave the edges
+ * marked so that it can be undone in the future.
+ */
+export function decycle(g: FullGraph): void {
+  const graphProps = getGraphProps(g);
+  // Cache the FAS. The cached FAS will be used on further iterations of layout
+  // calculation, as a part of simplified pipeline.
+  // greedyFas is a good (in size of sets), polynomial time algorithm to find
+  // the set of edges which cause cycles.
+  graphProps.fas = graphProps.fas === undefined ? greedyFas(g) : graphProps.fas;
+
+  for (const e of graphProps.fas) {
+    const edge = g.edge(e)!;
+    const layout = getEdgeProps(edge);
+    layout.reversed = true;
+    layout.original = edge;
+    g.removeEdge(e);
+    // An almost certainly unique name.
+    const name = `(reversed${EDGE_KEY_DELIM}${edgeId(edge)})`;
+    const reversed = { source: e.target, target: e.source, name, layout };
+    g.setEdge(reversed, reversed);
+  }
+}
+
+/**
+ * Given a DAG with edges possibly flipped by decycle, restore the flipped
+ * edges.
+ */
+export function recycle(g: FullGraph): void {
+  for (const e of g.edges()) {
+    const layout = getEdgeProps(e);
+    if (layout.reversed) {
+      const original = assertExists(
+        layout.original,
+        `Reversing edge ${edgeId(e)} with no original edge`,
+      );
+      g.removeEdge(e);
+      layout.reversed = false;
+      delete layout.original;
+      g.setEdge(original, original);
+    }
+  }
+}
+
+/**
+ * Heuristic Feedback Arc Set implementation, returning a minimal list of
+ * cycle-causing edges. This will be used as the set of edges to reverse to
+ * remove cycles in the graph.
+ *
+ * See Eades et al, "Effective Heuristic for the Feedback Arc Set Problem".
+ *
+ * All nodes will have some number of "out" edges (sources) and some number of
+ * "in" edges (sinks). The heuristic greedily removes source, sink, and nodes
+ * which have the highest D(n), where D(n) = (number of out edges - number of in
+ * edges). In practice, this means keeping a mapping of D(n) to lists of nodes
+ * with that size. (For convenience in iteration, this is an array normalized so
+ * that 0 = no inedges (aka all sources). Iteration then proceeds by "removing"
+ * the node with max(D(n)), updating nodes in its neighborhood with their new
+ * inedge & outedge count.
+ *
+ * This algorithm works because when removing max(D(n)) nodes, it's likely that
+ * new source and sink nodes are revealed. Additionally, other nodes within the
+ * current max set will likely get moved out of that set as their D(n) counts
+ * change. See the paper for proof, etc.
+ *
+ * During this iteration, the final FAS is the set of all edges removed when
+ * removing max(D(n)) nodes.
+ */
+function greedyFas(g: FullGraph): Edge[] {
+  const { printDebug } = getGraphProps(g);
+
+  interface FasNode extends Node {
+    in: number;
+    out: number;
+  }
+  interface FasEdge extends Edge {
+    weight: number;
+  }
+
+  type FasGraph = SmartGraph<FasNode, FasEdge>;
+  interface FasState {
+    graph: FasGraph;
+    // A list of FasNodes, sorted by Max(outEdges - inEdges)), with  [len-1]
+    // being sources & sinks.
+    buckets: FasNode[][];
+  }
+
+  if (g.nodeCount <= 1) return [];
+  const state = buildState();
+
+  if (printDebug) {
+    console.group("FAS");
+    debugFas(state);
+  }
+
+  const results = doGreedyFas(state);
+
+  if (printDebug) {
+    console.groupEnd();
+  }
+
+  return results;
+
+  /** Build the initial list of FAS buckets, ordered by (outedges - inedges). */
+  function buildState(): FasState {
+    const fasGraph = new TsabreGraph<FasNode, FasEdge>();
+    let maxIn = 0;
+    let maxOut = 0;
+
+    for (const id of g.nodes) {
+      fasGraph.setNode(id, { id, in: 0, out: 0 });
+    }
+
+    for (const edge of g.edges()) {
+      const { weight } = getEdgeProps(g.edge(edge)!);
+      fasGraph.setEdge(edge, { ...edge, weight });
+      maxOut = Math.max(maxOut, (fasGraph.node(edge.source)!.out += weight));
+      maxIn = Math.max(maxIn, (fasGraph.node(edge.target)!.in += weight));
+    }
+
+    const buckets: FasNode[][] = [];
+    for (let i = 0; i < Math.max(maxOut, maxIn) + 2; i++) {
+      buckets[i] = [];
+    }
+
+    for (const id of fasGraph.nodes) {
+      const node = fasGraph.node(id)!;
+      assignBucket(buckets, node);
+    }
+
+    return { graph: fasGraph, buckets };
+  }
+
+  /**
+   * Greedily work throuth the buckets, removing sources, sinks, and max nodes.
+   */
+  function doGreedyFas({ graph: g, buckets }: FasState): Edge[] {
+    const results: Edge[] = [];
+
+    const ends = buckets[buckets.length - 1];
+
+    let i = 0;
+    while (g.nodeCount > 0) {
+      while (ends.length > 0) {
+        removeNode(g, buckets, ends.shift()!, false);
+      }
+      if (g.nodeCount) {
+        for (let i = buckets.length - 2; i >= 0; --i) {
+          if (buckets[i].length > 0) {
+            const bucket = buckets[i].shift()!;
+            const reverse = removeNode(g, buckets, bucket, true);
+            results.push(...reverse);
+            break; // Conservatively remove one node at a time; jump back to
+            // removeing sources and sinks.
+          }
+        }
+      }
+      if (printDebug) {
+        console.group(`FAS iteration ${i++}`);
+        debugFas({ graph: g, buckets }, results);
+        console.groupEnd();
+      }
+    }
+
+    return results;
+  }
+
+  function removeNode(g: FasGraph, buckets: FasNode[][], entry: FasNode, collect: boolean): Edge[] {
+    const results: FasEdge[] = [];
+
+    const inEdges = g.inEdges(entry.id);
+    const outEdges = g.outEdges(entry.id);
+
+    const collectIn = collect && entry.in <= entry.out;
+    const collectOut = collect && !collectIn;
+
+    for (const e of inEdges) {
+      if (e.source === entry.id) continue;
+      const edge = g.edge(e)!;
+      const { weight } = edge;
+      const source = g.node(edge.source)!;
+
+      if (collectIn) {
+        results.push({
+          source: e.source,
+          target: e.target,
+          name: e.name,
+          weight,
+        });
+      }
+
+      removeBucket(buckets, source);
+      source.out -= weight;
+      assignBucket(buckets, source);
+    }
+
+    for (const e of outEdges) {
+      if (e.target === entry.id) continue;
+      const edge = g.edge(e)!;
+      const { weight } = edge;
+      const target = g.node(edge.target)!;
+
+      if (collectOut) {
+        results.push({
+          source: e.source,
+          target: e.target,
+          name: e.name,
+          weight,
+        });
+      }
+
+      removeBucket(buckets, target);
+      target.in -= weight;
+      assignBucket(buckets, target);
+    }
+
+    g.removeNode(entry.id);
+    return results;
+  }
+
+  function assignBucket(buckets: FasNode[][], node: FasNode) {
+    const i = idx(node, buckets.length);
+    buckets[i].push(node);
+  }
+
+  function removeBucket(buckets: FasNode[][], node: FasNode) {
+    const i = idx(node, buckets.length);
+    const idn = buckets[i].indexOf(node) || buckets[i].length;
+    buckets[i].splice(idn, 1);
+  }
+
+  function idx({ in: en, out }: FasNode, end: number): number {
+    return out === 0 || en === 0 ? end - 1 : Math.abs(out - en);
+  }
+}
+
+/** Functions for testing. */
+export const TEST_ONLY = {
+  greedyFas,
+};

package/src/layout/hierarchic/children.ts

@@ -0,0 +1,169 @@
+/**
+ * @fileoverview When running layouts, children of nodes are handled using Hulls
+ * & Segments, as opposed to subgraphs. To not include children during the
+ * layout, these helpers will keep track of all the children its found, their
+ * edges, and their parent associations, removing them from the graph safely
+ * until they can be added back after layout of top-level nodes is complete.
+ */
+
+import { assertExists } from "../../assert.ts";
+import {
+  getPositionOnCircle,
+  getSmallestEnclosingCircle,
+  smallestIntersectingRadius,
+} from "../../geometry/circle.ts";
+import type { Circle, Edge, Node, NodeId, PointTuple } from "../../types.ts";
+import type { LayoutGraph } from "../types.ts";
+import { getGraphProps, getNodeProps } from "../util.ts";
+
+/**
+ * A childrenHandler returns a pair of functions bound to a known set of
+ * children.
+ */
+export function handler(): {
+  remove: (input: LayoutGraph) => LayoutGraph;
+  replace: (input: LayoutGraph) => LayoutGraph;
+} {
+  const children: Array<[NodeId, Node]> = [];
+  const childEdges = new Map<Edge, Edge>();
+  return {
+    /**
+     * Stash child nodes, their parent links, and their edges.
+     */
+    remove(g: LayoutGraph) {
+      const visited = new Set<NodeId>();
+      function dfs(n: NodeId) {
+        if (visited.has(n)) return;
+        visited.add(n);
+        for (const child of g.children(n)) {
+          dfs(child);
+        }
+        const pid = g.parent(n);
+        if (g.hasNode(pid)) {
+          children.push([pid, g.node(n)!] as [NodeId, Node]);
+          for (const edge of g.edges(n)) {
+            childEdges.set(edge, g.edge(edge)!);
+          }
+          g.removeNode(n);
+        }
+      }
+      for (const id of g.nodes) {
+        dfs(id);
+      }
+      return g;
+    },
+
+    /**
+     * Put the stashed children back in the graph.
+     */
+    replace(g: LayoutGraph) {
+      while (children.length > 0) {
+        // Nodes were pushed from each tree bottom to top, so popping them
+        // works as a stack.
+        const [pid, node] = children.pop() as [NodeId, Node];
+        g.setNode(node.id, node);
+        g.setParent(node.id, pid);
+      }
+      for (const [edge, value] of childEdges.entries()) {
+        g.setEdge(edge, value);
+      }
+
+      // Update position offsets based on one root node being moved
+      function positionDFS(id: NodeId, translate: PointTuple) {
+        const node = assertExists(g.node(id));
+        const { geometry } = getNodeProps(node);
+        geometry.move({ x: translate[0] | 0, y: translate[1] | 0 });
+        if (!node.expanded) return;
+        for (const cid of g.children(id)) {
+          positionDFS(cid, translate);
+        }
+      }
+
+      // Going through each top-level node, recenter all its children by the
+      // top-most hull's <x, y>.
+      for (const id of g.children()) {
+        const {
+          geometry: { x, y },
+          fx,
+          fy,
+        } = getNodeProps(g.node(id)!);
+        for (const cid of g.children(id)) {
+          positionDFS(cid, [fx ?? x, fy ?? y]);
+        }
+      }
+
+      return g;
+    },
+  };
+}
+
+/**
+ * Layout all nodes which are children, inside their parent.
+ */
+export function layout(g: LayoutGraph): void {
+  function translateDFS(id: NodeId, translate: PointTuple) {
+    const node = assertExists(g.node(id), `children::layout::translateDFS: ${id} missing`);
+    getNodeProps(node).geometry.move({
+      x: translate[0] | 0,
+      y: translate[1] | 0,
+    });
+    if (!node.expanded) return;
+    for (const cid of g.children(id)) {
+      translateDFS(cid, translate);
+    }
+  }
+
+  function layoutDFS(id: NodeId): Circle & { id: NodeId } {
+    const node = assertExists(g.node(id), `children::layout::layoutDFS: ${id} missing`);
+    const { expanded } = node;
+    const { geometry } = getNodeProps(node);
+    const { baseRadius, hullRotation } = getGraphProps(g);
+    geometry.moveTo({ x: 0, y: 0 });
+
+    const children = g.children(id);
+    const childrenCount = children.size;
+
+    if (childrenCount === 0 || !expanded) {
+      // No children to lay out
+      return { id, x: 0, y: 0, r: geometry.height / 2 };
+    }
+
+    // Recursively layout all children first
+    const circles: Array<Circle & { id: NodeId }> = [];
+    for (const cid of children) {
+      circles.push(layoutDFS(cid));
+    }
+
+    // Arrange all children around the hull
+    const boundsRadius = smallestIntersectingRadius(
+      circles.map((a) => a.r),
+      2 * baseRadius,
+    );
+    let i = 0;
+    for (const circle of circles.sort((a, b) => a.id.localeCompare(b.id))) {
+      // Lay children out circularly, starting with a slight rotational offset
+      const position = getPositionOnCircle(boundsRadius, childrenCount, i++, -hullRotation);
+
+      circle.x = position.x;
+      circle.y = position.y;
+    }
+
+    // Find the smallest bounding circle
+    const bounds = { ...getSmallestEnclosingCircle(circles, baseRadius), id };
+
+    // Readjust children to center of smallest circle
+    for (const circle of circles) {
+      circle.x -= bounds.x;
+      circle.y -= bounds.y;
+      translateDFS(circle.id, [circle.x, circle.y]);
+    }
+
+    // Adjust local size
+    geometry.resize(bounds.r | 0);
+    return bounds;
+  }
+
+  for (const id of g.children()) {
+    layoutDFS(id);
+  }
+}