@knowvah/dot-engine 0.1.0

package/src/layout/osage/index.ts

@@ -0,0 +1,548 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * Osage cluster-packing layout engine.
+ *
+ * Faithful port of lib/osage/osageinit.c. Arranges clusters and loose
+ * nodes by recursively packing bounding rectangles, then routes edges.
+ *
+ * @see lib/osage/osageinit.c
+ * @see lib/osage/osage.h
+ */
+
+import type { Graph } from '../../model/graph.js';
+import type { Node } from '../../model/node.js';
+import type { Box } from '../../model/geom.js';
+import type { LayoutEngine } from '../../gvc/context.js';
+import type { PackInfo } from '../pack/index.js';
+import {
+  PackMode,
+  getPackInfo,
+  putRects,
+  PK_USER_VALS,
+} from '../pack/index.js';
+import { neatoInitNode, neatoSetAspect } from '../neato/init.js';
+import { parseNeatoDrawing } from '../neato/set-aspect.js';
+import { commonInitNode, layoutMeasurer, lateInt } from '../../common/nodeinit.js';
+import { initEdgeLabels } from '../../common/edge-label-init.js';
+import { nodeAttr } from '../../common/poly-init.js';
+import { splineEdges, EDGETYPE_NONE, EDGETYPE_LINE } from '../neato/splines.js';
+import { setEdgeTypeFromAttr } from '../dot/index.js';
+// Engine-neutral C common functions, currently parked under layout/dot:
+import { doGraphLabel } from '../dot/graph-label.js';
+import { graphInit } from '../../common/graph-init.js';
+import { mapbool } from '../dot/rank.js';
+import { BOTTOM_IX, TOP_IX } from '../dot/position-aux.js';
+import { placeGraphLabel } from '../dot/position-bbox.js';
+import { gvPostprocess } from '../../common/postproc.js';
+
+// ---------------------------------------------------------------------------
+// Constants
+// @see lib/osage/osageinit.c
+// ---------------------------------------------------------------------------
+
+/** Default bounding-box size (points) for an empty cluster with no label.
+ * @see lib/osage/osageinit.c:#define DFLT_SZ 18
+ */
+const DFLT_SZ = 18;
+
+/**
+ * Default margin in points passed to getPackInfo.
+ * @see lib/neatogen/adjust.h:DFLT_MARGIN (4 points)
+ * @see lib/osage/osageinit.c:layout (DFLT_MARGIN argument to getPackInfo)
+ */
+const DFLT_MARGIN = 4;
+
+// ---------------------------------------------------------------------------
+// PARENT helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Return the owning cluster for a node, or null if unclaimed.
+ *
+ * In C this is the PARENT(n) macro: `(Agraph_t*)ND_alg(n)`.
+ * Osage repurposes ND_alg to store cluster ownership during layout.
+ *
+ * @see lib/osage/osageinit.c:#define PARENT(n)
+ */
+export function PARENT(n: Node): Graph | null {
+  if (n.info.alg?.kind === 'osage') {
+    return n.info.alg.ownerCluster;
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// isCluster helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Return true if the subgraph is a cluster: the root, a name beginning
+ * (case-insensitively) with "cluster", OR a truthy `cluster` attribute. The
+ * name-only test dropped `cluster=true` subgraphs (2717's `domestic_cats`).
+ *
+ * @see lib/common/utils.c:695 is_a_cluster
+ */
+export function isCluster(g: Graph): boolean {
+  if (g === g.root) return true;
+  if (g.name.toLowerCase().startsWith('cluster')) return true;
+  return mapbool(g.attrs.get('cluster'));
+}
+
+// ---------------------------------------------------------------------------
+// clusterInitGraph
+// ---------------------------------------------------------------------------
+
+/**
+ * Initialize all nodes and edges in the graph for osage layout.
+ *
+ * Forces 2-D layout (ndim=2), initialises each node with neatoInitNode
+ * (sets default width/height in inches), then computes lw/rw/ht in points.
+ *
+ * @see lib/osage/osageinit.c:cluster_init_graph
+ */
+export function clusterInitGraph(g: Graph): void {
+  // C: gvLayoutJobs runs graph_init(g, LAYOUT_USES_RANKDIR) before osage_layout;
+  // osage does not set the flag → useRankdir=false. graph_init also creates the
+  // ROOT graph label: the layout() label block widens rootbb by it and adds its
+  // height via GD_border[TOP/BOTTOM]. Clusters get theirs via mkClusters.
+  // @see lib/common/input.c:600, lib/gvc/gvlayout.c:81, osageinit.c:168
+  graphInit(g, false);
+  // C: setEdgeType(g, EDGETYPE_LINE) — osage defaults edges to straight lines,
+  // but honors an explicit `splines` attr (ortho/curved/none). Without this the
+  // edge-type nibble stays EDGETYPE_NONE and osageLayout skips splineEdges
+  // entirely, emitting nodes but no edges. @see lib/osage/osageinit.c:51,
+  // lib/common/utils.c:setEdgeType (reads agget(g,"splines"))
+  setEdgeTypeFromAttr(g, EDGETYPE_LINE);
+  g.info.ndim = 2;
+  const measurer = layoutMeasurer(g);
+  for (const n of g.nodes.values()) {
+    neatoInitNode(n, 2);
+    if (measurer !== undefined) {
+      // C: neato_init_node -> common_init_node + gv_nodesize sizes
+      // every node from its label. @see lib/osage/osageinit.c:layout
+      commonInitNode(n, g);
+      continue;
+    }
+    const wPts = (n.info.width || 0.75) * 72;
+    const hPts = (n.info.height || 0.5) * 72;
+    n.info.lw = wPts / 2;
+    n.info.rw = wPts / 2;
+    n.info.ht = hPts;
+  }
+  // C cluster_init_graph loops edges calling common_init_edge, which creates the
+  // edge label (ED_label). The unset label is then positioned by addXLabels
+  // (run in gvPostprocess) at the edge midpoint. @see lib/osage/osageinit.c:57-64
+  if (measurer !== undefined) {
+    for (const e of g.edges) initEdgeLabels(e, g, measurer);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// mkClusters helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Recursively scan subgraphs of g, appending clusters to clist.
+ * Non-cluster subgraphs are transparent — their cluster children are promoted.
+ * @see lib/osage/osageinit.c:mkClusters (inner loop)
+ */
+export function mkClustersInto(
+  g: Graph,
+  clist: Array<Graph | null>,
+  parent: Graph,
+): void {
+  for (const subg of g.subgraphs.values()) {
+    if (isCluster(subg)) {
+      subg.info.bb = subg.info.bb ??
+        { ll: { x: 0, y: 0 }, ur: { x: 0, y: 0 } };
+      // C binds Agraphinfo_t then builds the cluster label + border.
+      doGraphLabel(subg, layoutMeasurer(subg));
+      clist.push(subg);
+      mkClusters(subg, null, subg);
+    } else {
+      mkClusters(subg, clist as Graph[], parent);
+    }
+  }
+}
+
+/**
+ * Discover all cluster subgraphs in g and populate GraphInfo.clust /
+ * GraphInfo.n_cluster for each cluster found.
+ *
+ * Non-cluster subgraphs are transparent: their cluster children are
+ * promoted to the nearest enclosing cluster ancestor.
+ *
+ * @see lib/osage/osageinit.c:mkClusters
+ */
+export function mkClusters(
+  g: Graph,
+  pclist: Graph[] | null,
+  parent: Graph,
+): void {
+  if (pclist === null) {
+    const list: Array<Graph | null> = [null];
+    mkClustersInto(g, list, parent);
+    const real = list.filter((x): x is Graph => x !== null);
+    g.info.n_cluster = real.length;
+    if (real.length > 0) g.info.clust = real;
+  } else {
+    mkClustersInto(g, pclist, parent);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// layout helpers — all exported so Lizard resets CCN at each boundary
+// ---------------------------------------------------------------------------
+
+/** Clone a Box (shallow copy of nested points). */
+export function cloneBox(b: Box): Box {
+  return { ll: { x: b.ll.x, y: b.ll.y }, ur: { x: b.ur.x, y: b.ur.y } };
+}
+
+/** Build a PackInfo initialised from graph attributes. @see lib/osage/osageinit.c:layout */
+export function buildPackInfo(g: Graph): PackInfo {
+  const pinfo: PackInfo = {
+    aspect: 1, sz: 0, margin: DFLT_MARGIN,
+    doSplines: false, mode: PackMode.Array,
+    fixed: null, vals: null, flags: 0,
+  };
+  getPackInfo(g, PackMode.Array, DFLT_MARGIN, pinfo);
+  if (pinfo.mode < PackMode.Graph) pinfo.mode = PackMode.Graph;
+  return pinfo;
+}
+
+/** Holds the parallel arrays built before calling putRects. */
+export interface OsageChildLists {
+  gs: Box[];
+  childGraphs: Graph[];
+  childNodes: Node[];
+  vals: number[];
+}
+
+/** Append one subcluster to the child lists. @see lib/osage/osageinit.c:layout (sortv via late_int) */
+export function addSubcluster(
+  lists: OsageChildLists,
+  subg: Graph,
+  useVals: boolean,
+): void {
+  lists.gs.push(cloneBox(subg.info.bb));
+  lists.childGraphs.push(subg);
+  if (useVals) lists.vals.push(lateInt(subg.attrs.get('sortv'), 0, 0));
+}
+
+/** Append one loose node to the child lists and claim it for cluster g. */
+export function addLooseNode(
+  lists: OsageChildLists,
+  n: Node,
+  g: Graph,
+  useVals: boolean,
+): void {
+  n.info.alg = { kind: 'osage', ownerCluster: g };
+  lists.gs.push({
+    ll: { x: 0, y: 0 },
+    ur: { x: n.info.lw + n.info.rw, y: n.info.ht },
+  });
+  lists.childNodes.push(n);
+  if (useVals) lists.vals.push(lateInt(nodeAttr(n, g, 'sortv'), 0, 0));
+}
+
+/** Build the child lists for g's direct children (subclusters + loose nodes). */
+export function buildChildLists(
+  g: Graph,
+  nClust: number,
+  nvs: number,
+  useVals: boolean,
+): OsageChildLists {
+  const lists: OsageChildLists = { gs: [], childGraphs: [], childNodes: [], vals: [] };
+  for (let i = 1; i <= nClust; i++) {
+    addSubcluster(lists, g.info.clust![i - 1], useVals);
+  }
+  if (g.nodes.size - nvs > 0) {
+    // C iterates agfstnode(g) — AGSEQ (root creation) order (osageinit.c:248).
+    // A cluster's node Map is in block-reference order, which differs when the
+    // cluster re-references nodes declared earlier; the loose-node order feeds
+    // the packing rectangle assignment.
+    const nodes = [...g.nodes.values()].sort((a, b) => a.id - b.id);
+    for (const n of nodes) {
+      if (n.info.alg === undefined) addLooseNode(lists, n, g, useVals);
+    }
+  }
+  return lists;
+}
+
+/** Raw bounding box accumulator returned by applyOffsets. */
+export interface RawBB {
+  llx: number; lly: number; urx: number; ury: number;
+}
+
+/** Apply putRects translation offsets; return the union bounding box. */
+export function applyOffsets(lists: OsageChildLists, pts: Array<{ x: number; y: number }>): RawBB {
+  let llx = Infinity, lly = Infinity, urx = -Infinity, ury = -Infinity;
+  const ng = lists.childGraphs.length;
+  for (let i = 0; i < lists.gs.length; i++) {
+    const p = pts[i]!;
+    const b = lists.gs[i]!;
+    const x0 = b.ll.x + p.x, y0 = b.ll.y + p.y;
+    const x1 = b.ur.x + p.x, y1 = b.ur.y + p.y;
+    if (x0 < llx) llx = x0;
+    if (y0 < lly) lly = y0;
+    if (x1 > urx) urx = x1;
+    if (y1 > ury) ury = y1;
+    if (i < ng) {
+      lists.childGraphs[i]!.info.bb = { ll: { x: x0, y: y0 }, ur: { x: x1, y: y1 } };
+    } else {
+      const nd = lists.childNodes[i - ng]!;
+      nd.info.coord = { x: (x0 + x1) / 2, y: (y0 + y1) / 2 };
+    }
+  }
+  return { llx, lly, urx, ury };
+}
+
+/** Widen rbb horizontally to fit the graph label (if any). */
+export function applyLabelExpansion(g: Graph, total: number, rbb: RawBB): RawBB {
+  const labelDim = (g.info.label as { dimen?: { x: number; y: number } } | undefined)?.dimen;
+  if (!labelDim) return rbb;
+  let { llx, lly, urx, ury } = rbb;
+  if (total === 0) return { llx: 0, lly: 0, urx: labelDim.x, ury: labelDim.y };
+  const d = labelDim.x - (urx - llx);
+  if (d > 0) { llx -= d / 2; urx += d / 2; }
+  return { llx, lly, urx, ury };
+}
+
+/** Add margin and border padding to rbb.
+ * C: rootbb.LL.y -= margin + GD_border(g)[BOTTOM_IX].y (index 0, NOT 3);
+ *    rootbb.UR.y += margin + GD_border(g)[TOP_IX].y.
+ * @see lib/osage/osageinit.c:186-187, lib/common/const.h:111-114 */
+export function addMarginAndBorder(g: Graph, margin: number, rbb: RawBB): RawBB {
+  let { llx, lly, urx, ury } = rbb;
+  const border = g.info.border;
+  const bottomY = border ? border[BOTTOM_IX]!.y : 0;
+  const topY = border ? border[TOP_IX]!.y : 0;
+  llx -= margin; urx += margin;
+  lly -= margin + bottomY; ury += margin + topY;
+  return { llx, lly, urx, ury };
+}
+
+/** Subtract rbb.ll from all child cluster bbs (translate to origin). */
+export function originShiftClusters(childGraphs: Graph[], rbb: RawBB): void {
+  const { llx, lly } = rbb;
+  for (const sg of childGraphs) {
+    const sbb = sg.info.bb;
+    sg.info.bb = {
+      ll: { x: sbb.ll.x - llx, y: sbb.ll.y - lly },
+      ur: { x: sbb.ur.x - llx, y: sbb.ur.y - lly },
+    };
+  }
+}
+
+/** Subtract rbb.ll from all child node coords (translate to origin). */
+export function originShiftNodes(childNodes: Node[], rbb: RawBB): void {
+  const { llx, lly } = rbb;
+  for (const nd of childNodes) {
+    nd.info.coord = {
+      x: nd.info.coord.x - llx,
+      y: nd.info.coord.y - lly,
+    };
+  }
+}
+
+/** Translate all children so the cluster's LL becomes (0,0). */
+export function translateToOrigin(lists: OsageChildLists, rbb: RawBB): void {
+  originShiftClusters(lists.childGraphs, rbb);
+  originShiftNodes(lists.childNodes, rbb);
+}
+
+// ---------------------------------------------------------------------------
+// osageLayoutRec — split into exported sub-steps for Lizard
+// ---------------------------------------------------------------------------
+
+/**
+ * Recurse into each direct subcluster; return total node count across them.
+ * @see lib/osage/osageinit.c:layout (subcluster recursion)
+ */
+export function recurseSubclusters(g: Graph, nClust: number, depth: number): number {
+  let nvs = 0;
+  for (let i = 1; i <= nClust; i++) {
+    const subg = g.info.clust![i - 1];
+    osageLayoutRec(subg, depth + 1);
+    nvs += subg.nodes.size;
+  }
+  return nvs;
+}
+
+/**
+ * Pack the direct children of g and set g.info.bb.
+ * @see lib/osage/osageinit.c:layout (rect-packing block)
+ */
+export function packChildren(
+  g: Graph, nClust: number, nvs: number, total: number, depth: number,
+): void {
+  const pinfo = buildPackInfo(g);
+  const useVals = pinfo.mode === PackMode.Array && (pinfo.flags & PK_USER_VALS) !== 0;
+  const lists = buildChildLists(g, nClust, nvs, useVals);
+  if (useVals && lists.vals.length > 0) pinfo.vals = lists.vals;
+  const pts = putRects(lists.gs.length, lists.gs, pinfo);
+  if (!pts) return;
+  let rbb = applyOffsets(lists, pts);
+  rbb = applyLabelExpansion(g, total, rbb);
+  rbb = addMarginAndBorder(g, depth > 0 ? pinfo.margin / 2 : 0, rbb);
+  translateToOrigin(lists, rbb);
+  g.info.bb = { ll: { x: 0, y: 0 }, ur: { x: rbb.urx - rbb.llx, y: rbb.ury - rbb.lly } };
+}
+
+/**
+ * Recursively pack all direct children (subclusters + loose nodes) of g
+ * into a bounding box. After this pass every cluster has LL=(0,0).
+ *
+ * @see lib/osage/osageinit.c:layout
+ */
+export function osageLayoutRec(g: Graph, depth: number): void {
+  const nClust = g.info.n_cluster ?? 0;
+  const nvs = recurseSubclusters(g, nClust, depth);
+  const total = g.nodes.size - nvs + nClust;
+  if (total === 0 && !g.info.label) {
+    g.info.bb = { ll: { x: 0, y: 0 }, ur: { x: DFLT_SZ, y: DFLT_SZ } };
+    return;
+  }
+  packChildren(g, nClust, nvs, total, depth);
+}
+
+// ---------------------------------------------------------------------------
+// osageReposition helpers — exported for Lizard
+// ---------------------------------------------------------------------------
+
+/** Shift directly-owned node coords by bb.ll to convert to absolute. */
+export function repositionNodes(g: Graph, bb: Box): void {
+  for (const n of g.nodes.values()) {
+    if (PARENT(n) !== g) continue;
+    n.info.coord = {
+      x: n.info.coord.x + bb.ll.x,
+      y: n.info.coord.y + bb.ll.y,
+    };
+  }
+}
+
+/** Shift a subcluster bb by parentBb.ll. */
+export function shiftSubclusterBb(subg: Graph, parentBb: Box): void {
+  const sbb = subg.info.bb;
+  subg.info.bb = {
+    ll: { x: sbb.ll.x + parentBb.ll.x, y: sbb.ll.y + parentBb.ll.y },
+    ur: { x: sbb.ur.x + parentBb.ll.x, y: sbb.ur.y + parentBb.ll.y },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// osageReposition
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert local (cluster-relative) coordinates to absolute root-relative
+ * coordinates by walking the cluster tree top-down and accumulating bb.ll.
+ *
+ * @see lib/osage/osageinit.c:reposition
+ */
+export function osageReposition(g: Graph, depth: number): void {
+  const bb = g.info.bb;
+  const nClust = g.info.n_cluster ?? 0;
+  if (depth > 0) repositionNodes(g, bb);
+  for (let i = 1; i <= nClust; i++) {
+    const subg = g.info.clust![i - 1];
+    if (depth > 0) shiftSubclusterBb(subg, bb);
+    osageReposition(subg, depth + 1);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// osageLayout
+// ---------------------------------------------------------------------------
+
+/**
+ * Main osage layout entry point.
+ *
+ * Pipeline:
+ * 1. clusterInitGraph — node/edge init
+ * 2. mkClusters — cluster discovery
+ * 3. osageLayoutRec — recursive rectangle packing
+ * 4. osageReposition — convert to absolute coordinates
+ * 5. splineEdges — edge routing (skipped when EDGETYPE_NONE)
+ *
+ * @see lib/osage/osageinit.c:osage_layout
+ */
+export function osageLayout(g: Graph): void {
+  clusterInitGraph(g);
+  mkClusters(g, null, g);
+  osageLayoutRec(g, 0);
+  osageReposition(g, 0);
+  // C: if GD_drawing(g)->ratio_kind, sync ND_pos from coord and run
+  // spline_edges0(g, true) — the aspect reshape + routing; else route
+  // directly. @see lib/osage/osageinit.c:324-335
+  parseNeatoDrawing(g);
+  if ((g.info.drawing?.ratioKind ?? 'none') !== 'none') {
+    for (const n of g.nodes.values()) {
+      n.info.pos = [n.info.coord.x / 72, n.info.coord.y / 72];
+    }
+    // C keeps osage's GD_bb (cluster boxes + label space included) for the
+    // aspect pass — spline_edges0 never recomputes it. A node-only
+    // computeSubgraphBB here clipped cluster tops out of the canvas (56).
+    neatoSetAspect(g);
+    splineEdges(g);
+  } else {
+    const et = g.info.flags & 0xf;
+    if (et !== EDGETYPE_NONE) splineEdges(g);
+  }
+  // C: dotneato_postprocess(g) == gv_postprocess(g, 1): position cluster labels,
+  // then add space for the root graph label, translate the drawing to origin,
+  // and place the root label. Osage previously ran only the cluster-label half,
+  // dropping the root graph label height (and any xlabels).
+  // @see lib/osage/osageinit.c:336, lib/common/postproc.c:gv_postprocess
+  placeGraphLabel(g);
+  gvPostprocess(g);
+}
+
+// ---------------------------------------------------------------------------
+// osageCleanup helpers — exported for Lizard
+// ---------------------------------------------------------------------------
+
+/** Recursively clear cluster arrays from g and all subclusters. */
+export function cleanupGraphs(g: Graph): void {
+  const nClust = g.info.n_cluster ?? 0;
+  for (let i = 1; i <= nClust; i++) cleanupGraphs(g.info.clust![i - 1]);
+  g.info.clust = undefined;
+  g.info.n_cluster = undefined;
+}
+
+// ---------------------------------------------------------------------------
+// osageCleanup
+// ---------------------------------------------------------------------------
+
+/**
+ * Free all layout-specific memory attached to g.
+ *
+ * Clears alg (osage ownership tag) from all nodes and removes cluster
+ * arrays from GraphInfo.
+ *
+ * @see lib/osage/osageinit.c:osage_cleanup
+ */
+export function osageCleanup(g: Graph): void {
+  for (const n of g.nodes.values()) {
+    if (n.info.alg?.kind === 'osage') n.info.alg = undefined;
+  }
+  cleanupGraphs(g);
+}
+
+// ---------------------------------------------------------------------------
+// LayoutEngine export
+// ---------------------------------------------------------------------------
+
+/**
+ * Osage layout engine plugin object, suitable for registration with
+ * GvcContext.
+ *
+ * @see lib/plugin/neato_layout/gvlayout_neato_layout.c
+ */
+export const OSAGE_LAYOUT_ENGINE: LayoutEngine = {
+  type: 'osage',
+  layout: osageLayout,
+  cleanup: osageCleanup,
+};