@davidsouther/agathon 0.0.0-stage → 0.0.0

package/src/geometry/quadtree.ts

@@ -0,0 +1,321 @@
+/**
+ * Fast, efficient, typesafe, custom quadtree that is capable of storing
+ * arbitrary polygons.
+ *
+ * http://www.cs.umd.edu/~meesh/cmsc420/ContentBook/FormalNotes/SametNotes/pm_quadtree_samet.pdf
+ *
+ * Why not:
+ *   *  goog.struct.Quadtree
+ *   *  d3.Quadtree
+ * Only store points; while geometries could be handled with bounds checking.
+ * Don't support lines & line crossing.
+ */
+
+import { assert } from "../assert.ts";
+import type { NodeId, Point, SegmentId } from "../types.ts";
+
+import { RectangleGeometry } from "./rectangle.ts";
+import type { Geometry, PolyLine } from "./types.ts";
+
+/** Maximum number of elements before splitting the quad tree. */
+const QUAD_TREE_SIZE = 4;
+
+/**
+ * An interface for a struct holding data managed by a QuadTree.
+ *
+ * See http://screen/C2qW9hmGE5RQJTg for a diagram.
+ */
+interface QuadTreeEntry {
+  /**
+   * The root QuadTree managing this entry. Needed when re-inserting items
+   * during splitting to track bookkeeping apporpriately.
+   */
+  root: QuadTree;
+  /** Whether this Entry is at the leaf, in which case it has no quadrants. */
+  isLeaf: boolean;
+  /** The four quadrants that make up the children of this QuadTree. */
+  quadrants?: [QuadTreeEntry, QuadTreeEntry, QuadTreeEntry, QuadTreeEntry];
+  /** Parent quad tree entry, to walk up for larger neighborhoods. */
+  parent?: QuadTreeEntry;
+  /**
+   * The covered bounds of this quad tree. The bounds of the four quadrants
+   * will fit inside these bounds.
+   */
+  bounds: Geometry;
+  /**
+   * The nodes whose geometries are completely contained in this Entry, but do
+   * not completely fit in any single quadrant of this entry.
+   */
+  children: Map<NodeId, Geometry>;
+  segments: Map<SegmentId, PolyLine>;
+}
+
+interface RegionSet {
+  nodes: Set<NodeId>;
+  segments: Set<PolyLine>;
+}
+
+function makeQuadTreeEntry(
+  root: QuadTree,
+  bounds: Geometry,
+  parent?: QuadTreeEntry,
+): QuadTreeEntry {
+  return {
+    isLeaf: true,
+    bounds,
+    root,
+    parent,
+    children: new Map<NodeId, Geometry>(),
+    segments: new Map<SegmentId, PolyLine>(),
+  };
+}
+
+function quadTreeRegion(
+  tree: QuadTreeEntry,
+  query: RegionSet,
+  region: Geometry,
+  size: number,
+): void {
+  for (const quadrant of tree.quadrants || []) {
+    if (quadrant.bounds.intersects(region)) {
+      quadTreeRegion(quadrant, query, region, size);
+    }
+  }
+
+  for (const [id, geom] of tree.children.entries()) {
+    if (query.nodes.has(id)) continue;
+    if (geom.intersects(region)) {
+      query.nodes.add(id);
+    }
+  }
+
+  for (const segment of tree.segments.values()) {
+    if (query.segments.has(segment)) continue;
+    const { points } = segment;
+    for (let i = 1; i < points.length; i++) {
+      const a = points[i - 1];
+      const b = points[i];
+      if (region.lineIntersects(a, b)) {
+        query.segments.add(segment);
+      }
+    }
+  }
+}
+
+/* Given a leaf quad tree entry, split it into four child quadrants and reinsert
+ * all children to update their positions. Each quadrants is created as a leaf
+ * so that the bounds information is always available, but that leaf will not be
+ * expanded until it grows larger than the carrying capacity. This results in at
+ * worst 3 empty quadrants per level of the tree, or O(1) memory overhead.
+ */
+function insertQuadTree(root: QuadTreeEntry, id: NodeId, geometry: Geometry): QuadTreeEntry {
+  if (!root.bounds.contains(geometry)) {
+    const entry = growQuadTree(root);
+    return insertQuadTree(entry, id, geometry);
+  }
+  if (root.isLeaf) {
+    if (root.children.size > QUAD_TREE_SIZE) {
+      splitQuadTree(root);
+      return insertQuadTree(root, id, geometry);
+    } else {
+      root.children.set(id, geometry);
+      return root;
+    }
+  } else {
+    for (const quadrant of root.quadrants || []) {
+      if (quadrant.bounds.contains(geometry)) {
+        return insertQuadTree(quadrant, id, geometry);
+      }
+    }
+    // The item spans multiple quadrants, add it to this node directly.
+    root.children.set(id, geometry);
+    return root;
+  }
+}
+
+function crossQuadTree(
+  tree: QuadTreeEntry,
+  set: Set<QuadTreeEntry>,
+  id: SegmentId,
+  segment: PolyLine,
+  a: Point,
+  b: Point,
+): void {
+  if (tree.isLeaf) {
+    tree.segments.set(id, segment);
+    set.add(tree);
+  } else {
+    for (const quadrant of tree.quadrants || []) {
+      if (quadrant.bounds.lineIntersects(a, b)) {
+        crossQuadTree(quadrant, set, id, segment, a, b);
+      }
+    }
+  }
+}
+
+function splitQuadTree(tree: QuadTreeEntry): void {
+  assert(tree.isLeaf, "Can only split leaf QuadTreeEntries");
+  tree.isLeaf = false;
+  const { width, x, y } = tree.bounds;
+  const side = width / 2;
+  const halfSide = side / 2;
+  tree.quadrants = [
+    makeQuadTreeEntry(
+      tree.root,
+      RectangleGeometry.square({
+        side,
+        point: { x: x + halfSide, y: y + halfSide },
+      }),
+      tree,
+    ),
+    makeQuadTreeEntry(
+      tree.root,
+      RectangleGeometry.square({
+        side,
+        point: { x: x - halfSide, y: y + halfSide },
+      }),
+      tree,
+    ),
+    makeQuadTreeEntry(
+      tree.root,
+      RectangleGeometry.square({
+        side,
+        point: { x: x - halfSide, y: y - halfSide },
+      }),
+      tree,
+    ),
+    makeQuadTreeEntry(
+      tree.root,
+      RectangleGeometry.square({
+        side,
+        point: { x: x + halfSide, y: y - halfSide },
+      }),
+      tree,
+    ),
+  ];
+
+  const { children, segments } = tree;
+  tree.children = new Map();
+  for (const [id, geom] of children.entries()) {
+    tree.root.set(id, geom);
+  }
+  for (const [id, polyline] of segments.entries()) {
+    tree.root.link(id, polyline);
+  }
+}
+
+/* Growing a quad tree takes the current root node, and makes it one quadrants
+ * of a node the next level up. The next node then has twice the side length and
+ * four times the area. The center of the next node up is either the origin, if
+ * the old tree is rooted not at the origin, or at the corner opposite the
+ * origin, if the old tree is rooted at the origin. Thus, every root will either
+ * be centered at the origin, or it will have one corner at the origin. By
+ * consistently growing in this manner, the tree will grow neer the origin. It
+ * is assumed that points will be preferentially near the origin.
+ */
+function growQuadTree(tree: QuadTreeEntry): QuadTreeEntry {
+  const { height: side, x, y } = tree.bounds;
+  const atOrigin = x === 0 && y === 0;
+  const point = atOrigin ? { x: side, y: side } : { x: 0, y: 0 };
+
+  const entry = makeQuadTreeEntry(tree.root, RectangleGeometry.square({ side: side * 2, point }));
+  entry.isLeaf = false;
+  if (atOrigin) {
+    // Old tree is at <0, 0>, create the other quadrants
+    entry.quadrants = [
+      tree,
+      makeQuadTreeEntry(tree.root, RectangleGeometry.square({ side, point: { x: side, y: 0 } })),
+      makeQuadTreeEntry(tree.root, RectangleGeometry.square({ side, point: { x: 0, y: side } })),
+      makeQuadTreeEntry(tree.root, RectangleGeometry.square({ side, point: { x: side, y: side } })),
+    ];
+  } else {
+    // Old tree is at <half, half>, create the other quadrants
+    const half = side / 2;
+    entry.quadrants = [
+      tree,
+      makeQuadTreeEntry(
+        tree.root,
+        RectangleGeometry.square({ side, point: { x: -half, y: half } }),
+      ),
+      makeQuadTreeEntry(
+        tree.root,
+        RectangleGeometry.square({ side, point: { x: -half, y: -half } }),
+      ),
+      makeQuadTreeEntry(
+        tree.root,
+        RectangleGeometry.square({ side, point: { x: half, y: -half } }),
+      ),
+    ];
+  }
+  rePlant(entry);
+  return entry;
+}
+
+function rePlant(entry: QuadTreeEntry) {
+  // "friend" method
+  (entry.root as unknown as { root: QuadTreeEntry }).root = entry;
+  for (const quad of entry.quadrants || []) {
+    quad.parent = entry;
+  }
+}
+
+/** QuadTree implementation. */
+export class QuadTree {
+  protected children = new Map<NodeId, QuadTreeEntry>();
+  protected segments = new Map<SegmentId, Set<QuadTreeEntry>>();
+  protected root: QuadTreeEntry = makeQuadTreeEntry(
+    this,
+    RectangleGeometry.square({ side: 256, point: { x: 128, y: 128 } }),
+  );
+
+  /** Mark id in the appropriate quad given the geometry. */
+  set(id: NodeId, geometry: Geometry): void {
+    if (this.children.has(id)) {
+      this.children.get(id)!.children.delete(id);
+      this.children.delete(id);
+    }
+    const tree = insertQuadTree(this.root, id, geometry);
+    this.children.set(id, tree);
+  }
+
+  /**
+   * Mark line as crossing the appropriate quad given the geometry. Both source
+   * and target nodes must already be in the quadtree.
+   */
+  link(segmentId: SegmentId, polyline: PolyLine): void {
+    if (this.segments.has(segmentId)) {
+      for (const entry of this.segments.get(segmentId)!) {
+        entry.segments.delete(segmentId);
+      }
+      this.segments.delete(segmentId);
+    }
+    const set = new Set<QuadTreeEntry>();
+    for (let i = 1; i < polyline.points.length; i++) {
+      crossQuadTree(
+        this.root,
+        set,
+        segmentId,
+        polyline,
+        polyline.points[i - 1],
+        polyline.points[i],
+      );
+    }
+    this.segments.set(segmentId, set);
+  }
+
+  /**
+   * Given a geometry, return all nodes and segments that could be in that
+   * region. Contained nodes' IDs are included, as well as IDs for nodes ending
+   * segments which originate from, terminate in, or cross over this quadtree.
+   *
+   * For nodes with geometries that would be smaller than a certain size, return
+   * an ID for a composite node with all the children. ??
+   */
+  region(geometry: Geometry, size = 1): RegionSet {
+    const nodes = new Set<NodeId>();
+    const segments = new Set<PolyLine>();
+    const region = { nodes, segments };
+    quadTreeRegion(this.root, region, geometry, size);
+    return region;
+  }
+}

