@davidsouther/agathon 0.0.0-stage → 0.0.0

package/src/geometry/geometry.ts

@@ -0,0 +1,318 @@
+import type { Bounds, Point } from "../types.ts";
+
+import { lineIntersectsBox } from "./box.ts";
+import type { Geometry, Line } from "./types.ts";
+
+/** Math.EPSILON is much to small for graphical geometry. */
+export const EPSILON = 1e-2;
+
+/** The base radius for Agathon geometry shapes. */
+export const BASE_RADIUS = 20;
+
+/** Origin point for default positions. */
+export function origin(): Point {
+  return { x: 0, y: 0 };
+}
+
+/** Parameters for a base geometry. */
+export interface GeometryParams {
+  point: Point;
+}
+
+/**
+ * BaseGeometry provides an implementation of clip, which provides convenience
+ * at the possible expense of small object performance.
+ */
+export abstract class BaseGeometry implements Geometry {
+  protected position: Point = { x: 0, y: 0 };
+  protected dragPt: Point = { x: 0, y: 0 };
+  protected movePt: Point = { x: 0, y: 0 };
+  protected bounds: Bounds = { height: 0, width: 0 };
+
+  get point(): Readonly<Point> {
+    return this.position;
+  }
+  get x(): number {
+    return this.position.x;
+  }
+  get y(): number {
+    return this.position.y;
+  }
+  get radius(): number {
+    return Math.sqrt(this.height * this.height + this.width * this.width) / 2;
+  }
+  get height(): number {
+    return this.bounds.height;
+  }
+  get width(): number {
+    return this.bounds.width;
+  }
+  get left(): number {
+    return this.x - this.bounds.width / 2;
+  }
+  get right(): number {
+    return this.x + this.bounds.width / 2;
+  }
+  get bottom(): number {
+    return this.y - this.bounds.height / 2;
+  }
+  get top(): number {
+    return this.y + this.bounds.height / 2;
+  }
+
+  constructor({ point = origin() }: Readonly<Partial<GeometryParams>>) {
+    // Defensive copy of the point
+    this.movePt.x = point.x;
+    this.movePt.y = point.y;
+    this.place();
+  }
+
+  private place(): void {
+    this.position.x = this.movePt.x + this.dragPt.x;
+    this.position.y = this.movePt.y + this.dragPt.y;
+  }
+
+  drag({ x: dx, y: dy }: Point): void {
+    this.dragPt.x += dx;
+    this.dragPt.y += dy;
+    this.place();
+  }
+
+  dragTo({ x, y }: Point): void {
+    this.dragPt.x = x;
+    this.dragPt.y = y;
+    this.place();
+  }
+
+  move({ x: dx, y: dy }: Point): void {
+    this.movePt.x += dx;
+    this.movePt.y += dy;
+    this.place();
+  }
+
+  moveTo({ x, y }: Point): void {
+    this.movePt.x = x;
+    this.movePt.y = y;
+    this.place();
+  }
+
+  abstract resize(size: number | Bounds): void;
+
+  abstract clipi(line: Line): void;
+
+  abstract makeClone(): Geometry;
+
+  clone(): Geometry {
+    const geom = this.makeClone();
+    geom.moveTo(this.movePt);
+    geom.dragTo(this.dragPt);
+    return geom;
+  }
+
+  clip(line: Readonly<Line>): Point {
+    const [{ x: ax, y: ay }, { x: bx, y: by }] = line;
+    const b: Point = { x: bx, y: by };
+    const newLine: Line = [{ x: ax, y: ay }, b];
+    this.clipi(newLine);
+    return b;
+  }
+
+  intersects(geometry: Geometry): boolean {
+    // Check if the geometries' AABBs overlap on either X or Y axes.
+    // clang-format off
+    return !(
+      geometry.bottom > this.top ||
+      geometry.top < this.bottom ||
+      geometry.left > this.right ||
+      geometry.right < this.left
+    );
+    // clang-format on
+  }
+
+  lineIntersects(a: Point, b: Point): boolean {
+    return lineIntersectsBox(a, b, { x: this.left, y: this.bottom }, this);
+  }
+
+  contains(geometry: Geometry): boolean {
+    // treating both geometries as AABBs, is geometry contained inside this?
+    // clang-format off
+    return (
+      geometry.left >= this.left &&
+      geometry.right <= this.right &&
+      geometry.top <= this.top &&
+      geometry.bottom >= this.bottom
+    );
+    // clang-format on
+  }
+
+  /**
+   * For this geometry type, calculate the tightest bounds that would fit these
+   * children. Naively, calculates the rectangular bounds. Circle, for instance,
+   * could calculate a tighter bounds.
+   */
+  tightestFit(children: Iterable<Geometry>): Bounds & Point {
+    let minX = Number.MAX_SAFE_INTEGER;
+    let minY = Number.MAX_SAFE_INTEGER;
+    let maxX = Number.MIN_SAFE_INTEGER;
+    let maxY = Number.MIN_SAFE_INTEGER;
+
+    for (const { x, y, width, height } of children) {
+      const halfWidth = width / 2;
+      const halfHeight = height / 2;
+      minX = Math.min(minX, x - halfWidth);
+      minY = Math.min(minY, y - halfHeight);
+      maxX = Math.max(maxX, x + halfWidth);
+      maxY = Math.max(maxY, y + halfHeight);
+    }
+
+    if (minX > maxX) [minX, maxX] = [maxX, minX];
+    if (minY > maxY) [minY, maxY] = [maxY, minY];
+
+    return {
+      // Divide and add, for numerical stability.
+      x: maxX / 2 + minX / 2,
+      y: maxY / 2 + minY / 2,
+      width: maxX - minX,
+      height: maxY - minY,
+    };
+  }
+
+  fitTo(children: Iterable<Geometry>, padding = 0): void {
+    const fit = this.tightestFit(children);
+    this.resize({
+      height: fit.height + padding * 2,
+      width: fit.width + padding * 2,
+    });
+
+    // fit is new center point of geometry bounds. Normalize children by moving
+    // them by -fit, and adjust this geometry by fit to compensate the center.
+    this.move(fit);
+    const delta: Point = { x: -fit.x, y: -fit.y };
+    for (const child of children) child.move(delta);
+  }
+}
+
+/**
+ * Adjust second point in `source` to lie on `target`. If the lines are
+ * nonintersecting, source is unchanged.
+ */
+export function clipi(source: Line, target: Line): void {
+  const [{ x: ax1, y: ay1 }, { x: ax2, y: ay2 }] = source;
+  const [{ x: bx1, y: by1 }, { x: bx2, y: by2 }] = target;
+
+  const axd = ax2 - ax1;
+  const ayd = ay2 - ay1;
+
+  const bxd = bx2 - bx1;
+  const byd = by2 - by1;
+
+  const sxd = bx1 - ax1;
+  const syd = by1 - ay1;
+
+  // Adapted from en.wikipedia.org/wiki/Intersection_(Euclidean_geometry)#Two_line_segments
+
+  // In parametric form:
+  // ax(s) = ax1 + s * axd
+  // ay(s) = ay1 + s * ayd
+  // bx(t) = bx1 + t * bxd
+  // by(t) = by1 + t * byd
+
+  // Results in the linear equations
+  // s * axd - t * bxd = sxd
+  // s * ayd - t * byd = syd
+
+  // Solving s, t by Cramer's rule
+  const s = (sxd * -byd - syd * -bxd) / (axd * -byd - ayd * -bxd);
+  const t = (axd * syd - ayd * sxd) / (axd * -byd - ayd * -bxd);
+
+  if (0 <= s && t <= 1) {
+    // There is an intersection! Update source parametrically
+    source[1].x = ax1 + axd * s;
+    source[1].y = ay1 + ayd * s;
+  }
+  // no intersection, all that to do nothing
+}
+
+/**
+ * Given a line and a circle, update the second point on the line to lie on the
+ * circle closest to the first point on the line.
+ */
+export function clipicircle(line: Line, point: Point, radius: number): void {
+  let [{ x: x1, y: y1 }, { x: x2, y: y2 }] = line;
+
+  // Normalize so that circle is at (0, 0)
+  x1 -= point.x;
+  x2 -= point.x;
+  y1 -= point.y;
+  y2 -= point.y;
+
+  // Line is:
+  // x(t) = x1 + t dx
+  // y(t) = y1 + t dy - r^
+  //
+  // Circle is: (a^ shorthand for a squared)
+  //
+  // 0 = x^ + y^ - r^
+  //
+  // Substituting gives
+  //
+  //   = (x1 + t dx)^ + (y1 + t dy)^ - r^
+  //
+  // Simplifying gives
+  //   = x1^ + 2 dx x1 t + dx^ t^ + y1^ + 2 dy y1 t + dy^ t^ - r^
+  //   = dx^ dy^ t^ + 2 (dx x1 + dy y1) t + x1^ + y1^ - r^
+  //
+  // Quadratic equation setup for t is therefore
+  //
+  // a = dx^ + dy^
+  // b = 2 (dx x1 + dy y1)
+  // c = x1^ + y1^ - r^2
+
+  const dx = x2 - x1;
+  const dy = y2 - y1;
+
+  const a = dx * dx + dy * dy;
+  const b = 2 * (dx * x1 + dy * y1);
+  const c = x1 * x1 + y1 * y1 - radius * radius;
+
+  const det = b * b - 4 * a * c;
+
+  let t = 0;
+  if (det < 0) {
+    return;
+  }
+  const aa = 2 * a;
+  if (det < EPSILON) {
+    t = -b / aa;
+  } else {
+    // Use stable quadratic from
+    // http://people.csail.mit.edu/bkph/articles/Quadratics.pdf
+    const basis = -b - Math.sqrt(det);
+    let t1: number;
+    let t2: number;
+    if (b >= 0) {
+      t1 = basis / (2 * a);
+      t2 = (2 * c) / basis;
+    } else {
+      t1 = (2 * c) / basis;
+      t2 = basis / (2 * a);
+    }
+
+    // Use best t (smallest t between 0 and 1). All return cases are for
+    // intersections outside the line segment.
+    if (t1 < 0) {
+      if (t2 < 0) return;
+      if (t2 > 1) return;
+      t = t2;
+    } else if (t1 > 1) {
+      if (t2 < 0) return;
+      if (t2 > 1) return;
+      t = t2;
+    } else {
+      t = Math.min(t1, t2);
+    }
+  }
+
+  line[1].x = line[0].x + t * dx;
+  line[1].y = line[0].y + t * dy;
+}

