@mark1russell7/packing 0.0.0-bootstrap.0 → 0.1.0

package/src/metrics.ts

@@ -0,0 +1,72 @@
+import type { Rect } from "./rect.ts";
+
+/** The measurements of a packing. */
+export interface PackingMetrics {
+  /** The number of rectangles. */
+  count: number;
+  /** The size of the hull: the smallest box around the rectangles. */
+  hull: { width: number; height: number };
+  /** The width of the hull divided by its height. A hull without height gives 0. */
+  hullAspect: number;
+  /** The number of rectangles in each row, from the top. */
+  rows: number[];
+  /** The largest right edge of a row less the smallest right edge of a row. A straight right side gives 0. */
+  raggedness: number;
+  /** The part of the hull that the rectangles cover: their area divided by the area of the hull. */
+  utilization: number;
+  /** The width of the widest rectangle divided by the median width. */
+  widestOverMedian: number;
+}
+
+/** The options of `packingMetrics`. */
+export interface MetricsOptions {
+  /** A rectangle joins a row when its top is this close to the top of the first rectangle of the row. The default is 40. */
+  rowTolerance?: number;
+}
+
+/**
+ * This function measures a packing. It gives the hull and its aspect, the rows and the raggedness of the right side.
+ * It also gives the part of the hull that the rectangles cover, and the widest rectangle against the median width.
+ *
+ * @example
+ * ```ts
+ * const { utilization, raggedness } = packingMetrics(Rect.packed(cards));
+ * ```
+ */
+export function packingMetrics(rects: readonly Rect[], options: MetricsOptions = {}): PackingMetrics {
+  const tolerance = options.rowTolerance ?? 40;
+  const boxes = rects.filter((r) => r.size.x > 0 && r.size.y > 0);
+  if (boxes.length === 0) return { count: 0, hull: { width: 0, height: 0 }, hullAspect: 0, rows: [], raggedness: 0, utilization: 0, widestOverMedian: 0 };
+
+  const left = Math.min(...boxes.map((r) => r.position.x));
+  const top = Math.min(...boxes.map((r) => r.position.y));
+  const right = Math.max(...boxes.map((r) => r.right()));
+  const bottom = Math.max(...boxes.map((r) => r.bottom()));
+  const hull = { width: right - left, height: bottom - top };
+
+  // The rows: the rectangles by their top, and a row takes each rectangle near the top of its first rectangle
+  const rows: { top: number; right: number; count: number }[] = [];
+  for (const r of boxes.toSorted((a, b) => a.position.y - b.position.y)) {
+    const row = rows.at(-1);
+    if (row && Math.abs(r.position.y - row.top) <= tolerance) {
+      row.right = Math.max(row.right, r.right());
+      row.count += 1;
+    } else {
+      rows.push({ top: r.position.y, right: r.right(), count: 1 });
+    }
+  }
+  const rights = rows.map((row) => row.right);
+  const widths = boxes.map((r) => r.size.x).toSorted((a, b) => a - b);
+  const median = widths[Math.floor(widths.length / 2)] ?? 0;
+  const widest = widths.at(-1) ?? 0;
+  const area = boxes.reduce((sum, r) => sum + r.area(), 0);
+  return {
+    count: boxes.length,
+    hull,
+    hullAspect: hull.height > 0 ? hull.width / hull.height : 0,
+    rows: rows.map((row) => row.count),
+    raggedness: Math.max(...rights) - Math.min(...rights),
+    utilization: hull.width * hull.height > 0 ? area / (hull.width * hull.height) : 0,
+    widestOverMedian: median > 0 ? widest / median : 0,
+  };
+}

package/src/order.ts

