@knowvah/dot-engine 0.1.0

package/src/layout/patchwork/tree-map.ts

@@ -0,0 +1,183 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * Squarified treemap algorithm (tree_map.c port).
+ *
+ * Implements the squarified treemap layout primitive: given a sorted
+ * (descending) array of areas and a fill rectangle, assigns one
+ * center-based Rectangle to each item while minimising aspect ratio.
+ *
+ * @see lib/patchwork/tree_map.c
+ * @see lib/patchwork/tree_map.h
+ */
+
+// ---------------------------------------------------------------------------
+// Rectangle type
+// ---------------------------------------------------------------------------
+
+/**
+ * Center-based rectangle used by the squarified treemap algorithm.
+ * x[0] = center-x, x[1] = center-y.
+ * size[0] = width, size[1] = height.
+ *
+ * @see lib/patchwork/tree_map.h:rectangle
+ */
+export interface Rectangle {
+  x: [number, number];
+  size: [number, number];
+}
+
+// ---------------------------------------------------------------------------
+// Squarifier
+// ---------------------------------------------------------------------------
+
+/**
+ * Stateful worker that runs one squarified treemap layout.
+ *
+ * All mutable algorithm state is held as instance fields so that every
+ * method signature stays within the 5-parameter project limit.
+ *
+ * @see lib/patchwork/tree_map.c:squarify
+ */
+class Squarifier {
+  // inputs
+  private readonly area: readonly number[];
+  private readonly recs: Rectangle[];
+  // per-recursion state (reset between strip levels)
+  private nadded = 0;
+  private maxarea = 0;
+  private minarea = 1;
+  private totalarea = 0;
+  private asp = 1;
+  private offset = 0;
+
+  constructor(area: readonly number[], recs: Rectangle[]) {
+    this.area = area;
+    this.recs = recs;
+  }
+
+  /** Place nadded items left-to-right at top of a tall fillrec. */
+  private placeTall(nadded: number, totalarea: number, fillrec: Rectangle): void {
+    const w = Math.min(fillrec.size[0], fillrec.size[1]);
+    const hh = totalarea / w;
+    const topY = fillrec.x[1] + 0.5 * fillrec.size[1] - hh / 2;
+    let xx = fillrec.x[0] - fillrec.size[0] / 2;
+    for (let i = 0; i < nadded; i++) {
+      const ww = this.area[this.offset + i]! / hh;
+      this.recs[this.offset + i] = { x: [xx + ww / 2, topY], size: [ww, hh] };
+      xx += ww;
+    }
+  }
+
+  /** Place nadded items top-to-bottom at left of a wide fillrec. */
+  private placeWide(nadded: number, totalarea: number, fillrec: Rectangle): void {
+    const w = Math.min(fillrec.size[0], fillrec.size[1]);
+    const ww = totalarea / w;
+    const leftX = fillrec.x[0] - 0.5 * fillrec.size[0] + ww / 2;
+    let yy = fillrec.x[1] + fillrec.size[1] / 2;
+    for (let i = 0; i < nadded; i++) {
+      const hh = this.area[this.offset + i]! / ww;
+      this.recs[this.offset + i] = { x: [leftX, yy - hh / 2], size: [ww, hh] };
+      yy -= hh;
+    }
+  }
+
+  /** Commit current strip and return the shrunken remaining fillrec. */
+  private commit(nadded: number, totalarea: number, fillrec: Rectangle): Rectangle {
+    const w = Math.min(fillrec.size[0], fillrec.size[1]);
+    if (fillrec.size[0] <= fillrec.size[1]) {
+      this.placeTall(nadded, totalarea, fillrec);
+      const hh = totalarea / w;
+      return {
+        x: [fillrec.x[0], fillrec.x[1] - hh / 2],
+        size: [fillrec.size[0], fillrec.size[1] - hh],
+      };
+    }
+    this.placeWide(nadded, totalarea, fillrec);
+    const ww = totalarea / w;
+    return {
+      x: [fillrec.x[0] + ww / 2, fillrec.x[1]],
+      size: [fillrec.size[0] - ww, fillrec.size[1]],
+    };
+  }
+
+  /** Try adding the next item; return true if aspect ratio improves. */
+  private tryAdd(n: number, fillrec: Rectangle): boolean {
+    if (this.nadded >= n) return false;
+    const w = Math.min(fillrec.size[0], fillrec.size[1]);
+    const next = this.area[this.offset + this.nadded]!;
+    const newmax = Math.max(this.maxarea, next);
+    const newmin = Math.min(this.minarea, next);
+    const s = this.totalarea + next;
+    const h = s / w;
+    const newasp = Math.max(h / (newmin / h), (newmax / h) / h);
+    if (newasp > this.asp) return false;
+    this.nadded++;
+    this.maxarea = newmax;
+    this.minarea = newmin;
+    this.totalarea = s;
+    this.asp = newasp;
+    return true;
+  }
+
+  /**
+   * Run the squarified layout for n items starting at this.offset.
+   *
+   * @see lib/patchwork/tree_map.c:squarify
+   */
+  run(n: number, fillrec: Rectangle): void {
+    if (n === 0) return;
+    const w = Math.min(fillrec.size[0], fillrec.size[1]);
+    // Bootstrap: seed with first item
+    const a0 = this.area[this.offset]!;
+    this.nadded = 1;
+    this.maxarea = a0;
+    this.minarea = a0;
+    this.totalarea = a0;
+    this.asp = Math.max(a0 / (w * w), (w * w) / a0);
+    // Grow strip while aspect ratio improves
+    while (this.tryAdd(n, fillrec)) { /* tryAdd mutates state */ }
+    // Commit strip and recurse on remainder
+    const committed = this.nadded;
+    const total = this.totalarea;
+    const nextFill = this.commit(committed, total, fillrec);
+    this.offset += committed;
+    // Reset strip state for next level
+    this.nadded = 0;
+    this.maxarea = 0;
+    this.minarea = 1;
+    this.totalarea = 0;
+    this.asp = 1;
+    this.run(n - committed, nextFill);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public entry point
+// ---------------------------------------------------------------------------
+
+/**
+ * Perform a squarified treemap layout on a single level.
+ *
+ * area[] must be sorted descending. Returns null if the total area exceeds
+ * the fill rectangle's capacity (plus 0.001 float tolerance). Otherwise
+ * returns an array of n center-based rectangles.
+ *
+ * @see lib/patchwork/tree_map.c:tree_map
+ */
+export function treeMap(
+  n: number,
+  area: readonly number[],
+  fillrec: Rectangle,
+): Rectangle[] | null {
+  let total = 0;
+  for (let i = 0; i < n; i++) total += area[i]!;
+  if (total > fillrec.size[0] * fillrec.size[1] + 0.001) return null;
+
+  const recs: Rectangle[] = Array.from({ length: n }, () => ({
+    x: [0, 0] as [number, number],
+    size: [0, 0] as [number, number],
+  }));
+  new Squarifier(area, recs).run(n, fillrec);
+  return recs;
+}

package/src/layout/patchwork/tree-node.ts

@@ -0,0 +1,120 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * Internal tree node and construction helpers for the patchwork layout.
+ *
+ * Mirrors treenode_t and mkTree from lib/patchwork/patchwork.c.
+ *
+ * @see lib/patchwork/patchwork.c:treenode_t
+ * @see lib/patchwork/patchwork.c:mkTree
+ */
+
+import type { Graph } from '../../model/graph.js';
+import type { Node } from '../../model/node.js';
+import type { Rectangle } from './tree-map.js';
+
+/** @see lib/patchwork/patchwork.c:treenode_t */
+export interface TreeNode {
+  area: number;
+  childArea: number;
+  r: Rectangle;
+  leftChild: TreeNode | null;
+  rightSib: TreeNode | null;
+  kind: 'graph' | 'node';
+  ref: Graph | Node;
+  nChildren: number;
+}
+
+/** Default area when attribute is missing or zero. @see lib/patchwork/patchwork.c */
+const DFLT_SZ = 1.0;
+
+/** Area multiplier for numerical stability. @see lib/patchwork/patchwork.c */
+const SCALE = 1000.0;
+
+/** @see lib/patchwork/patchwork.c:getArea */
+export function getArea(attrs: Map<string, string>): number {
+  const raw = attrs.get('area');
+  let area = raw !== undefined ? parseFloat(raw) : DFLT_SZ;
+  if (!isFinite(area) || area === 0) area = DFLT_SZ;
+  return area * SCALE;
+}
+
+/** @see lib/patchwork/patchwork.c:fullArea (mp parameter) */
+export function getInset(attrs: Map<string, string>): number {
+  const raw = attrs.get('inset');
+  if (raw === undefined) return 0;
+  const v = parseFloat(raw);
+  return isFinite(v) ? v : 0;
+}
+
+/** wid = 2*inset + sqrt(childArea), area = wid². @see lib/patchwork/patchwork.c:fullArea */
+export function fullArea(childArea: number, inset: number): number {
+  const wid = 2.0 * inset + Math.sqrt(childArea);
+  return wid * wid;
+}
+
+/** Mutable accumulator used during tree construction. */
+export interface ChildAccum {
+  first: TreeNode | null;
+  prev: TreeNode | null;
+  area: number;
+  nChildren: number;
+}
+
+/** Append all cluster children of g to accum. @see lib/patchwork/patchwork.c:mkTree */
+export function appendClusters(g: Graph, sparent: Map<Node, Graph>, accum: ChildAccum): void {
+  for (const subg of g.info.clust ?? []) {
+    const cp = mkTree(subg, sparent);
+    accum.nChildren++;
+    accum.area += cp.area;
+    if (!accum.first) accum.first = cp;
+    if (accum.prev) accum.prev.rightSib = cp;
+    accum.prev = cp;
+  }
+}
+
+/** Append unclaimed direct nodes of g to accum. @see lib/patchwork/patchwork.c:mkTree */
+export function appendNodes(g: Graph, sparent: Map<Node, Graph>, accum: ChildAccum): void {
+  for (const n of g.nodes.values()) {
+    if (sparent.has(n)) continue;
+    const cp: TreeNode = {
+      area: getArea(n.attrs),
+      childArea: 0,
+      r: { x: [0, 0], size: [0, 0] },
+      leftChild: null, rightSib: null,
+      kind: 'node', ref: n, nChildren: 0,
+    };
+    accum.nChildren++;
+    accum.area += cp.area;
+    if (!accum.first) accum.first = cp;
+    if (accum.prev) accum.prev.rightSib = cp;
+    accum.prev = cp;
+    sparent.set(n, g);
+  }
+}
+
+/**
+ * Recursively build the internal TreeNode tree from a Graph hierarchy.
+ * Nodes already owned by a cluster (sparent set) are skipped.
+ * @see lib/patchwork/patchwork.c:mkTree
+ */
+export function mkTree(g: Graph, sparent: Map<Node, Graph>): TreeNode {
+  const p: TreeNode = {
+    area: 0, childArea: 0,
+    r: { x: [0, 0], size: [0, 0] },
+    leftChild: null, rightSib: null,
+    kind: 'graph', ref: g, nChildren: 0,
+  };
+  const accum: ChildAccum = { first: null, prev: null, area: 0, nChildren: 0 };
+  appendClusters(g, sparent, accum);
+  appendNodes(g, sparent, accum);
+  p.nChildren = accum.nChildren;
+  if (accum.nChildren > 0) {
+    p.childArea = accum.area;
+    p.area = fullArea(accum.area, getInset(g.attrs));
+  } else {
+    p.area = getArea(g.attrs);
+  }
+  p.leftChild = accum.first;
+  return p;
+}

package/src/layout/sfdp/index.ts

@@ -0,0 +1,231 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * sfdp layout engine entry point — the sfdp_layout pipeline:
+ * init → prism0 control resolution → per-component multilevel
+ * spring-electrical embedding → straight-line splines → component
+ * packing → postprocess.
+ *
+ * Spec read at the 15.0.0 tag.
+ *
+ * @see lib/sfdpgen/sfdpinit.c:sfdp_layout (15.0.0)
+ */
+
+import type { Graph } from '../../model/graph.js';
+import type { LayoutEngine } from '../../gvc/context.js';
+import { csrand } from '../../common/crand.js';
+import { graphInit } from '../../common/graph-init.js';
+import { setEdgeTypeFromAttr } from '../dot/index.js';
+import { EDGETYPE_LINE, splineEdgesShifted } from '../neato/splines.js';
+import { sepFactor, DFLT_MARGIN } from '../neato/sep-factor.js';
+import {
+  ccomps,
+  computeSubgraphBB,
+  getPackInfo,
+  packSubgraphs,
+  normalizeGraphBB,
+  PackMode,
+  type PackInfo,
+} from '../pack/index.js';
+import { CL_OFFSET } from '../twopi/pipeline.js';
+import { placeGraphLabel } from '../dot/position-bbox.js';
+import { gvPostprocess } from '../../common/postproc.js';
+import { aggetGraph } from '../fdp/fdp-model.js';
+import { overlapPrismTries } from '../neato/fdp-adjust.js';
+import { adjustNodesScale } from '../neato/sc-adjust.js';
+import { lateDouble } from '../../common/nodeinit.js';
+import {
+  type SpringElectricalControl,
+  springElectricalControlNew,
+} from './spring-electrical.js';
+import { multilevelSpringElectricalEmbedding } from './spring-driver.js';
+import {
+  sfdpInitGraph,
+  sfdpCleanup,
+  tuneControl,
+  makeMatrix,
+  getSizes,
+  getPos,
+} from './init.js';
+
+export { sfdpInitGraph, sfdpCleanup, tuneControl, makeMatrix, getSizes, getPos };
+export { multilevelSpringElectricalEmbedding };
+
+/** GD_ndim is fixed at 2 — see sfdpInitGraph. */
+const DIM = 2;
+
+/**
+ * Lay out one connected graph: adjacency matrix, label half-sizes,
+ * starting positions, the multilevel embedding, ND_pos write-back.
+ * @see lib/sfdpgen/sfdpinit.c:sfdpLayout (the static per-component fn)
+ */
+export function sfdpLayoutComponent(
+  g: Graph, ctrl: SpringElectricalControl, pad: { x: number; y: number },
+): void {
+  const A = makeMatrix(g);
+  // edge_labeling_scheme > 0 (|edgelabel| nodes) is not ported.
+  const sizes = ctrl.overlap >= 0 ? getSizes(g, pad) : null;
+  const pos = getPos(g, DIM);
+
+  multilevelSpringElectricalEmbedding(DIM, A, ctrl, sizes, pos);
+
+  for (const n of g.nodes.values()) {
+    const i = n.info.id!;
+    n.info.pos = [pos[i * DIM]!, pos[i * DIM + 1]!];
+  }
+}
+
+/**
+ * Resolve the tuned control, component padding, and whether a post-layout
+ * overlap pass is needed. The reference binary is built with GTS, so
+ * graphAdjustMode's default is "prism0" → AM_PRISM value 0 scaling −4.
+ *
+ * When the mode resolves to AM_PRISM (prism*, or the boolean/false fallback),
+ * overlap removal runs inside sfdp: ctrl.overlap = value (0 for prism0, 1000
+ * for prism/false), ctrl.initialScaling = overlap_scaling (default −4), and
+ * doAdjust is false. Otherwise (scale family, AM_NONE, unported modes) sfdp's
+ * in-layout removal is off (ctrl.overlap = −1) and doAdjust drives a
+ * post-layout removeOverlapWith (adjustNodesScale).
+ * @see lib/neatogen/adjust.c:graphAdjustMode / getAdjustMode (15.0.0)
+ * @see lib/sfdpgen/sfdpinit.c:sfdp_layout (HAVE_GTS branch)
+ */
+function resolveControl(g: Graph): {
+  ctrl: SpringElectricalControl; pad: { x: number; y: number }; doAdjust: boolean;
+} {
+  const ctrl = springElectricalControlNew();
+  tuneControl(g, ctrl);
+  const pad = { x: DFLT_MARGIN / 72, y: DFLT_MARGIN / 72 }; // PS2INCH
+
+  // graphAdjustMode(g, &am, "prism0"): agget NULL (unset) → "prism0" default.
+  const overlap = aggetGraph(g, 'overlap');
+  const flag = overlap === undefined ? 'prism0' : overlap;
+  const ntry = overlapPrismTries(flag);
+  if (ntry !== null) {
+    // AM_PRISM && doAdjust: overlap removal happens inside sfdp.
+    ctrl.overlap = ntry;
+    ctrl.initialScaling = lateDouble(
+      g.root.attrs.get('overlap_scaling'), -4.0, -1.e10);
+    const sep = sepFactor(g);
+    if (sep.doAdd) {
+      pad.x = sep.x / 72;
+      pad.y = sep.y / 72;
+    }
+    return { ctrl, pad, doAdjust: false };
+  }
+  // Non-PRISM: turn off in-sfdp removal; run removeOverlapWith after layout.
+  ctrl.overlap = -1;
+  return { ctrl, pad, doAdjust: true };
+}
+
+/**
+ * Disconnected graphs: embed and route each component (the rand()
+ * stream threads across components — coarsening permutations draw from
+ * wherever the previous component's srand(123) embedding left it),
+ * then pack in l_node mode with spline-aware shifting.
+ * @see lib/sfdpgen/sfdpinit.c:sfdp_layout (ncc > 1 branch)
+ */
+function layoutComponents(
+  g: Graph, comps: Graph[],
+  ctrl: SpringElectricalControl, pad: { x: number; y: number },
+  doAdjust: boolean,
+): void {
+  const pinfo: PackInfo = {
+    aspect: 1, sz: 0, margin: CL_OFFSET, doSplines: false,
+    mode: PackMode.Node, fixed: null, vals: null, flags: 0,
+  };
+  getPackInfo(g, PackMode.Node, CL_OFFSET, pinfo);
+  pinfo.doSplines = true; // C sets it after getPackInfo
+
+  for (const sg of comps) {
+    // ccomps already node-induces edges (graphviz_node_induce).
+    sfdpLayoutComponent(sg, ctrl, pad);
+    if (doAdjust) adjustNodesScale(sg); // removeOverlapWith (non-PRISM modes)
+    // @see lib/sfdpgen/sfdpinit.c:284 (setEdgeType FUNCTION, per component)
+    setEdgeTypeFromAttr(sg, EDGETYPE_LINE);
+    splineEdgesShifted(sg);
+  }
+  packSubgraphs(comps.length, comps, g, pinfo);
+}
+
+/**
+ * dotneato_postprocess equivalent: translate the drawing to the
+ * origin, set the root bb, place the graph label.
+ * @see lib/common/postproc.c:gv_postprocess
+ */
+function postprocess(g: Graph, singleComponent: boolean): void {
+  // Single-component: native never re-runs compute_bb after routing (C
+  // gv_postprocess only translates), so g.info.bb stays the box
+  // splineEdgesShifted left — the neatoSetAspect-scaled box grown by
+  // clip_and_install curve extents. A geometric recompute here would clobber
+  // the ratio=fill scale: node half-sizes are (correctly) not scaled by the
+  // fill factor, so a node-box∪curve union lands short of the scaled box by
+  // node_size*(f-1) on the stretched axis. Just translate to the origin,
+  // exactly as neato/splines.ts:1000-1003 warns. Multi-component: pack re-runs
+  // compute_bb post-routing over raw control points (hull).
+  // @see lib/common/postproc.c:599 gv_postprocess (never recomputes GD_bb)
+  if (singleComponent) {
+    normalizeGraphBB(g);
+  } else {
+    // Multi-component: packSubgraphs already placed the components; C runs
+    // compute_bb (hull) with NO shift, then gv_postprocess whose
+    // translate_drawing shifts to the origin AFTER addXLabels. Shifting here
+    // (before addXLabels) rounds the xlabel obstacle rects (objplp2rect uses
+    // round()) in the origin frame instead of C's packed frame, tipping the
+    // edge-label side-selection knife-edge (same X, wrong Y). Drop the
+    // premature shift and let gvPostprocess→translateDrawing do it.
+    // @see neato/index.ts layoutComponents (commit 1e7515d — identical bug/fix)
+    g.info.bb = computeSubgraphBB(g, 0, false);
+  }
+  // C sfdp_layout ends with dotneato_postprocess(g) = gv_postprocess(g, 1):
+  // place_graph_label, then addXLabels — the pass that positions the *edge*
+  // labels (sfdp never sets ED_label(e)->pos during routing).
+  // @see lib/sfdpgen/sfdpinit.c:295
+  placeGraphLabel(g);
+  gvPostprocess(g);
+}
+
+/**
+ * The complete sfdp pipeline.
+ *
+ * The C libc rand() stream is process-global and each reference SVG
+ * was produced by a fresh process; reset the modeled stream to its
+ * process-start state (srand(1)) per layout so repeated renders in one
+ * JS process reproduce the C binary.
+ * @see lib/sfdpgen/sfdpinit.c:sfdp_layout
+ */
+export function sfdpLayout(g: Graph): void {
+  // C: gvLayoutJobs runs graph_init(g, LAYOUT_USES_RANKDIR) before sfdp_layout.
+  // sfdp does not set the flag → useRankdir=false. This is also the ONLY place
+  // sfdp gets a rankdir at all: it previously never ran SET_RANKDIR, so
+  // GD_realrankdir stayed TB even for rankdir=LR graphs (record shapes read it).
+  // @see lib/common/input.c:600, lib/gvc/gvlayout.c:81
+  graphInit(g, false);
+  sfdpInitGraph(g);
+  csrand(1); // process-start rand() state on the reference platform
+
+  // Single-component graphs never reach pack, so their final bb keeps the
+  // curve-refined box grown during routing; multi-component graphs are packed,
+  // and pack re-runs compute_bb (control-point hull). @see postprocess.
+  let singleComponent = true;
+  if (g.nodes.size > 0) {
+    const { ctrl, pad, doAdjust } = resolveControl(g);
+    const comps = ccomps(g, '_sfdp_cc');
+    singleComponent = comps.length === 1;
+    if (singleComponent) {
+      sfdpLayoutComponent(g, ctrl, pad);
+      if (doAdjust) adjustNodesScale(g); // removeOverlapWith (non-PRISM modes)
+      splineEdgesShifted(g); // C spline_edges: shift + coord sync + route
+    } else {
+      layoutComponents(g, comps, ctrl, pad, doAdjust);
+    }
+  }
+
+  postprocess(g, singleComponent);
+}
+
+/** @see lib/gvc/gvplugin.h:gvlayout_engine_s */
+export const SFDP_LAYOUT_ENGINE: LayoutEngine = {
+  type: 'sfdp',
+  layout: sfdpLayout,
+  cleanup: sfdpCleanup,
+};