package/src/geometry/path.ts

@@ -0,0 +1,315 @@
+// d3 has path libraries, however, they don't work on ReadonlyArrays or
+// Readonly<PointTuple>, and I'm trying to keep the amount of copying from
+// various Point forms down. Additionally, they use arbitrary precision
+// floating point arithmetic, when really most of the time there's no need for
+// more than 1 or 2 decimals of precision. Further significant digits only
+// serve to make the path more difficult for humans to read.
+
+import type { Box, Point } from "../types.ts";
+
+/** A box that everything fits into. */
+export const FULL_BOX = {
+  x: -Number.MAX_VALUE,
+  y: -Number.MAX_VALUE,
+  width: Infinity,
+  height: Infinity,
+};
+
+// An enum that indicates whether each side of a pair of points are inside or
+// outside a box. the first half indicates the location of the first point
+// (inside or outside), and the second word indicates the location of the second
+// point. See `testInBox` for usage.
+const IntersectionPoint = {
+  OUTSIDE_OUTSIDE: 0,
+  OUTSIDE_INSIDE: 1,
+  INSIDE_OUTSIDE: 2,
+  INSIDE_INSIDE: 3,
+  UNSET: Number.MAX_VALUE,
+} as const;
+type IntersectionPoint = (typeof IntersectionPoint)[keyof typeof IntersectionPoint];
+
+/**
+ * Create an SVG `d` attribute encoding a straight-line path between absolutely
+ * positioned points, truncating their decimal values to a certain precision. If
+ * points lie outside the given box, use non-drawing `Move` commands.
+ */
+export function straightLinePath(
+  points: ReadonlyArray<Readonly<Point>>,
+  box: Box = FULL_BOX,
+  precision = 2,
+): string {
+  // This method uses a combination of the interpreter pattern and a register-
+  // based execution machine. The input tape is the list of `Point` values. The
+  // output is held internally in the `commands` array, which holds a list of
+  // SVG d path commands:
+  // https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/d
+  //
+  // The commands available for the interpreter are `move`, `line`, `inBox`,
+  // `testInOutIntersection`, and `testOutInIntersection`. "Registers" are
+  // documented inline.
+
+  // The output tap, a list of `d` drawing commands.
+  const commands: string[] = [];
+
+  // lastX and lastY track where the command being calculated will end. They are
+  // updated at various points in the algorithm, before calling `command` to
+  // generate a line command using lastX, lastY as the <x, y> values for that
+  // command.
+  let lastX = points[0].x;
+  let lastY = points[0].y;
+
+  // Start by moving to the first point in the list.
+  move();
+
+  // And end there if we only have a single point.
+  if (points.length === 1) return commands[0];
+
+  // left, right, top, bottom are the box constants, used to test for ray/box
+  // intersections.
+  const boxLeft = box.x;
+  const boxRight = boxLeft + box.width;
+  const boxBottom = box.y;
+  const boxTop = boxBottom + box.height;
+
+  if (boxRight <= boxLeft || boxTop <= boxBottom) {
+    // If you end up here debugging, then this probably should have been an
+    // error case. The following string will help you determine what's going on.
+    // `path::straightLinePath: degenerate box: ${boxString()}`
+    return "";
+  }
+
+  //
+  // Error Reporting Utilities
+  //
+
+  function boxString(): string {
+    return `t ${boxTop} r ${boxRight} b ${boxBottom} l ${boxLeft}`;
+  }
+
+  function doThrow(message: string): never {
+    const last = `${lastX},${lastY}`;
+    const current = `${currentX},${currentY}`;
+    const fullMessage = `${message} <from ${last} to ${current} with box ${boxString()}>`;
+    throw new Error(`path::straighLinePath: ${fullMessage}`);
+  }
+
+  //
+  // Drawing commands
+  //
+
+  // set lastX and lastY to the current position & increment i for the next loop
+  function advance() {
+    // set last point to current point
+    lastX = currentX;
+    lastY = currentY;
+    // increment i
+    i++;
+  }
+
+  // Write an M or L command using lastX lastY at a given precision.
+  function command(c: "M" | "L") {
+    commands.push(`${c}${lastX.toFixed(precision)},${lastY.toFixed(precision)}`);
+  }
+
+  function move() {
+    // If the last command was a (M)ove, replace it with this (M)ove.
+    if (commands.length > 0 && commands[commands.length - 1][0] === "M") {
+      commands.pop();
+    }
+    command("M");
+  }
+
+  function line() {
+    command("L");
+  }
+
+  //
+  // Interesction & Box Tests
+  //
+
+  function inBox(x: number, y: number): boolean {
+    return x >= boxLeft && x <= boxRight && y <= boxTop && y >= boxBottom;
+  }
+
+  // Set up the "registers" for running the drawing operations
+  // testInteresection uses a register inspired approach. The setup for each
+  // test is the same, but to cut down on parameter passing, these local
+  // registers keep the test values.
+  let directionX = 0;
+  let directionY = 0;
+  let magnitude = 0;
+  let normalX = 0;
+  let normalY = 0;
+  let invX = 0;
+  let invY = 0;
+  let tTop = 0;
+  let tLeft = 0;
+  let tRight = 0;
+  let tBottom = 0;
+  let tBest = 0;
+
+  function testInBox() {
+    if (isNaN(lastX) || isNaN(lastY) || isNaN(currentX) || isNaN(currentY)) {
+      inBoxTest = IntersectionPoint.UNSET;
+      return;
+    }
+    // The IntersectionPoint is a bit enum, with bit 0 determining whether
+    // the current point is in the box, and bit 1 controlling whether the
+    // last point is in the box. Adding them together gives the four states.
+    const lastIn = inBox(lastX, lastY) ? 2 : 0;
+    const currentIn = inBox(currentX, currentY) ? 1 : 0;
+    inBoxTest = (lastIn + currentIn) as IntersectionPoint;
+  }
+
+  // In normalized coordinates, find the t parameter for intersection of the
+  // four edges of the box.
+  function setupIntersectionTest() {
+    directionX = currentX - lastX;
+    directionY = currentY - lastY;
+
+    magnitude = Math.sqrt(directionX * directionX + directionY * directionY);
+    if (magnitude === 0) {
+      throw new Error(`path: last <${lastX}, ${lastY}> set to current <${currentX}, ${currentY}>`);
+    }
+    normalX = directionX / magnitude;
+    normalY = directionY / magnitude;
+
+    invX = 1 / normalX;
+    invY = 1 / normalY;
+
+    tLeft = (boxLeft - lastX) * invX;
+    tTop = (boxTop - lastY) * invY;
+    tRight = (boxRight - lastX) * invX;
+    tBottom = (boxBottom - lastY) * invY;
+  }
+
+  // After calculated a new tBest based on the normal, update lastX lastY to
+  // be at the point of intersection.
+  function updateToPointOfIntersection() {
+    lastX += normalX * tBest;
+    lastY += normalY * tBest;
+
+    return true;
+  }
+
+  // find the point of intersection with the box closest to l0 towards l1. If
+  // it exists, update last to that point and return true. Otherwise, return
+  // false. Algorithm for testing ray/box intersection is available many
+  // places, eg
+  // https://www.scratchapixel.com/lessons/3d-basic-rendering/minimal-ray-tracer-rendering-simple-shapes/ray-box-intersection
+  // https://medium.com/@bromanz/another-view-on-the-classic-ray-aabb-intersection-algorithm-for-bvh-traversal-41125138b525
+  function testOutInIntersection(): boolean {
+    setupIntersectionTest();
+
+    const tsmallx = Math.min(tLeft, tRight);
+    const tsmally = Math.min(tTop, tBottom);
+    const tbigx = Math.max(tLeft, tRight);
+    const tbigy = Math.max(tTop, tBottom);
+
+    tBest = Math.max(0, Math.max(tsmallx, tsmally));
+    const tMax = Math.min(tbigx, tbigy);
+
+    if (tBest > tMax) return false;
+    if (tBest <= 0) {
+      if (tMax > 0) {
+        tBest = tMax;
+      } else {
+        return false;
+      }
+    }
+    // If the best point is beyond the current point, this doesn't intersect.
+    if (tBest / magnitude > 1) return false;
+
+    return updateToPointOfIntersection();
+  }
+
+  // Find point of intersection from within the box closest to l0 towards l1.
+  // This is a slightly different algorithm than above, because
+  // testOutInIntersection is optimized for a ray intersecting the exterior (a
+  // convex polygon), while testInOutIntersection must look for the interior (a
+  // concave polycon).
+  function testInOutIntersection(): boolean {
+    setupIntersectionTest();
+
+    // Find the smallest intersection t that is greater than 0.
+    tBest = Number.MAX_VALUE;
+    if (tLeft > 0 && tLeft < tBest) tBest = tLeft;
+    if (tRight > 0 && tRight < tBest) tBest = tRight;
+    if (tTop > 0 && tTop < tBest) tBest = tTop;
+    if (tBottom > 0 && tBottom < tBest) tBest = tBottom;
+
+    if (tBest === Number.MAX_VALUE) return false;
+
+    return updateToPointOfIntersection();
+  }
+
+  //
+  // Main
+  //
+
+  // The index into `points` for the current <x, y>.
+  let i = 1;
+  // The {x, y} values at points[i].
+  let currentX: number, currentY: number;
+  let inBoxTest: IntersectionPoint = IntersectionPoint.UNSET;
+
+  // This loop walks through the list of points. The path cursor has already
+  // been (M)oved to the first point in the path. From here, it will attempt to
+  // (L)ine from point to point while inside the box, (M)ove from point to point
+  // while outside the box, and create new points at the path/bounding box
+  // intersection.
+  while (i < points.length) {
+    currentX = points[i].x;
+    currentY = points[i].y;
+
+    testInBox();
+
+    switch (inBoxTest as IntersectionPoint) {
+      case IntersectionPoint.OUTSIDE_OUTSIDE:
+        // line from last to current intersects the box
+        if (testOutInIntersection()) {
+          // testOutInIntersection set last point to intersection point
+          move();
+        } else {
+          // No intersection, so the line doesn't cross the box. Advance to the
+          // current (still outside) box point, basically throwing away this
+          // point and continue the next iteration.
+          advance();
+        }
+        break;
+      case IntersectionPoint.OUTSIDE_INSIDE:
+        if (!testOutInIntersection()) {
+          return doThrow("no outside to inside intersection");
+        }
+        // testOutInIntersection set last point to intersection point. Move the
+        // line to start at the edge of the box.
+        move();
+        break;
+      case IntersectionPoint.INSIDE_INSIDE:
+        advance();
+        // L to current point
+        line();
+        break;
+      case IntersectionPoint.INSIDE_OUTSIDE:
+        if (!testInOutIntersection()) {
+          return doThrow("no inside to outside intersection");
+        }
+        // L to point of intersection
+        line();
+        advance();
+        break;
+      default:
+        return doThrow(
+          `invalid box test state ${
+            Object.keys(IntersectionPoint).find(
+              (k) => IntersectionPoint[k as keyof typeof IntersectionPoint] === inBoxTest,
+            ) ?? inBoxTest
+          }`,
+        );
+    }
+  }
+
+  // If we only have one command, that means the line isn't in the box and
+  // there is nothing to display.
+  return commands.length > 1 ? commands.join(" ") : "";
+}