@@ -0,0 +1,26 @@
+import type { Rect } from "./rect.ts";
+
+/**
+ * An order of the rectangles before the packing. The order changes the layout much. `input` keeps the order of
+ * the array of the caller: the row packing then fills no gaps, so its rows read in that order.
+ */
+export type SortOrder = "height-desc" | "height-asc" | "width-desc" | "area-desc" | "input";
+
+/** This constant lists each sort order. The first one is the default. */
+export const SORT_ORDERS: readonly SortOrder[] = ["height-desc", "height-asc", "width-desc", "area-desc", "input"];
+
+/** This function gives the comparator of a sort order. The sort is stable, so `input` keeps the order. */
+export function compareRects(order: SortOrder): <T>(a: Rect<T>, b: Rect<T>) => number {
+  switch (order) {
+    case "height-desc":
+      return (a, b) => b.size.y - a.size.y;
+    case "height-asc":
+      return (a, b) => a.size.y - b.size.y;
+    case "width-desc":
+      return (a, b) => b.size.x - a.size.x;
+    case "area-desc":
+      return (a, b) => b.area() - a.area();
+    case "input":
+      return () => 0;
+  }
+}

package/src/pack.ts

@@ -0,0 +1,132 @@
+import { compareRects, type SortOrder } from "./order.ts";
+import { Rect } from "./rect.ts";
+import { packSkyline } from "./skyline.ts";
+import { Vector } from "./vector.ts";
+
+/** The options of `pack` and `packRows` */
+export interface PackOptions {
+  /** The order of the rectangles before the packing. The default is `height-desc`. */
+  sortOrder?: SortOrder;
+}
+
+/** The options of `pack` */
+export interface PackLayoutOptions extends PackOptions {
+  /** The packing: `rows` (the default) or `skyline`. Use `skyline` to pack around locked rectangles. */
+  strategy?: "rows" | "skyline";
+}
+
+function packInto<T>(rects: Rect<T>[], region: Rect<T>, offset: Vector, order: SortOrder): void {
+  const unpacked = Rect.unpacked(rects);
+  pack(unpacked, region, { sortOrder: order });
+  for (const r of Rect.packed(unpacked)) r.translateBy(offset);
+}
+
+function packRow<T>(rects: Rect<T>[], outer: Rect<T>, order: SortOrder): boolean {
+  const row: Rect<T>[] = [];
+  // toSorted gives a sorted copy, thus the order of the array of the caller stays
+  const byHeight = rects.toSorted(compareRects(order));
+  // A gap fill puts a later rect before an earlier one, thus the order `input` fills no gaps
+  const fillGaps = order !== "input";
+
+  const rowRect = new Rect<T>();
+  rowRect.size.set(outer.size.x, 0);
+
+  for (const rect of byHeight) {
+    if (rect.wasPacked) continue;
+
+    if (rect.size.x > rowRect.size.x) {
+      if (outer.fixedSize && rect.size.x > outer.size.x) continue;
+
+      const outerLeft = new Rect<T>();
+      outerLeft.position.setTo(rowRect.position);
+      outerLeft.size.set(outer.size.x - rowRect.position.x, rowRect.size.y);
+      outerLeft.fixedSize = true;
+      if (fillGaps) packInto(rects, outerLeft, outer.position, order);
+
+      rowRect.position.set(0, rowRect.bottom());
+      rowRect.size.set(outer.size.x, 0);
+      row.length = 0;
+    }
+
+    if (rowRect.position.y + rect.size.y > outer.size.y) {
+      if (outer.fixedSize) continue;
+      outer.size.y += rect.size.y;
+      if (!outer.fixedWidth && !outer.size.x) outer.size.x = rect.size.x;
+      Rect.resetPacked(rects);
+      return false;
+    }
+
+    row.push(rect);
+    rect.position.setTo(rowRect.position.add(outer.position));
+    rowRect.shrinkLeft(rect.size.x);
+    rect.wasPacked = true;
+
+    if (rect.size.y > rowRect.size.y) rowRect.size.y = rect.size.y;
+
+    if (fillGaps && row.length > 1) {
+      const rectInRow = row[row.length - 1]!;
+      const outerLeft = new Rect<T>();
+      outerLeft.position.set(rectInRow.position.x, rectInRow.bottom());
+      outerLeft.size.set(rectInRow.size.x, rowRect.size.y - rectInRow.size.y);
+      outerLeft.fixedWidth = true;
+      outerLeft.fixedSize = true;
+      packInto(rects, outerLeft, outer.position, order);
+    }
+  }
+  return true;
+}
+
+/**
+ * This function packs rectangles into an outer rectangle of a given width with a guillotine row packing. It does
+ * not change the width. Without `fixedSize`, the height grows until all rectangles fit. A `locked` rectangle keeps
+ * its position, but the rows do not go around it. `pack` sets the width first and then uses this function.
+ */
+export function packRows<T>(rects: Rect<T>[], outer: Rect<T>, options: PackOptions = {}): Rect<T> {
+  const order = options.sortOrder ?? "height-desc";
+  for (const r of rects) if (r.locked) r.wasPacked = true;
+  while (!packRow(rects, outer, order));
+  return outer;
+}
+
+/**
+ * This function packs rectangles into an outer rectangle with a guillotine row packing. It sets the position
+ * of each rectangle and the size of the outer rectangle, and it gives the outer rectangle.
+ *
+ * - Without fixed sizes, the outer rectangle starts with a width of 1.5 times the square root of the total area.
+ *   This width is not less than the width of the widest rectangle. The height grows until all rectangles fit.
+ * - With `fixedWidth`, the width stays. A rectangle wider than that width goes on its own row and overflows.
+ * - With `fixedSize`, a rectangle that does not fit is not packed: its `wasPacked` stays `false`.
+ * - `options.strategy` selects `packRows` (the default) or `packSkyline` after the width is set.
+ */
+export function pack<T>(rects: Rect<T>[], outer: Rect<T> = new Rect(), options: PackLayoutOptions = {}): Rect<T> {
+  let totalArea = 0;
+  let widest = 0;
+  let minX = rects.length > 0 ? Infinity : 0;
+  let minY = rects.length > 0 ? Infinity : 0;
+  for (const r of rects) {
+    totalArea += r.area();
+    widest = Math.max(widest, r.size.x);
+    minX = Math.min(minX, r.size.x);
+    minY = Math.min(minY, r.size.y);
+  }
+
+  const idealWidth = outer.fixedWidth
+    ? outer.size.x
+    : Math.max(widest, Math.min(1.5 * Math.sqrt(totalArea), outer.size.x || Infinity));
+
+  const ideal = Vector.of(idealWidth).clamp(new Vector(minX, minY), Vector.Infinity);
+
+  // A fixed width stays, also when a rectangle is wider: that rectangle overflows
+  if (!outer.fixedSize) outer.size.setTo(outer.fixedWidth ? new Vector(outer.size.x, ideal.y) : ideal);
+  if (options.strategy === "skyline") packSkyline(rects, outer, options);
+  else packRows(rects, outer, options);
+
+  if (!outer.fixedSize) {
+    const contentRight = Rect.maxRight(rects);
+    if (!outer.size.x) outer.size.x = contentRight;
+    else if (!outer.fixedWidth) outer.size.x = Math.min(contentRight, outer.size.x);
+    outer.size.y = Rect.maxBottom(rects);
+  }
+
+  return outer;
+}