package/src/geometry/rectangle.ts

@@ -0,0 +1,129 @@
+import type { Bounds, Point } from "../types.ts";
+
+import { BASE_RADIUS, BaseGeometry, clipi, type GeometryParams, origin } from "./geometry.ts";
+import type { Line } from "./types.ts";
+
+/** An interface describing the input for a square. */
+export interface SquareParams extends GeometryParams {
+  /** Length of one side of the square. */
+  side: number;
+}
+
+const SQUARE_SIDE = BASE_RADIUS * 2;
+
+/** An interface describing the input for a rectangle. */
+export interface RectangleParams extends GeometryParams {
+  /** Length along the X axis. */
+  width: number;
+
+  /** Length along the Y axis. */
+  height: number;
+}
+
+// Constants to help clipi
+const R45 = (-45 * Math.PI) / 180;
+const COS45 = Math.cos(R45);
+const SIN45 = Math.sin(R45);
+
+/** Implementation of a Geometry representing an axis-aligned rectangle. */
+export class RectangleGeometry extends BaseGeometry {
+  // Width / height
+  private aspect!: number;
+
+  static square({ side, point }: { side?: number; point?: Point }): RectangleGeometry {
+    return new RectangleGeometry({ width: side, height: side, point });
+  }
+
+  static plane(): RectangleGeometry {
+    return new RectangleGeometry({ width: Number.MAX_SAFE_INTEGER });
+  }
+
+  constructor({
+    width = SQUARE_SIDE * 2,
+    height = SQUARE_SIDE,
+    point = origin(),
+  }: Readonly<Partial<RectangleParams>> = {}) {
+    super({ point });
+    this.resize({ height, width });
+  }
+
+  makeClone(): RectangleGeometry {
+    const { height, width } = this;
+    return new RectangleGeometry({ point: this, height, width });
+  }
+
+  resize(size: number | Bounds): void {
+    let height: number;
+    let width: number;
+
+    if (typeof size === "number") {
+      height = width = size;
+    } else {
+      height = size.height;
+      width = size.width;
+    }
+
+    this.bounds.width = width;
+    this.bounds.height = height;
+    this.aspect = width / height;
+  }
+
+  clipi(line: Line): void {
+    // To quickly clip the line to an edge, perform an affine transformation on
+    // the line's source point. This affine transoformation aligns the point
+    // along the rectangle's diagonals as normal axes. We then rotate the point
+    // 45degrees counterclockwise so that the diagonales align the unit axes.
+    // This allows a simple quadrant check to choose which rectangle edge to
+    // clip to.
+
+    let { x, y } = line[0];
+    x -= this.x;
+    y -= this.y;
+
+    x /= this.aspect;
+
+    const x2 = x * COS45 - y * SIN45;
+    y = x * SIN45 + y * COS45;
+    x = x2;
+
+    // Based on angle from the origin to the line start, choose an edge.
+    // Because the line point has been projected and rotated, a simple quadrant
+    // check tells the corners to use for the edge.
+    const h2 = this.height / 2;
+    const w2 = this.width / 2;
+    let edge: Line;
+    if (x >= 0 && y >= 0) {
+      edge = [
+        { x: w2, y: h2 },
+        { x: -w2, y: h2 },
+      ];
+    } else if (x <= 0 && y >= 0) {
+      edge = [
+        { x: -w2, y: h2 },
+        { x: -w2, y: -h2 },
+      ];
+    } else if (x <= 0 && y <= 0) {
+      edge = [
+        { x: -w2, y: -h2 },
+        { x: w2, y: -h2 },
+      ];
+    } else if (x >= 0 && y <= 0) {
+      edge = [
+        { x: w2, y: -h2 },
+        { x: w2, y: h2 },
+      ];
+    } else {
+      throw new Error("Non-coplanar line clipped to rectangle");
+    }
+
+    // Clip line to edge
+    clipi(line, edge);
+  }
+}
+
+/** Implementation of a geometry representing an axis-aligned square. */
+export class SquareGeometry extends RectangleGeometry {
+  constructor({ side = SQUARE_SIDE, point = origin() }: Readonly<Partial<SquareParams>> = {}) {
+    super({ width: side, height: side, point });
+  }
+}

