@davidsouther/agathon 0.0.0-stage → 0.0.0

package/package.json

@@ -1,6 +1,21 @@
 {
   "name": "@davidsouther/agathon",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.0",
+  "type": "module",
+  "description": "Graph data structure, algorithms, and hierarchic layout.",
+  "license": "MIT",
+  "repository": "git+https://github.com/DavidSouther/agathon.git",
+  "sideEffects": false,
+  "files": [
+    "src",
+    "!src/**/*_test.ts",
+    "!src/**/testing.ts"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./*": "./src/*.ts"
+  },
+  "scripts": {
+    "test": "node --test \"src/**/*_test.ts\""
+  }
+}

package/src/assert.ts

@@ -0,0 +1,67 @@
+type AssertMessage = string | (() => string);
+
+/**
+ * Throw an error when a condition is not met.
+ */
+export function assert(
+  condition: boolean,
+  message: AssertMessage = "Assertion failed",
+  warn = false,
+): void | never {
+  if (!condition) {
+    message = message instanceof Function ? message() : message;
+    if (warn) {
+      console.warn(message);
+    } else {
+      throw new Error(message);
+    }
+  }
+}
+
+/**
+ * Given a `number|undefined|null`, assert that it is not undefined, not NaN, and not +-Infinity.
+ */
+export function assertFinite(
+  n: number | undefined | null,
+  message: AssertMessage = `Assertion failed: Value ${n} is not finite`,
+): number | never {
+  assert(n != null && !isNaN(n) && n !== Infinity && n !== -Infinity, message);
+  return n as number;
+}
+
+/**
+ * Given a value, return it if it is not null nor undefined. Otherwise throw an
+ * error.
+ *
+ * @template T
+ * @returns {NonNullable<T>}
+ */
+export function assertExists<T>(
+  t: T,
+  message: AssertMessage = "Assertion failed: value does not exist",
+): NonNullable<T> {
+  assert(t != null, message);
+  return t as NonNullable<T>;
+}
+
+/**
+ * @param {*} n
+ * @returns string
+ */
+export function assertString(
+  n: unknown,
+  message: AssertMessage = () => `Assertion failed: ${n} is not a string`,
+): string {
+  assert(typeof n === "string", message);
+  return n as string;
+}
+
+/**
+ * Compile time assertion that no value will used at this point in control flow.
+ */
+export function checkExhaustive(
+  value: never,
+  message: AssertMessage = `Unexpected value ${value}`,
+): never {
+  throw new Error(message instanceof Function ? message() : message);
+}

package/src/geometry/box.ts

@@ -0,0 +1,76 @@
+import type { Bounds, Point } from "../types.ts";
+
+/**
+ * Given an axis-aligned box and a line defined by two end points, determine if
+ * any point of the line is within the box. Takes the start and end points of
+ * the line segment, the upper-left point of the box, and the height and width
+ * of the box. This aligns with the data types in Layout Managers.
+ *
+ * @param pointA the starting point of a line segment.
+ * @param pointB the end point of a line segment.
+ *     In normal form, the line will be at pointA at t=0 and pointB at t=1.
+ * @param boxPoint the top-left corner of the axis-aligned box.
+ * @param boxBounds the height and width of the box.
+ */
+export function lineIntersectsBox(
+  { x: ax, y: ay }: Point,
+  { x: bx, y: by }: Point,
+  { x: px, y: py }: Point,
+  { height, width }: Bounds,
+): boolean {
+  // Align points to (0, 0)
+  ax -= px;
+  bx -= px;
+  ay -= py;
+  by -= py;
+
+  // Sort line to go from top to bottom
+  if (ay > by) {
+    const tx = bx;
+    const ty = by;
+    bx = ax;
+    by = ay;
+    ax = tx;
+    ay = ty;
+  }
+
+  // Line goes left to right or right to left
+  if (ax < bx) {
+    // Line goes from left to right, so a must be smaller than the bottom-right
+    // corner and b must be greater than the top-left corner.
+    return ax <= width && ay <= height && bx >= 0 && by >= 0;
+  } else {
+    // Line goes from right to left, so a must be smaller than the top-left
+    // corner and b must be greater than the bottom-right corner.
+    return ax >= 0 && ay <= height && bx <= width && by >= 0;
+  }
+}
+
+/**
+ * Given a circle and a box, return whether any part of the circle overlaps the
+ * box. This check is performed by offseting the center point by its radius in
+ * axis-aligned directions, and checking if that point is within the
+ * origin-centered axis-aligned box.
+ *
+ * @param center point of the circle.
+ * @param radius of the circle.
+ * @param boxPoint the top-left corner of the axis-aligned box.
+ * @param boxBounds the height and width of the box.
+ */
+export function circleIntersectsBox(
+  { x: cx, y: cy }: Point,
+  r: number,
+  { x: px, y: py }: Point,
+  { height, width }: Bounds,
+): boolean {
+  // Align points to (0, 0)
+  cx -= px;
+  cy -= py;
+
+  const xl = cx + r;
+  const xr = cx - r;
+  const yt = cy + r;
+  const yb = cy - r;
+
+  return xl >= 0 && xr <= width && yt >= 0 && yb <= height;
+}