package/src/push.ts

@@ -0,0 +1,83 @@
+import type { Rect } from "./rect.ts";
+
+/** The options of `pushCascade`. */
+export interface PushOptions {
+  /** The space between a shoved rectangle and the rectangle that shoves it. The default is 8. */
+  gap?: number;
+  /** The most shoves. The default is eight for each rectangle. The cascade stops at this limit. */
+  maxShoves?: number;
+}
+
+/** A direction of a shove: an axis and a sign. */
+interface Direction {
+  readonly axis: "x" | "y";
+  readonly sign: 1 | -1;
+}
+
+/** This function gives the overlap of two rectangles on each axis. A value of 0 or less is no overlap. */
+function overlapOf(a: Rect, b: Rect): { x: number; y: number } {
+  return {
+    x: Math.min(a.right(), b.right()) - Math.max(a.position.x, b.position.x),
+    y: Math.min(a.bottom(), b.bottom()) - Math.max(a.position.y, b.position.y),
+  };
+}
+
+/**
+ * This function gives the direction of a first shove. The axis has the smaller overlap. The sign points away from the
+ * center of the pusher. When that shove crosses 0, the sign is positive.
+ */
+function firstDirection(pusher: Rect, r: Rect, gap: number): Direction {
+  const overlap = overlapOf(pusher, r);
+  if (overlap.x < overlap.y) {
+    const back = r.position.x + r.size.x / 2 < pusher.position.x + pusher.size.x / 2 && pusher.position.x - r.size.x - gap >= 0;
+    return { axis: "x", sign: back ? -1 : 1 };
+  }
+  const back = r.position.y + r.size.y / 2 < pusher.position.y + pusher.size.y / 2 && pusher.position.y - r.size.y - gap >= 0;
+  return { axis: "y", sign: back ? -1 : 1 };
+}
+
+/** This function puts a rectangle past the pusher, along a direction. The rectangle does not go past 0. */
+function shove(pusher: Rect, r: Rect, direction: Direction, gap: number): void {
+  if (direction.axis === "x") {
+    const x = direction.sign > 0 ? pusher.right() + gap : pusher.position.x - r.size.x - gap;
+    r.position.set(Math.max(0, x), r.position.y);
+    return;
+  }
+  const y = direction.sign > 0 ? pusher.bottom() + gap : pusher.position.y - r.size.y - gap;
+  r.position.set(r.position.x, Math.max(0, y));
+}
+
+/**
+ * This function moves each rectangle that a placed rectangle overlaps, and the rectangles that those overlap in turn.
+ * A shove takes the axis of the smaller overlap, away from the pusher. A shoved rectangle keeps the direction of its first
+ * shove when it shoves the next one, so the cascade goes outward. The placed rectangle and each locked rectangle stay.
+ * The function moves the rectangles in place and gives the rectangles that moved.
+ *
+ * @example
+ * ```ts
+ * const moved = pushCascade(dropped, cards, { gap: 8 });
+ * ```
+ */
+export function pushCascade<T>(placed: Rect<T>, rects: readonly Rect<T>[], options: PushOptions = {}): Rect<T>[] {
+  const gap = options.gap ?? 8;
+  const maxShoves = options.maxShoves ?? rects.length * 8;
+  const moved = new Set<Rect<T>>();
+  const queue: { pusher: Rect<T>; direction?: Direction }[] = [{ pusher: placed }];
+  let shoves = 0;
+  while (shoves < maxShoves) {
+    const step = queue.shift();
+    if (!step) break;
+    const { pusher, direction } = step;
+    for (const r of rects) {
+      if (r === pusher || r === placed || r.locked) continue;
+      const overlap = overlapOf(pusher, r);
+      if (overlap.x <= 0 || overlap.y <= 0) continue;
+      const next = direction ?? firstDirection(pusher, r, gap);
+      shove(pusher, r, next, gap);
+      moved.add(r);
+      queue.push({ pusher: r, direction: next });
+      if (++shoves >= maxShoves) break;
+    }
+  }
+  return [...moved];
+}

