@knowvah/dot-engine 0.1.0

package/src/vpsc/HeapUtils.ts

@@ -0,0 +1,88 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * Min-heap helpers over Constraint arrays.
+ *
+ * The C++ code uses std::make_heap / std::push_heap / std::pop_heap with a
+ * `gt` comparator that flips compareConstraints, producing a min-heap.
+ * We replicate that with a standard binary heap stored in an array.
+ *
+ * @see lib/vpsc/block.cpp: make_heap, insert, deleteMin, findMin, merge_heaps, gt
+ */
+
+import { Constraint, compareConstraints } from "./Constraint.js";
+
+/**
+ * Greater-than comparator: flips compareConstraints to turn a max-heap into
+ * a min-heap (matching the C++ `gt` lambda).
+ * @see lib/vpsc/block.cpp: static bool gt(...)
+ */
+export function heapGt(l: Constraint, r: Constraint): boolean {
+  return compareConstraints(r, l);
+}
+
+/**
+ * Bubble element at index i upward until the heap property is restored.
+ * @see lib/vpsc/block.cpp: std::push_heap internals
+ */
+export function heapSiftUp(h: Constraint[], i: number): void {
+  while (i > 0) {
+    const parent = (i - 1) >> 1;
+    if (!heapGt(h[parent]!, h[i]!)) break;
+    const tmp = h[parent]!;
+    h[parent] = h[i]!;
+    h[i] = tmp;
+    i = parent;
+  }
+}
+
+/**
+ * Push element at index i downward until the heap property is restored.
+ * @see lib/vpsc/block.cpp: std::pop_heap internals
+ */
+export function heapSiftDown(h: Constraint[], i: number): void {
+  const n = h.length;
+  for (;;) {
+    let smallest = i;
+    const l = 2 * i + 1;
+    const r = 2 * i + 2;
+    if (l < n && heapGt(h[smallest]!, h[l]!)) smallest = l;
+    if (r < n && heapGt(h[smallest]!, h[r]!)) smallest = r;
+    if (smallest === i) break;
+    const tmp = h[i]!;
+    h[i] = h[smallest]!;
+    h[smallest] = tmp;
+    i = smallest;
+  }
+}
+
+/** @see lib/vpsc/block.cpp: static void make_heap(...) */
+export function makeHeap(h: Constraint[]): void {
+  for (let i = (h.length >> 1) - 1; i >= 0; i--) {
+    heapSiftDown(h, i);
+  }
+}
+
+/** @see lib/vpsc/block.cpp: static Constraint *findMin(...) */
+export function heapFindMin(h: Constraint[]): Constraint {
+  return h[0]!;
+}
+
+/** @see lib/vpsc/block.cpp: static void deleteMin(...) */
+export function heapDeleteMin(h: Constraint[]): void {
+  h[0] = h[h.length - 1]!;
+  h.pop();
+  if (h.length > 0) heapSiftDown(h, 0);
+}
+
+/** @see lib/vpsc/block.cpp: static void insert(...) */
+export function heapInsert(h: Constraint[], c: Constraint): void {
+  h.push(c);
+  heapSiftUp(h, h.length - 1);
+}
+
+/** @see lib/vpsc/block.cpp: static void merge_heaps(...) */
+export function mergeHeaps(heap1: Constraint[], heap2: Constraint[]): void {
+  for (const c of heap2) heap1.push(c);
+  makeHeap(heap1);
+}

package/src/vpsc/Solver.ts