package/src/geometry/circle.ts

@@ -0,0 +1,296 @@
+import { checkExhaustive } from "../assert.ts";
+import type { Bounds, Circle, Point } from "../types.ts";
+
+import {
+  BASE_RADIUS,
+  BaseGeometry,
+  clipicircle,
+  EPSILON,
+  type GeometryParams,
+  origin,
+} from "./geometry.ts";
+import type { Geometry, Line } from "./types.ts";
+
+/** Params to create a circle */
+export interface CircleParams extends GeometryParams {
+  radius: number;
+}
+
+/** Geometry for a circle (or a point with small radius) */
+export class CircleGeometry extends BaseGeometry {
+  private innderRadius!: number;
+
+  get isPoint(): boolean {
+    return this.radius < EPSILON;
+  }
+
+  override get radius(): number {
+    return this.innderRadius;
+  }
+
+  static point(point: Point = origin()): CircleGeometry {
+    return new CircleGeometry({ point, radius: 0 });
+  }
+
+  constructor({ point = origin(), radius = BASE_RADIUS }: Readonly<Partial<CircleParams>> = {}) {
+    super({ point });
+    this.resize(radius);
+  }
+
+  makeClone(): CircleGeometry {
+    return new CircleGeometry({ point: this, radius: this.radius });
+  }
+
+  resize(size: number | Bounds): void {
+    if (typeof size === "number") {
+      this.innderRadius = size;
+    } else {
+      this.innderRadius = Math.max(size.width, size.height) / 2;
+    }
+    this.bounds.height = this.bounds.width = this.radius * 2;
+  }
+
+  clipi(line: Line): void {
+    if (this.isPoint) {
+      // A point will never clip
+      return;
+    }
+
+    const dx = line[0].x - this.point.x;
+    const dy = line[0].y - this.point.y;
+    if (dx * dx + dy * dy <= this.radius * this.radius) {
+      // Start point is inside the circle. While clipicircle can handle this
+      // case, to be consistent with the documentation that lines leaving the
+      // polygon are not clipped, this returns early.
+      return;
+    }
+    clipicircle(line, this.point, this.radius);
+  }
+
+  /**
+   * Given a collection of geometries, fit this geometry to contain them, and
+   * update all positions to remain centered.
+   */
+  override tightestFit(neighborhood: Iterable<Geometry>): Bounds & Point {
+    const neighborCircles: Circle[] = [];
+
+    // TODO: Make getSmallestEnclosingCircle take geometries. Until
+    // then, convert all the geometries into circles.
+    for (const neighbor of neighborhood) {
+      const { x, y, radius } = neighbor;
+      neighborCircles.push({ x, y, r: radius });
+    }
+
+    const { x, y, r } = getSmallestEnclosingCircle(neighborCircles, 0);
+
+    return { x, y, height: r * 2, width: r * 2 };
+  }
+}
+
+/**
+ * Find the smallest radius such that the two circles adjacent with the largest
+ * combined radiuses are at least `separation` distance apart.
+ *
+ * For example, given a list with circles of radius [15, 20, 10, 10], the two
+ * largest adjacent circles are 15 and 20. To arrange these four points around a
+ * central point <0, 0> with the first two circles being a minimum of 35 pixels
+ * apart, the intersecting circle must have a radius of 40 pixels. Each point
+ * in the input list can then be projected that far from <0, 0>, and no enclosed
+ * circles will intersect.
+ */
+export function smallestIntersectingRadius(circles: number[], minimumSpacing: number): number {
+  const circlesLength = circles.length;
+
+  if (circlesLength < 2) return 0;
+
+  // First, find the pair of circles with the largest combined separation.
+  const largestCombinedRadius = Math.max(
+    ...circles.map((r, i) => r + circles[(i + 1) % circlesLength]),
+  );
+
+  const separation = largestCombinedRadius + minimumSpacing;
+  const theta = (2 * Math.PI) / circlesLength;
+  const gammaInv = Math.sqrt(2 * (1 - Math.cos(theta)));
+  const radius = separation / gammaInv;
+
+  return radius;
+}
+
+/**
+ * Returns the smallest circle that contains the specified circles.
+ * Expected time complexity is O(n).
+ */
+export function getSmallestEnclosingCircle(circles: Circle[], padding: number): Circle {
+  const enclosingCircle = enclosingCircleIntersectingCircles(circles, []) || {
+    x: 0,
+    y: 0,
+    r: 0,
+  };
+  enclosingCircle.r += padding;
+  return enclosingCircle;
+}
+
+/**
+ * Returns the smallest circle that contains the circles
+ * and intersects the boundaryCircles.
+ * Based on Emo Welzl's paper:
+ * https://www.inf.ethz.ch/personal/emo/PublFiles/SmallEnclDisk_LNCS555_91.ps
+ */
+function enclosingCircleIntersectingCircles(
+  circles: Circle[],
+  boundaryCircles: Circle[],
+): Circle | null {
+  circles = circles.slice(); // don't modify caller's data
+
+  let minEnclosingCircle: Circle | null = null;
+
+  if (boundaryCircles.length === 1) {
+    minEnclosingCircle = { ...boundaryCircles[0] };
+  } else if (boundaryCircles.length === 2) {
+    minEnclosingCircle = circleIntersectingTwoCircles(boundaryCircles[0], boundaryCircles[1]);
+  } else if (boundaryCircles.length >= 3) {
+    const l = boundaryCircles.length;
+    return circleIntersectingThreeCircles(
+      boundaryCircles[l - 3],
+      boundaryCircles[l - 2],
+      boundaryCircles[l - 1],
+    );
+  }
+
+  const visitedCircles: Circle[] = [];
+
+  while (circles.length > 0) {
+    const currentCircle = circles.pop()!;
+
+    if (minEnclosingCircle && circleContainsCircle(minEnclosingCircle, currentCircle)) {
+      visitedCircles.push(currentCircle);
+    } else {
+      // Current circle isn't inside current minimal enclosing circle.
+      // This means it will define the new minimal enclosing circle.
+      // We are going to compute minimal circle for all visited circles with
+      // the current circle on it's boundary.
+      boundaryCircles.push(currentCircle);
+      minEnclosingCircle = enclosingCircleIntersectingCircles(visitedCircles, boundaryCircles);
+      boundaryCircles.pop();
+
+      visitedCircles.push(currentCircle);
+    }
+  }
+
+  return minEnclosingCircle;
+}
+
+/** Returns true if the specified circle1 contains the specified circle2. */
+function circleContainsCircle(circle1: Circle, circle2: Circle): boolean {
+  const EPSILON = 1e-6;
+  const xc0 = circle1.x - circle2.x;
+  const yc0 = circle1.y - circle2.y;
+  return Math.sqrt(xc0 * xc0 + yc0 * yc0) < circle1.r - circle2.r + EPSILON;
+}
+
+/** Returns the smallest circle that intersects the two specified circles. */
+function circleIntersectingTwoCircles(circle1: Circle, circle2: Circle): Circle {
+  if (circleContainsCircle(circle1, circle2)) return circle1;
+  if (circleContainsCircle(circle2, circle1)) return circle2;
+  const { x: x1, y: y1, r: r1 } = circle1;
+  const { x: x2, y: y2, r: r2 } = circle2;
+  const dx = x2 - x1;
+  const dy = y2 - y1;
+  const dr = r2 - r1;
+  const l = Math.sqrt(dx * dx + dy * dy);
+  return {
+    x: (x1 + x2 + (dx / l) * dr) / 2,
+    y: (y1 + y2 + (dy / l) * dr) / 2,
+    r: (l + r1 + r2) / 2,
+  };
+}
+
+/** Returns the smallest circle that intersects the three specified circles. */
+function circleIntersectingThreeCircles(circle1: Circle, circle2: Circle, circle3: Circle): Circle {
+  const { x: x1, y: y1, r: r1 } = circle1;
+  const { x: x2, y: y2, r: r2 } = circle2;
+  const { x: x3, y: y3, r: r3 } = circle3;
+  const a2 = 2 * (x1 - x2);
+  const b2 = 2 * (y1 - y2);
+  const c2 = 2 * (r2 - r1);
+  const d2 = x1 * x1 + y1 * y1 - r1 * r1 - x2 * x2 - y2 * y2 + r2 * r2;
+  const a3 = 2 * (x1 - x3);
+  const b3 = 2 * (y1 - y3);
+  const c3 = 2 * (r3 - r1);
+  const d3 = x1 * x1 + y1 * y1 - r1 * r1 - x3 * x3 - y3 * y3 + r3 * r3;
+  const ab = a3 * b2 - a2 * b3;
+  const xa = (b2 * d3 - b3 * d2) / ab - x1;
+  const xb = (b3 * c2 - b2 * c3) / ab;
+  const ya = (a3 * d2 - a2 * d3) / ab - y1;
+  const yb = (a2 * c3 - a3 * c2) / ab;
+  const A = xb * xb + yb * yb - 1;
+  const B = 2 * (xa * xb + ya * yb + r1);
+  const C = xa * xa + ya * ya - r1 * r1;
+  const r = (-B - Math.sqrt(B * B - 4 * A * C)) / (2 * A);
+  return {
+    x: xa + xb * r + x1,
+    y: ya + yb * r + y1,
+    r,
+  };
+}
+
+/** returns a point on a circle divided into slices */
+export function getPositionOnCircle(
+  radius: number,
+  numSlices: number,
+  slice: number,
+  rotationOffset = 0,
+): Point {
+  if (numSlices === 1) {
+    // for one slice return the center point
+    return { x: 0, y: 0 };
+  }
+  const sliceSize = (2 * Math.PI) / numSlices;
+  const angle = sliceSize * slice + (rotationOffset * Math.PI) / 180;
+  const x = radius * Math.cos(angle);
+  const y = radius * Math.sin(angle);
+  return { x, y };
+}
+
+/** Quadrants of a circle. */
+export const Quadrant = {
+  TOP_RIGHT: 1,
+  TOP_LEFT: 2,
+  BOTTOM_LEFT: 3,
+  BOTTOM_RIGHT: 4,
+} as const;
+export type Quadrant = (typeof Quadrant)[keyof typeof Quadrant];
+
+/**
+ * Return an SVG transform attribute string to translate to a point at the
+ * quadrant of a circle.
+ */
+export function translateCircleQuadrant(
+  radius: number,
+  quadrant: Quadrant = Quadrant.TOP_RIGHT,
+): `translate(${number},${number})` {
+  let sx = 1,
+    sy = -1;
+  switch (quadrant) {
+    case Quadrant.TOP_RIGHT:
+      sx = 1;
+      sy = -1;
+      break;
+    case Quadrant.TOP_LEFT:
+      sx = -1;
+      sy = -1;
+      break;
+    case Quadrant.BOTTOM_LEFT:
+      sx = -1;
+      sy = 1;
+      break;
+    case Quadrant.BOTTOM_RIGHT:
+      sx = 1;
+      sy = -1;
+      break;
+    default:
+      checkExhaustive(quadrant);
+  }
+  const r = Math.abs(radius) / Math.SQRT2;
+  return `translate(${sx * r},${sy * r})`;
+}