package/src/rect.ts

@@ -0,0 +1,73 @@
+import { Vector } from "./vector.ts";
+
+/** A rectangle of the packer. `id` identifies the item that it measures. The packer sets `position` and `wasPacked`. */
+// oxlint-disable-next-line typescript/no-unnecessary-type-parameters -- the parameter types the id of the caller
+export class Rect<T = unknown> {
+  readonly #position = new Vector();
+  readonly #size = new Vector();
+
+  /** The identity of the item that the rectangle measures. */
+  id?: T;
+  /** The packer sets this field to `true` when it places the rectangle. */
+  wasPacked = false;
+  /** For an outer rectangle: the packer keeps its width. */
+  fixedWidth = false;
+  /** For an outer rectangle: the packer keeps its width and its height, and it skips a rectangle that does not fit. */
+  fixedSize = false;
+  /**
+   * The packer keeps the position of a locked rectangle. `packSkyline` packs the other rectangles around it.
+   * `packRows` only keeps its position, and other rectangles can overlap it.
+   */
+  locked = false;
+
+  /** The top left corner. */
+  get position(): Vector { return this.#position; }
+  /** The width and the height. */
+  get size(): Vector { return this.#size; }
+
+  /** This method gives the right edge. */
+  right(): number { return this.#position.x + this.#size.x; }
+  /** This method gives the bottom edge. */
+  bottom(): number { return this.#position.y + this.#size.y; }
+
+  /** This method moves the left edge to the right by an amount, and the right edge stays. */
+  shrinkLeft(amount: number): this {
+    this.#position.x += amount;
+    this.#size.x -= amount;
+    return this;
+  }
+
+  /** This method moves the rectangle by an offset. */
+  translateBy(offset: Vector): this {
+    this.#position.set(this.#position.x + offset.x, this.#position.y + offset.y);
+    return this;
+  }
+
+  /** This method gives the area of the size. */
+  area(): number { return this.#size.area(); }
+
+  /** This function gives the rectangles that the packer placed. */
+  static packed<U>(rects: Rect<U>[]): Rect<U>[] {
+    return rects.filter((r) => r.wasPacked);
+  }
+
+  /** This function gives the rectangles that the packer did not place. */
+  static unpacked<U>(rects: Rect<U>[]): Rect<U>[] {
+    return rects.filter((r) => !r.wasPacked);
+  }
+
+  /** This function marks each rectangle as not placed. A locked rectangle stays placed. */
+  static resetPacked<U>(rects: Rect<U>[]): void {
+    for (const r of rects) r.wasPacked = r.locked;
+  }
+
+  /** This function gives the largest right edge, or 0 for an empty list. */
+  static maxRight<U>(rects: Rect<U>[]): number {
+    return rects.reduce((acc, r) => Math.max(acc, r.right()), 0);
+  }
+
+  /** This function gives the largest bottom edge, or 0 for an empty list. */
+  static maxBottom<U>(rects: Rect<U>[]): number {
+    return rects.reduce((acc, r) => Math.max(acc, r.bottom()), 0);
+  }
+}

package/src/skyline.ts

@@ -0,0 +1,83 @@
+import { compareRects, type SortOrder } from "./order.ts";
+import type { Rect } from "./rect.ts";
+
+/**
+ * This function finds the lowest window of width `rw` on a skyline. For each `x` in `[0, width - rw]`, the height
+ * of the window is the largest value of `skyline[x, x + rw)`. The first `x` with the smallest height wins. A
+ * monotonic deque makes the search O(width) for one rectangle.
+ */
+export function lowestWindow(skyline: ArrayLike<number>, width: number, rw: number): { x: number; y: number } {
+  const deque = new Int32Array(width);
+  let head = 0;
+  let tail = 0;
+  let bestX = 0;
+  let bestY = Infinity;
+  for (let i = 0; i < width; i++) {
+    while (tail > head && skyline[deque[tail - 1]!]! <= skyline[i]!) tail--;
+    deque[tail++] = i;
+    if (deque[head]! <= i - rw) head++;
+    if (i >= rw - 1) {
+      const max = skyline[deque[head]!]!;
+      if (max < bestY) {
+        bestY = max;
+        bestX = i - rw + 1;
+      }
+    }
+  }
+  return { x: bestX, y: bestY };
+}
+
+/**
+ * This function packs rectangles into an outer rectangle with a skyline. It puts each rectangle in the lowest place
+ * where it fits, and it does not change the width of the outer rectangle.
+ *
+ * - A `locked` rectangle keeps its position. The skyline starts at its bottom edge across its width, thus the other
+ *   rectangles go under it. The space above it stays empty, because a skyline has no holes.
+ * - The skyline has a cell for each whole unit of the width. A rectangle that needs more cells than the outer
+ *   rectangle has goes under all other rectangles, at the left edge.
+ * - Without `fixedSize`, the height of the outer rectangle grows to the content. With `fixedSize`, a rectangle that
+ *   does not fit is not packed: its `wasPacked` stays `false`.
+ * - The default sort order is `height-desc`. The order of the array of the caller stays.
+ */
+export function packSkyline<T>(rects: Rect<T>[], outer: Rect<T>, options: { sortOrder?: SortOrder } = {}): Rect<T> {
+  // a cell for each whole unit of the width: a rectangle never goes past the right edge
+  const width = Math.floor(outer.size.x);
+  if (width <= 0) return outer;
+  const skyline = new Float64Array(width);
+
+  for (const rect of rects) {
+    if (!rect.locked) continue;
+    rect.wasPacked = true;
+    const x0 = Math.max(0, Math.floor(rect.position.x - outer.position.x));
+    const x1 = Math.min(width, Math.ceil(rect.position.x - outer.position.x + rect.size.x));
+    const bottom = rect.position.y - outer.position.y + rect.size.y;
+    for (let i = x0; i < x1; i++) skyline[i] = Math.max(skyline[i]!, bottom);
+    if (!outer.fixedSize) outer.size.y = Math.max(outer.size.y, bottom);
+  }
+
+  for (const rect of rects.toSorted(compareRects(options.sortOrder ?? "height-desc"))) {
+    if (rect.wasPacked) continue;
+    const rw = Math.ceil(rect.size.x);
+    const rh = rect.size.y;
+    if (rw <= 0 || rh <= 0) continue;
+
+    let x: number;
+    let y: number;
+    if (rw > width) {
+      if (outer.fixedSize) continue;
+      x = 0;
+      y = 0;
+      for (let i = 0; i < width; i++) if (skyline[i]! > y) y = skyline[i]!;
+    } else {
+      ({ x, y } = lowestWindow(skyline, width, rw));
+      if (outer.fixedSize && y + rh > outer.size.y) continue;
+    }
+
+    rect.position.set(x + outer.position.x, y + outer.position.y);
+    rect.wasPacked = true;
+    const top = y + rh;
+    for (let i = x; i < Math.min(width, x + rw); i++) skyline[i] = top;
+    if (!outer.fixedSize) outer.size.y = Math.max(outer.size.y, top);
+  }
+  return outer;
+}

package/src/vector.ts

@@ -0,0 +1,80 @@
+/** A mutable two-dimensional vector. */
+export class Vector {
+  #x: number;
+  #y: number;
+
+  constructor(x = 0, y = 0) {
+    this.#x = x;
+    this.#y = y;
+  }
+
+  /** The first component: a width or a left position. */
+  get x(): number { return this.#x; }
+  set x(v: number) { this.#x = v; }
+  /** The second component: a height or a top position. */
+  get y(): number { return this.#y; }
+  set y(v: number) { this.#y = v; }
+
+  /** This method sets both components. */
+  set(x: number, y: number): void {
+    this.#x = x;
+    this.#y = y;
+  }
+
+  /** This method copies the components of another vector. */
+  setTo(v: Vector): void {
+    this.#x = v.x;
+    this.#y = v.y;
+  }
+
+  /** This method gives a new vector: the sum of this vector and another. */
+  add(other: Vector): Vector {
+    return new Vector(this.#x + other.x, this.#y + other.y);
+  }
+
+  /** This method gives the product of the components: the area of a size. */
+  area(): number {
+    return this.#x * this.#y;
+  }
+
+  /** This method gives a new vector with the same components. */
+  clone(): Vector {
+    return new Vector(this.#x, this.#y);
+  }
+
+  /** This method gives a new vector with each component between the components of `min` and `max`. */
+  clamp(min: Vector, max: Vector): Vector {
+    return new Vector(
+      Math.max(min.x, Math.min(max.x, this.#x)),
+      Math.max(min.y, Math.min(max.y, this.#y)),
+    );
+  }
+
+  /** This function gives a vector with the same value in both components. */
+  static of(scalar: number): Vector {
+    return new Vector(scalar, scalar);
+  }
+
+  /** This function gives the smallest value of each component, or a zero vector for an empty list. */
+  static min(vectors: Vector[]): Vector {
+    if (!vectors.length) return new Vector();
+    return new Vector(
+      Math.min(...vectors.map((v) => v.x)),
+      Math.min(...vectors.map((v) => v.y)),
+    );
+  }
+
+  /** This function gives the largest value of each component, or a zero vector for an empty list. */
+  static max(vectors: Vector[]): Vector {
+    if (!vectors.length) return new Vector();
+    return new Vector(
+      Math.max(...vectors.map((v) => v.x)),
+      Math.max(...vectors.map((v) => v.y)),
+    );
+  }
+
+  /** This getter gives a new infinite vector each time. A shared value is not safe, because a vector is mutable. */
+  static get Infinity(): Vector {
+    return new Vector(Infinity, Infinity);
+  }
+}