package/src/geometry/rngon.ts

@@ -0,0 +1,132 @@
+import { assertExists } from "../assert.ts";
+import type { Bounds, Point } from "../types.ts";
+
+import { CircleGeometry } from "./circle.ts";
+import { BASE_RADIUS, BaseGeometry, clipi, type GeometryParams, origin } from "./geometry.ts";
+import type { Geometry, Line, Radian } from "./types.ts";
+
+/**
+ * Parameters to create an rngon.
+ *
+ * For a surprisingly good overview, see
+ * https://www.mathsisfun.com/geometry/regular-polygons.html
+ */
+export interface RNGonParams extends GeometryParams {
+  /** Number of sides of the RNGon. */
+  n: number;
+
+  rotation: Radian;
+
+  /**
+   * Radius of the NGon. All points along the polygon will be this distance from
+   * the center.
+   */
+  radius: number;
+}
+
+const RNGON_N = 6;
+const RNGON_ROTATION = 0;
+
+/**
+ * An RNGon is a Regular N-verticy Polygon. N must be greater than 2. Regular is
+ * a light misnomer, as the class provides rotation and affine transformations.
+ * An RNGon with a side length less than 1 creates a circle. The RNGon will be
+ * rotated by `rotation` radians. This is easiest to visualize with a triangle,
+ * which will "point" to the right with zero rotation. Positive rotation will
+ * spin the RNGon counter-clockwise.
+ */
+export class RNGon extends BaseGeometry {
+  private readonly n: number;
+  private rad: number;
+  private rotation: Radian;
+  private sideAngle!: number;
+  // Has N+1 points, as first point is duplicated to make clipi easier
+  private readonly points: Array<Readonly<Point>> = [];
+
+  static circle({ point, radius }: Partial<Omit<RNGonParams, "n">> = {}): Geometry {
+    return new CircleGeometry({ point, radius });
+  }
+
+  static point(point: Point = { x: 0, y: 0 }): Geometry {
+    return new CircleGeometry({ point, radius: 0 });
+  }
+
+  override get radius(): number {
+    return this.rad;
+  }
+
+  constructor({
+    n = RNGON_N,
+    radius = BASE_RADIUS,
+    rotation = RNGON_ROTATION,
+    point = origin(),
+  }: Readonly<Partial<RNGonParams>> = {}) {
+    super({ point });
+    this.n = n;
+    this.rad = radius;
+    this.rotation = rotation;
+    this.update();
+  }
+
+  override makeClone(): RNGon {
+    const { n, radius, rotation } = this;
+    return new RNGon({ n, radius, rotation, point: this });
+  }
+
+  resize(size: number | Bounds): void {
+    if (typeof size === "number") {
+      this.rad = size;
+    } else {
+      this.rad = Math.max(size.width, size.height) / 2;
+    }
+    this.update();
+  }
+
+  private update() {
+    const anglePart = Math.PI / this.n;
+    this.sideAngle = 2 * anglePart;
+
+    this.updatePoints();
+    this.updateBox();
+  }
+
+  private updatePoints() {
+    this.points.splice(0, this.points.length);
+    const theta = this.rotation;
+    const maxTheta = this.rotation + 2 * Math.PI;
+    const step = (2 * Math.PI) / this.n;
+    for (let t = theta; t <= maxTheta; t += step) {
+      const x = Math.cos(t) * this.radius;
+      const y = Math.sin(t) * this.radius;
+      this.points.push({ x, y });
+    }
+  }
+
+  /**
+   * Update the box. Must call updatePoints first. See public `update` method.
+   */
+  private updateBox() {
+    const xs = this.points.map(({ x }) => x);
+    const ys = this.points.map(({ y }) => y);
+    const maxX = Math.max(...xs);
+    const minX = Math.min(...xs);
+    const maxY = Math.max(...ys);
+    const minY = Math.min(...ys);
+    this.bounds.width = maxX - minX;
+    this.bounds.height = maxY - minY;
+  }
+
+  clipi(line: Line): void {
+    // Find edge closest to start of the line
+    const dx = line[1].x - this.x;
+    const dy = line[1].y - this.y;
+    const theta = (Math.atan2(dx, dy) + this.rotation) % (2 * Math.PI);
+    const side = Math.floor(theta / this.sideAngle);
+
+    const edgeStart = assertExists(this.points[side]);
+    const edgeEnd = assertExists(this.points[side + 1]);
+
+    // Clip to closest edge
+    clipi(line, [edgeStart, edgeEnd]);
+  }
+}