@@ -0,0 +1,274 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * VPSC, IncVPSC, and Rectangle.
+ *
+ * @see lib/vpsc/solve_VPSC.h
+ * @see lib/vpsc/solve_VPSC.cpp
+ * @see lib/vpsc/generate-constraints.h  (Rectangle)
+ * @see lib/vpsc/generate-constraints.cpp (Rectangle)
+ */
+
+import { Variable } from "./Variable.js";
+import { Constraint } from "./Constraint.js";
+import { Block } from "./Block.js";
+import { Blocks } from "./Blocks.js";
+
+// ---------------------------------------------------------------------------
+// Rectangle
+// Ported from lib/vpsc/generate-constraints.h + generate-constraints.cpp
+// ---------------------------------------------------------------------------
+
+/**
+ * An axis-aligned rectangle used as input to constraint generation.
+ *
+ * @see lib/vpsc/generate-constraints.h: class Rectangle
+ * @see lib/vpsc/generate-constraints.cpp: Rectangle::Rectangle(...)
+ */
+export class Rectangle {
+  private minX: number;
+  private maxX: number;
+  private minY: number;
+  private maxY: number;
+
+  constructor(x: number, X: number, y: number, Y: number) {
+    this.minX = x;
+    this.maxX = X;
+    this.minY = y;
+    this.maxY = Y;
+  }
+
+  getMaxX(): number { return this.maxX; }
+  getMaxY(): number { return this.maxY; }
+  getMinX(): number { return this.minX; }
+  getMinY(): number { return this.minY; }
+  getCentreX(): number { return this.minX + this.width() / 2.0; }
+  getCentreY(): number { return this.minY + this.height() / 2.0; }
+  width(): number { return this.maxX - this.minX; }
+  height(): number { return this.maxY - this.minY; }
+
+  /** @see lib/vpsc/generate-constraints.h: double overlapX(const Rectangle &r) const */
+  overlapX(r: Rectangle): number {
+    if (this.getCentreX() <= r.getCentreX() && r.getMinX() < this.maxX)
+      return this.maxX - r.getMinX();
+    if (r.getCentreX() <= this.getCentreX() && this.minX < r.getMaxX())
+      return r.getMaxX() - this.minX;
+    return 0;
+  }
+
+  /** @see lib/vpsc/generate-constraints.h: double overlapY(const Rectangle &r) const */
+  overlapY(r: Rectangle): number {
+    if (this.getCentreY() <= r.getCentreY() && r.getMinY() < this.maxY)
+      return this.maxY - r.getMinY();
+    if (r.getCentreY() <= this.getCentreY() && this.minY < r.getMaxY())
+      return r.getMaxY() - this.minY;
+    return 0;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// VPSC
+// @see lib/vpsc/solve_VPSC.h
+// @see lib/vpsc/solve_VPSC.cpp
+// ---------------------------------------------------------------------------
+
+/**
+ * Variable Placement with Separation Constraints problem instance.
+ *
+ * @see lib/vpsc/solve_VPSC.h: struct VPSC
+ * @see lib/vpsc/solve_VPSC.cpp
+ */
+export class VPSC {
+  protected bs: Blocks;
+  protected cs: Constraint[];
+
+  /** @see lib/vpsc/solve_VPSC.cpp: VPSC::VPSC(...) */
+  constructor(vs: Variable[], cs: Constraint[]) {
+    this.bs = new Blocks(vs);
+    this.cs = cs;
+  }
+
+  /**
+   * Phase 1 (feasibility): topological sort, mergeLeft per variable, cleanup,
+   * then verify no constraint has slack < -1e-7.
+   * @see lib/vpsc/solve_VPSC.cpp: VPSC::satisfy()
+   */
+  satisfy(): void {
+    const vs = this.bs.totalOrder();
+    for (const v of vs) {
+      if (!v.block!.deleted) this.bs.mergeLeft(v.block!);
+    }
+    this.bs.cleanup();
+    this.verifyConstraints();
+  }
+
+  /** @see lib/vpsc/solve_VPSC.cpp: VPSC::refine() */
+  private refine(): void {
+    for (let solved = false; !solved;) {
+      solved = true;
+      for (const b of this.bs) {
+        b.setUpInConstraints();
+        b.setUpOutConstraints();
+      }
+      for (const b of this.bs) {
+        const c = b.findMinLM();
+        if (c !== null && c.lm < 0) {
+          this.bs.split(b, c);
+          this.bs.cleanup();
+          solved = false;
+          break;
+        }
+      }
+    }
+    this.verifyConstraints();
+  }
+
+  /**
+   * Throw if any constraint has slack < -1e-7.
+   * Shared between satisfy() and refine().
+   */
+  private verifyConstraints(): void {
+    for (const c of this.cs) {
+      if (c.slack() < -0.0000001) throw new Error("Unsatisfied constraint");
+    }
+  }
+
+  /**
+   * Optimal solution: satisfy() then refine().
+   * @see lib/vpsc/solve_VPSC.cpp: VPSC::solve()
+   */
+  solve(): void {
+    this.satisfy();
+    this.refine();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// IncVPSC
+// @see lib/vpsc/solve_VPSC.h: struct IncVPSC
+// @see lib/vpsc/solve_VPSC.cpp
+// ---------------------------------------------------------------------------
+
+/**
+ * Incremental VPSC solver — allows refinement after blocks are moved.
+ *
+ * @see lib/vpsc/solve_VPSC.h: struct IncVPSC
+ * @see lib/vpsc/solve_VPSC.cpp
+ */
+export class IncVPSC extends VPSC {
+  splitCnt: number;
+  private inactive: Constraint[];
+
+  /** @see lib/vpsc/solve_VPSC.cpp: IncVPSC::IncVPSC(...) */
+  constructor(vs: Variable[], cs: Constraint[]) {
+    super(vs, cs);
+    this.splitCnt = 0;
+    this.inactive = cs.slice();
+    for (const c of this.inactive) c.active = false;
+  }
+
+  /**
+   * Incremental satisfy: split blocks, then merge across most-violated
+   * inactive constraint until none remain violated.
+   * @see lib/vpsc/solve_VPSC.cpp: IncVPSC::satisfy()
+   */
+  override satisfy(): void {
+    this.splitBlocks();
+    let splitCtr = 0;
+    let v: Constraint | null = null;
+    while (this.mostViolated((c) => { v = c; }) < -0.0000001) {
+      const vc = v!;
+      const lb = vc.left.block!;
+      const rb = vc.right.block!;
+      if (lb !== rb) {
+        lb.mergeTwoArg(rb, vc);
+      } else {
+        if (++splitCtr > 10000) throw new Error("Cycle Error!");
+        const [splitC, newLb, newRb] = lb.splitBetween(vc.left, vc.right);
+        this.inactive.push(splitC);
+        newLb.mergeTwoArg(newRb, vc);
+        this.bs.insert(newLb);
+      }
+    }
+    this.bs.cleanup();
+    for (const c of this.cs) {
+      if (c.slack() < -0.0000001) throw new Error("Unsatisfied constraint");
+    }
+  }
+
+  /**
+   * Move each block to its optimal unconstrained position.
+   * @see lib/vpsc/solve_VPSC.cpp: IncVPSC::moveBlocks()
+   */
+  moveBlocks(): void {
+    for (const b of this.bs) {
+      b.wposn = b.desiredWeightedPosition();
+      b.posn = b.wposn / b.weight;
+    }
+  }
+
+  /**
+   * Move blocks then split each block where min-LM constraint is negative.
+   * @see lib/vpsc/solve_VPSC.cpp: IncVPSC::splitBlocks()
+   */
+  splitBlocks(): void {
+    this.moveBlocks();
+    this.splitCnt = 0;
+    for (const b of this.bs) {
+      const v = b.findMinLM();
+      if (v !== null && v.lm < -0.0000001) {
+        this.splitCnt++;
+        const b2 = v.left.block!;
+        const pos = b2.posn;
+        const [l, r] = b2.splitInto(v);
+        l.posn = pos; l.wposn = pos * l.weight;
+        r.posn = pos; r.wposn = pos * r.weight;
+        this.bs.insert(l);
+        this.bs.insert(r);
+        b2.deleted = true;
+        this.inactive.push(v);
+      }
+    }
+    this.bs.cleanup();
+  }
+
+  /**
+   * Convergence loop: |Δcost| ≤ 0.0001.
+   * @see lib/vpsc/solve_VPSC.cpp: IncVPSC::solve()
+   */
+  override solve(): void {
+    let lastCost = Infinity;
+    let cost = this.bs.cost();
+    do {
+      lastCost = cost;
+      this.satisfy();
+      this.splitBlocks();
+      cost = this.bs.cost();
+    } while (Math.abs(lastCost - cost) > 0.0001);
+  }
+
+  /**
+   * Finds the most violated inactive constraint. Removes it via swap-and-pop.
+   * @see lib/vpsc/solve_VPSC.cpp: IncVPSC::mostViolated
+   */
+  private mostViolated(setV: (c: Constraint) => void): number {
+    let minSlack = Number.MAX_VALUE;
+    let deletePoint = -1;
+    const l = this.inactive;
+    for (let i = 0; i < l.length; i++) {
+      const slack = l[i]!.slack();
+      if (slack < minSlack) {
+        minSlack = slack;
+        setV(l[i]!);
+        deletePoint = i;
+      }
+    }
+    if (deletePoint !== -1 && minSlack < -0.0000001) {
+      l[deletePoint] = l[l.length - 1]!;
+      l.pop();
+    }
+    return minSlack;
+  }
+}
+
+export { Block, Blocks };

package/src/vpsc/SweepLine.ts

@@ -0,0 +1,214 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * Sweep-line constraint generation for VPSC overlap removal.
+ *
+ * @see lib/vpsc/generate-constraints.h
+ * @see lib/vpsc/generate-constraints.cpp
+ */
+
+import { Variable } from "./Variable.js";
+import { Constraint } from "./Constraint.js";
+import { Rectangle } from "./Solver.js";
+import { EvType, SweepNode, SweepEvent } from "./sweepTypes.js";
+
+export function makeNode(v: Variable, r: Rectangle, pos: number): SweepNode {
+  return {
+    v, r, pos,
+    firstAbove: null, firstBelow: null,
+    leftNeighbours: new Set(), rightNeighbours: new Set(),
+  };
+}
+
+export function compareEventsSameRect(ea: SweepEvent, eb: SweepEvent): number {
+  if (ea.type === EvType.Open && eb.type !== EvType.Open) return -1;
+  return 1;
+}
+
+export function compareEvents(ea: SweepEvent, eb: SweepEvent): number {
+  if (ea.node.r === eb.node.r) return compareEventsSameRect(ea, eb);
+  if (ea.pos < eb.pos) return -1;
+  if (ea.pos > eb.pos) return 1;
+  return 0;
+}
+
+export function nodePosLt(a: SweepNode, b: SweepNode): boolean {
+  if (a.pos < b.pos) return true;
+  if (b.pos < a.pos) return false;
+  return a < b;
+}
+
+export function scanlineInsert(sl: SweepNode[], node: SweepNode): void {
+  let lo = 0;
+  let hi = sl.length;
+  while (lo < hi) {
+    const mid = (lo + hi) >> 1;
+    if (nodePosLt(sl[mid]!, node)) lo = mid + 1;
+    else hi = mid;
+  }
+  sl.splice(lo, 0, node);
+}
+
+export function scanlineRemove(sl: SweepNode[], node: SweepNode): void {
+  const i = sl.indexOf(node);
+  if (i !== -1) sl.splice(i, 1);
+}
+
+export function getLeftNeighbours(sl: SweepNode[], v: SweepNode): Set<SweepNode> {
+  const result = new Set<SweepNode>();
+  const idx = sl.indexOf(v);
+  for (let i = idx - 1; i >= 0; i--) {
+    const u = sl[i]!;
+    if (u.r.overlapX(v.r) <= 0) { result.add(u); return result; }
+    if (u.r.overlapX(v.r) <= u.r.overlapY(v.r)) result.add(u);
+  }
+  return result;
+}
+
+export function getRightNeighbours(sl: SweepNode[], v: SweepNode): Set<SweepNode> {
+  const result = new Set<SweepNode>();
+  const idx = sl.indexOf(v);
+  for (let i = idx + 1; i < sl.length; i++) {
+    const u = sl[i]!;
+    if (u.r.overlapX(v.r) <= 0) { result.add(u); return result; }
+    if (u.r.overlapX(v.r) <= u.r.overlapY(v.r)) result.add(u);
+  }
+  return result;
+}
+
+export function xOpenNeighbour(sl: SweepNode[], v: SweepNode): void {
+  const left = getLeftNeighbours(sl, v);
+  const right = getRightNeighbours(sl, v);
+  v.leftNeighbours = left;
+  v.rightNeighbours = right;
+  for (const n of left) n.rightNeighbours.add(v);
+  for (const n of right) n.leftNeighbours.add(v);
+}
+
+export function openLinkChain(sl: SweepNode[], v: SweepNode): void {
+  const idx = sl.indexOf(v);
+  if (idx > 0) { const u = sl[idx - 1]!; v.firstAbove = u; u.firstBelow = v; }
+  if (idx < sl.length - 1) { const u = sl[idx + 1]!; v.firstBelow = u; u.firstAbove = v; }
+}
+
+export function xCloseLeft(v: SweepNode, cs: Constraint[]): void {
+  for (const u of v.leftNeighbours) {
+    cs.push(new Constraint(u.v, v.v, (v.r.width() + u.r.width()) / 2.0));
+    u.rightNeighbours.delete(v);
+  }
+}
+
+export function xCloseRight(v: SweepNode, cs: Constraint[]): void {
+  for (const u of v.rightNeighbours) {
+    cs.push(new Constraint(v.v, u.v, (v.r.width() + u.r.width()) / 2.0));
+    u.leftNeighbours.delete(v);
+  }
+}
+
+export function xCloseNeighbour(v: SweepNode, cs: Constraint[]): void {
+  xCloseLeft(v, cs);
+  xCloseRight(v, cs);
+}
+
+export function xCloseSimple(v: SweepNode, cs: Constraint[]): void {
+  const l = v.firstAbove;
+  const r = v.firstBelow;
+  if (l !== null) {
+    cs.push(new Constraint(l.v, v.v, (v.r.width() + l.r.width()) / 2.0));
+    l.firstBelow = v.firstBelow;
+  }
+  if (r !== null) {
+    cs.push(new Constraint(v.v, r.v, (v.r.width() + r.r.width()) / 2.0));
+    r.firstAbove = v.firstAbove;
+  }
+}
+
+export function yClose(v: SweepNode, cs: Constraint[]): void {
+  const l = v.firstAbove;
+  const r = v.firstBelow;
+  if (l !== null) {
+    cs.push(new Constraint(l.v, v.v, (v.r.height() + l.r.height()) / 2.0));
+    l.firstBelow = v.firstBelow;
+  }
+  if (r !== null) {
+    cs.push(new Constraint(v.v, r.v, (v.r.height() + r.r.height()) / 2.0));
+    r.firstAbove = v.firstAbove;
+  }
+}
+
+export function buildXEvents(rects: Rectangle[], vs: Variable[]): SweepEvent[] {
+  const events: SweepEvent[] = [];
+  for (let i = 0; i < rects.length; i++) {
+    const r = rects[i]!;
+    vs[i]!.desiredPosition = r.getCentreX();
+    const node = makeNode(vs[i]!, r, r.getCentreX());
+    events.push({ type: EvType.Open, node, pos: r.getMinY() });
+    events.push({ type: EvType.Close, node, pos: r.getMaxY() });
+  }
+  return events;
+}
+
+export function buildYEvents(rects: Rectangle[], vs: Variable[]): SweepEvent[] {
+  const events: SweepEvent[] = [];
+  for (let i = 0; i < rects.length; i++) {
+    const r = rects[i]!;
+    vs[i]!.desiredPosition = r.getCentreY();
+    const node = makeNode(vs[i]!, r, r.getCentreY());
+    events.push({ type: EvType.Open, node, pos: r.getMinX() });
+    events.push({ type: EvType.Close, node, pos: r.getMaxX() });
+  }
+  return events;
+}
+
+/**
+ * Prepares constraints to apply VPSC horizontally (X axis).
+ * @see lib/vpsc/generate-constraints.cpp: generateXConstraints
+ */
+export function generateXConstraints(
+  rects: Rectangle[],
+  vs: Variable[],
+  useNeighbourLists: boolean
+): Constraint[] {
+  const events = buildXEvents(rects, vs);
+  events.sort(compareEvents);
+  const sl: SweepNode[] = [];
+  const cs: Constraint[] = [];
+  for (const e of events) {
+    const v = e.node;
+    if (e.type === EvType.Open) {
+      scanlineInsert(sl, v);
+      if (useNeighbourLists) xOpenNeighbour(sl, v);
+      else openLinkChain(sl, v);
+    } else {
+      if (useNeighbourLists) xCloseNeighbour(v, cs);
+      else xCloseSimple(v, cs);
+      scanlineRemove(sl, v);
+    }
+  }
+  return cs;
+}
+
+/**
+ * Prepares constraints to apply VPSC vertically (Y axis).
+ * @see lib/vpsc/generate-constraints.cpp: generateYConstraints
+ */
+export function generateYConstraints(
+  rects: Rectangle[],
+  vs: Variable[]
+): Constraint[] {
+  const events = buildYEvents(rects, vs);
+  events.sort(compareEvents);
+  const sl: SweepNode[] = [];
+  const cs: Constraint[] = [];
+  for (const e of events) {
+    const v = e.node;
+    if (e.type === EvType.Open) {
+      scanlineInsert(sl, v);
+      openLinkChain(sl, v);
+    } else {
+      yClose(v, cs);
+      scanlineRemove(sl, v);
+    }
+  }
+  return cs;
+}

package/src/vpsc/Variable.ts

@@ -0,0 +1,54 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * A variable in the VPSC (Variable Placement with Separation Constraints) problem.
+ * Each variable has a desired position and a weight controlling how strongly it is
+ * attracted to that position.
+ *
+ * @see lib/vpsc/variable.h
+ * @see lib/vpsc/variable.cpp
+ */
+
+import type { Block } from "./Solver.js";
+import type { Constraint } from "./Constraint.js";
+
+export class Variable {
+  /** Useful identifier, mirrored from C source `const int id`. */
+  id: number;
+  /** Desired (ideal) position for this variable. @see variable.h */
+  desiredPosition: number;
+  /** Weight controlling attraction to desiredPosition. @see variable.h */
+  weight: number;
+  /** Offset within the block. Mutated during block merges. @see variable.h */
+  offset: number;
+  /** Block this variable belongs to. Null until assigned by Blocks constructor. */
+  block: Block | null;
+  /** Visited flag used by topological sort in Blocks.totalOrder(). */
+  visited: boolean;
+  /** Constraints where this variable is the right endpoint. @see variable.h `in` */
+  in: Constraint[];
+  /** Constraints where this variable is the left endpoint. @see variable.h `out` */
+  out: Constraint[];
+
+  /**
+   * @see lib/vpsc/variable.h: Variable(const int id_, const double desiredPos_, const double weight_)
+   */
+  constructor(id: number, desiredPos: number, weight: number) {
+    this.id = id;
+    this.desiredPosition = desiredPos;
+    this.weight = weight;
+    this.offset = 0;
+    this.block = null;
+    this.visited = false;
+    this.in = [];
+    this.out = [];
+  }
+
+  /**
+   * Compute the current position: block reference position plus this variable's offset.
+   * @see lib/vpsc/variable.h: double position() const { return block->posn+offset; }
+   */
+  position(): number {
+    return this.block!.posn + this.offset;
+  }
+}