package/src/geometry/types.ts

@@ -0,0 +1,102 @@
+import type { Bounds, NodeId, Point } from "../types.ts";
+
+/** Nominal type for radians */
+export type Radian = number;
+
+/** A line is a simple 2vec stored as a tuple. */
+export type Line = [Point, Point];
+
+/**
+ * Polyline has starting and ending nodes, with some number of intermediate
+ * points.
+ */
+export interface PolyLine {
+  source: NodeId;
+  target: NodeId;
+  points: [Point, Point, ...Point[]];
+}
+
+/**
+ * A Geometry has a Point and Bound in a vector space, and can clip lines to
+ * its boundaries.
+ */
+export interface Geometry extends Bounds, Point {
+  readonly left: number;
+  readonly right: number;
+  readonly top: number;
+  readonly bottom: number;
+
+  /** Utility for getting just the {x, y} point. */
+  readonly point: Readonly<Point>;
+
+  /** The smallest radius to completely contain this geometry. */
+  readonly radius: number;
+
+  /** Update a Geometry's position by a point delta. */
+  move(delta: Point): void;
+
+  /** Update a Geometry's position to an explicit point. */
+  moveTo(point: Point): void;
+
+  /** Update a Geometry's user-contributed drag position by a point delta. */
+  drag(delta: Point): void;
+
+  /**
+   * Update a Geometry's user-contributed drag position to an explicit point.
+   */
+  dragTo(point: Point): void;
+
+  /**
+   * Change the second point in line to be on the edge of the Geometry nearest
+   * the first point of the line. No change if the starting point is inside the
+   * geometry or if the end point is outside the geometry.
+   *
+   * Short for "clip _i_nplace".
+   *
+   * Users of a Geometry should prefer this method for performance.
+   */
+  clipi(line: Line): void;
+
+  /**
+   * Return the point of intersection between the line and the line on the
+   * geometry closes to the first point of the line. No change if the starting
+   * point is inside the geometry or if the end point is outside the geometry.
+   *
+   * Users of a Geometry should prefer calling this method for clarity.
+   */
+  clip(line: Readonly<Line>): Point;
+
+  /**
+   * Resize the geometry as appropriate for the geometry class. Resizing to a
+   * radius will attempt to resize to a consistent size (circular/square/regular
+   * polygon). Resizing to a bounds will attempt to create the geometry with
+   * an aspect ratio matching the bounds, aligned to the axis.
+   */
+  resize(size: number | Bounds): void;
+
+  /**
+   * Treating both geometries as Axis-Aligned Bounding Boxes, test whether
+   * `geometry` is contained inside `this`.
+   */
+  contains(geometry: Geometry): boolean;
+
+  /**
+   * Treating both geometries as Axis-aligned Bounding Boxes, test whether
+   * `geometry` intersects `this`.
+   */
+  intersects(geometry: Geometry): boolean;
+
+  /**
+   * Given two points, checks whether a line segment connecting those points
+   * intersects with the AABB of this geometry.
+   */
+  lineIntersects(a: Point, b: Point): boolean;
+
+  /**
+   * Given a collection of geometries, change this geometry's size to contain
+   * them, and update all positions to remain centered.
+   */
+  fitTo(children: Iterable<Geometry>, padding: number): void;
+
+  clone(): Geometry;
+}