@mark1russell7/packing 0.2.2 → 0.2.3

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@mark1russell7/packing",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Rectangle packing: shelf, guillotine and skyline strategies, push cascades and measures of a layout.",
   "keywords": [
     "rectangle-packing",

package/src/adapters.ts

@@ -3,6 +3,7 @@
 import { EPS, type PackInput, type PackOutput } from "./contract.ts";
 import { boundsOf, buildFrame, now, outerOf, readFrame, rectsOf, viaAxes, type Entry } from "./frame.ts";
 import { packFree } from "./free.ts";
+import { clearMoves, moveCount, MOVES } from "./moves.ts";
 import type { SortOrder } from "./order.ts";
 import { pack } from "./pack.ts";
 import { pushCascade } from "./push.ts";
@@ -59,9 +60,10 @@ function packFixedWidth(id: "rows" | "skyline" | "shelf", input: PackInput, opti
   const start = now();
   const frame = buildFrame(input);
   const rects = rectsOf(frame);
+  clearMoves();
   if (frame.w > 0) pack(rects, outerOf(frame), { strategy: id, sortOrder: options.sortOrder, space: spaceOf(input, frame) });
   const output = readFrame(input, frame, []);
-  return { ...output, trace: [{ id, ms: now() - start, measures: { "pack.overflow": output.overflow.length } }] };
+  return { ...output, trace: [{ id, ms: now() - start, measures: { "pack.overflow": output.overflow.length, [MOVES[id]]: moveCount(MOVES[id]) } }] };
 }
 
 /** This function makes the strategy of one function of `pack`. */
@@ -150,7 +152,7 @@ export const logSweep: SizeSearch = {
       ...output,
       trace: [
         { id: "log-sweep", ms, measures: { "pack.search.widths": result.tried.length, "pack.search.ms": ms } },
-        { id, ms: ms / runs, measures: { "pack.overflow": output.overflow.length } },
+        { id, ms: ms / runs, measures: { "pack.overflow": output.overflow.length, [MOVES[id]]: moveCount(MOVES[id]) } },
       ],
     };
   },
@@ -191,8 +193,9 @@ function pushFixedWidth(input: PackInput, options: PushStrategyOptions, previous
   // The cascade: each item in the order of its rank pushes the others, and then it stays
   const inPlay = frame.entries.filter((e) => !pending.includes(e)).map((e) => e.rect);
   const maxShoves = options.maxShovesPerItem * Math.max(1, inPlay.length);
+  let cascaded = 0;
   for (const e of positioned) {
-    pushCascade(e.rect, inPlay, { gap: 0, maxShoves });
+    cascaded += pushCascade(e.rect, inPlay, { gap: 0, maxShoves }).length;
     e.rect.locked = true;
   }
 
@@ -234,7 +237,7 @@ function pushFixedWidth(input: PackInput, options: PushStrategyOptions, previous
   return {
     ...output,
     trace: [
-      { id: "push", ms: pushMs, measures: { "pack.push.moved": moved.length } },
+      { id: "push", ms: pushMs, measures: { "pack.push.moved": moved.length, [MOVES.push]: cascaded } },
       { id: "skyline", ms: now() - skylineStart, measures: { "pack.push.replaced": pending.length, "pack.overflow": output.overflow.length } },
     ],
   };

package/src/free.ts

@@ -1,3 +1,4 @@
+import { clearMoves } from "./moves.ts";
 import { pack, type PackLayoutOptions } from "./pack.ts";
 import { Rect } from "./rect.ts";
 
@@ -85,6 +86,8 @@ export function packFree<T>(rects: Rect<T>[], outer: Rect<T> = new Rect(), optio
 
   const tried: FreeWidthTry[] = [];
   const run = (width: number): FreeWidthTry => {
+    // The counts of the moves come from the last run: the run with the best width
+    clearMoves();
     Rect.resetPacked(rects);
     const box = new Rect<T>();
     box.position.setTo(outer.position);

package/src/measures.ts

@@ -13,7 +13,7 @@ export type { Direction } from "@mark1russell7/layout-contract";
 export type MeasureFamily = "density" | "aspect" | "order" | "raggedness" | "overflow" | "stability" | "determinism" | "speed";
 
 /** The id of a measure of the packer. The ids are those of `docs/FORMAT.md`, and `highways` uses the same ids. */
-export type MeasureId = "pack.area" | "pack.fill" | "pack.whitespace" | "pack.aspect" | "pack.aspectError" | "pack.order.inversions" | "pack.order.breaks" | "pack.raggedness" | "pack.overflow" | "pack.overflow.rate" | "pack.overflow.area" | "pack.overflow.forced" | "pack.overflow.forcedArea" | "pack.overflow.excess" | "pack.stability.moved" | "pack.stability.mean" | "pack.stability.q95" | "pack.deterministic" | "pack.search.widths" | "pack.search.ms";
+export type MeasureId = "pack.area" | "pack.fill" | "pack.whitespace" | "pack.aspect" | "pack.aspectError" | "pack.order.inversions" | "pack.order.breaks" | "pack.raggedness" | "pack.overflow" | "pack.overflow.rate" | "pack.overflow.area" | "pack.overflow.forced" | "pack.overflow.forcedArea" | "pack.overflow.excess" | "pack.overflow.forcedAreaMin" | "pack.overflow.excessArea" | "pack.stability.moved" | "pack.stability.mean" | "pack.stability.q95" | "pack.deterministic" | "pack.search.widths" | "pack.search.ms";
 
 /**
  * The facts of one measure: its family, its unit, its direction and its range.
@@ -53,6 +53,8 @@ export interface LayoutMeasures {
   "pack.overflow.forced": number;
   "pack.overflow.forcedArea": number;
   "pack.overflow.excess": number;
+  "pack.overflow.forcedAreaMin": number;
+  "pack.overflow.excessArea": number;
   "pack.search.widths": number;
   "pack.search.ms": number;
 }
@@ -111,6 +113,8 @@ export const MEASURE_SPECS: Readonly<Record<MeasureId, MeasureSpec>> = Object.fr
   "pack.overflow.forced": spec("pack.overflow.forced", "overflow", "count", "lower", 0, Infinity, 0),
   "pack.overflow.forcedArea": spec("pack.overflow.forcedArea", "overflow", "share", "lower", 0, 1, 0.005),
   "pack.overflow.excess": spec("pack.overflow.excess", "overflow", "count", "lower", 0, Infinity, 0),
+  "pack.overflow.forcedAreaMin": spec("pack.overflow.forcedAreaMin", "overflow", "share", "lower", 0, 1, 0.005),
+  "pack.overflow.excessArea": spec("pack.overflow.excessArea", "overflow", "share", "lower", 0, 1, 0.005),
   "pack.stability.moved": spec("pack.stability.moved", "stability", "share", "lower", 0, 1, 0.02, { floor: 0, tol: 0.02 }),
   "pack.stability.mean": spec("pack.stability.mean", "stability", "container widths", "lower", 0, Infinity, 0.005, { floor: 0, tol: 0.005 }),
   "pack.stability.q95": spec("pack.stability.q95", "stability", "container widths", "lower", 0, Infinity, 0.01, { floor: 0, tol: 0.01 }),
@@ -205,6 +209,7 @@ function traceSum(output: PackOutput, id: string): number {
  * - The time `pack.search.ms` comes from the trace. It is not part of the determinism rule.
  * - The overflow measures count each id once. `pack.overflow.forced` is the lower bound of `overflowBound`.
  * - `pack.overflow.excess` is the overflow less the forced overflow. A container with no fixed side gives 0 for both.
+ * - `pack.overflow.forcedAreaMin` is a lower bound of the overflow area. `pack.overflow.excessArea` is the overflow area above it.
  *
  * @example
  * ```ts
@@ -257,6 +262,8 @@ export function measure(input: PackInput, output: PackOutput, options: MeasureOp
     if (unplaced.has(item.id)) unplacedArea += a;
   }
   const bound = overflowBound(input);
+  const overflowArea = itemArea > 0 ? unplacedArea / itemArea : 0;
+  const forcedAreaMin = itemArea > 0 ? Math.min(1, bound.area / itemArea) : 0;
 
   return {
     "pack.area": hullArea,
@@ -269,15 +276,29 @@ export function measure(input: PackInput, output: PackOutput, options: MeasureOp
     "pack.raggedness": hull.w > 0 ? spread / hull.w : 0,
     "pack.overflow": unplaced.size,
     "pack.overflow.rate": input.items.length > 0 ? unplaced.size / input.items.length : 0,
-    "pack.overflow.area": itemArea > 0 ? unplacedArea / itemArea : 0,
+    "pack.overflow.area": overflowArea,
     "pack.overflow.forced": bound.forced,
-    "pack.overflow.forcedArea": itemArea > 0 ? Math.min(1, bound.area / itemArea) : 0,
+    "pack.overflow.forcedArea": forcedAreaMin,
     "pack.overflow.excess": Math.max(0, unplaced.size - bound.forced),
+    "pack.overflow.forcedAreaMin": forcedAreaMin,
+    "pack.overflow.excessArea": excessAreaOf(overflowArea, forcedAreaMin),
     "pack.search.widths": traceSum(output, "pack.search.widths"),
     "pack.search.ms": traceSum(output, "pack.search.ms"),
   };
 }
 
+/** The float noise of `pack.overflow.excessArea`. A difference below 0 by this value or less becomes 0. */
+const AREA_NOISE = 1e-9;
+
+/**
+ * This function gives the overflow area above its lower bound. A value from `-AREA_NOISE` to 0 becomes 0. A value below
+ * `-AREA_NOISE` stays, because it shows a bug of the bound or of the packer.
+ */
+function excessAreaOf(overflowArea: number, forcedAreaMin: number): number {
+  const excess = overflowArea - forcedAreaMin;
+  return excess < 0 && excess >= -AREA_NOISE ? 0 : excess;
+}
+
 /**
  * This function gives the stability measures of a change pair: the run on the base input and the run on the changed
  * input. The items match by id. The values are not rounded.

package/src/moves.ts

@@ -0,0 +1,33 @@
+// The counts of the characteristic move of each strategy (roadmap item k59, `docs/BENCH.md`, "Activation"). The
+// packers count their move here, and the adapters write the count in `trace.measures`. The counts do not change a layout.
+// The module is internal: the package root does not export it.
+
+/** The id of the characteristic move of each strategy. The trace of each strategy has its id, also with the count 0. */
+export const MOVES: Readonly<{ rows: "move.gapFill"; shelf: "move.stack"; skyline: "move.lowerWindow"; push: "move.cascade" }> = Object.freeze({
+  /** A rectangle that the gap fill of `packRow` places in a gap of a row: under a shorter neighbor, or at the row break. */
+  rows: "move.gapFill",
+  /** A rectangle that `packShelf` puts on an open shelf with a taller rectangle. The strip above it stays empty. */
+  shelf: "move.stack",
+  /** A rectangle that the skyline puts in a lower window, not in the leftmost window where it fits. */
+  skyline: "move.lowerWindow",
+  /** A rectangle that a push cascade moves. */
+  push: "move.cascade",
+});
+
+const counts = new Map<string, number>();
+
+/** This function adds `n` to the count of a move. */
+export function countMove(id: string, n = 1): void {
+  if (n > 0) counts.set(id, (counts.get(id) ?? 0) + n);
+}
+
+/** This function sets the count of a move to 0. Without an id, it sets each count to 0. */
+export function clearMoves(id?: string): void {
+  if (id === undefined) counts.clear();
+  else counts.delete(id);
+}
+
+/** This function gives the count of a move since the last `clearMoves`. */
+export function moveCount(id: string): number {
+  return counts.get(id) ?? 0;
+}

package/src/pack.ts

@@ -1,3 +1,4 @@
+import { clearMoves, countMove, MOVES } from "./moves.ts";
 import { compareRects, type SortOrder } from "./order.ts";
 import { Rect } from "./rect.ts";
 import { packRowsInSpace, packShelf } from "./shelf.ts";
@@ -25,10 +26,20 @@ export interface PackLayoutOptions extends PackOptions {
   strategy?: "rows" | "skyline" | "shelf";
 }
 
+/** The depth of the calls of `packInto`. Only the outer gap fill counts its rectangles as moves. */
+let fillDepth = 0;
+
 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);
+  fillDepth++;
+  try {
+    pack(unpacked, region, { sortOrder: order });
+  } finally {
+    fillDepth--;
+  }
+  const placed = Rect.packed(unpacked);
+  if (fillDepth === 0) countMove(MOVES.rows, placed.length);
+  for (const r of placed) r.translateBy(offset);
 }
 
 function packRow<T>(rects: Rect<T>[], outer: Rect<T>, order: SortOrder): boolean {
@@ -100,7 +111,8 @@ export function packRows<T>(rects: Rect<T>[], outer: Rect<T>, options: PackOptio
   const space = options.space;
   if (space !== undefined && (!space.plain || rects.some((r) => r.locked))) return packRowsInSpace(rects, outer, order, space);
   for (const r of rects) if (r.locked) r.wasPacked = true;
-  while (!packRow(rects, outer, order));
+  // A row that does not fit grows the height and starts again, thus the gap fills of the try before do not count
+  while (!packRow(rects, outer, order)) if (fillDepth === 0) clearMoves(MOVES.rows);
   return outer;
 }
 

package/src/shelf.ts

@@ -1,3 +1,4 @@
+import { countMove, MOVES } from "./moves.ts";
 import { compareRects, type SortOrder } from "./order.ts";
 import type { Rect } from "./rect.ts";
 import { firstFit, type FreeSpace, type FreeSpan } from "./space.ts";
@@ -111,6 +112,8 @@ export function packShelf<T>(rects: Rect<T>[], outer: Rect<T>, options: ShelfOpt
 
     if (outer.fixedSize && rowTop + h > outer.size.y) continue;
 
+    // The move of a shelf: the rectangle joins an open shelf that a taller rectangle made
+    if (!rowEmpty && rowTop + h < rowBottom) countMove(MOVES.shelf);
     rect.position.set(x + outer.position.x, rowTop + outer.position.y);
     rect.wasPacked = true;
     rowEmpty = false;

package/src/skyline.ts

@@ -1,3 +1,4 @@
+import { countMove, MOVES } from "./moves.ts";
 import { compareRects, type SortOrder } from "./order.ts";
 import type { Rect } from "./rect.ts";
 import type { FreeSpace } from "./space.ts";
@@ -11,6 +12,19 @@ import type { FreeSpace } from "./space.ts";
  * `limit[x, x + rw)`. A second deque keeps that smallest value. No valid window gives the height `Infinity`.
  */
 export function lowestWindow(skyline: ArrayLike<number>, width: number, rw: number, limit?: ArrayLike<number>, rh = 0): { x: number; y: number } {
+  const { x, y } = findWindow(skyline, width, rw, limit, rh);
+  return { x, y };
+}
+
+/** The lowest window of `findWindow`, and `first`: the x of the leftmost valid window, or `-1` */
+interface Window {
+  x: number;
+  y: number;
+  first: number;
+}
+
+/** This function is `lowestWindow`, and it also gives the x of the leftmost valid window. */
+function findWindow(skyline: ArrayLike<number>, width: number, rw: number, limit?: ArrayLike<number>, rh = 0): Window {
   if (limit !== undefined) return lowestLimitedWindow(skyline, limit, width, rw, rh);
   const deque = new Int32Array(width);
   let head = 0;
@@ -29,11 +43,16 @@ export function lowestWindow(skyline: ArrayLike<number>, width: number, rw: numb
       }
     }
   }
-  return { x: bestX, y: bestY };
+  return { x: bestX, y: bestY, first: width >= rw ? 0 : -1 };
+}
+
+/** This function counts the move of the skyline: a window that is lower than the leftmost valid window. */
+function countWindow(w: Window): void {
+  if (Number.isFinite(w.y) && w.first >= 0 && w.x !== w.first) countMove(MOVES.skyline);
 }
 
 /** This function is `lowestWindow` with a limit for each cell. */
-function lowestLimitedWindow(skyline: ArrayLike<number>, limit: ArrayLike<number>, width: number, rw: number, rh: number): { x: number; y: number } {
+function lowestLimitedWindow(skyline: ArrayLike<number>, limit: ArrayLike<number>, width: number, rw: number, rh: number): Window {
   const high = new Int32Array(width);
   const low = new Int32Array(width);
   let hh = 0;
@@ -42,6 +61,7 @@ function lowestLimitedWindow(skyline: ArrayLike<number>, limit: ArrayLike<number
   let lt = 0;
   let bestX = 0;
   let bestY = Infinity;
+  let first = -1;
   for (let i = 0; i < width; i++) {
     while (ht > hh && skyline[high[ht - 1]!]! <= skyline[i]!) ht--;
     high[ht++] = i;
@@ -51,13 +71,15 @@ function lowestLimitedWindow(skyline: ArrayLike<number>, limit: ArrayLike<number
     if (low[lh]! <= i - rw) lh++;
     if (i >= rw - 1) {
       const max = skyline[high[hh]!]!;
-      if (max < bestY && max + rh <= limit[low[lh]!]!) {
+      const valid = max + rh <= limit[low[lh]!]!;
+      if (valid && first < 0) first = i - rw + 1;
+      if (max < bestY && valid) {
         bestY = max;
         bestX = i - rw + 1;
       }
     }
   }
-  return { x: bestX, y: bestY };
+  return { x: bestX, y: bestY, first };
 }
 
 /** The options of `packSkyline` */
@@ -116,8 +138,10 @@ export function packSkyline<T>(rects: Rect<T>[], outer: Rect<T>, options: Skylin
       y = 0;
       for (let i = 0; i < width; i++) if (skyline[i]! > y) y = skyline[i]!;
     } else {
-      ({ x, y } = lowestWindow(skyline, width, rw));
+      const found = findWindow(skyline, width, rw);
+      ({ x, y } = found);
       if (outer.fixedSize && y + rh > outer.size.y) continue;
+      countWindow(found);
     }
 
     rect.position.set(x + outer.position.x, y + outer.position.y);
@@ -179,7 +203,8 @@ function packSkylineInSpace<T>(rects: Rect<T>[], outer: Rect<T>, order: SortOrde
       outer.size.y = Math.max(outer.size.y, y + rh);
       continue;
     }
-    ({ x, y } = lowestWindow(skyline, width, rw, limit, rh));
+    let found = findWindow(skyline, width, rw, limit, rh);
+    ({ x, y } = found);
     let sky: Float64Array = skyline;
     let lim: Float64Array = limit;
     if (!Number.isFinite(y)) {
@@ -189,10 +214,12 @@ function packSkylineInSpace<T>(rects: Rect<T>[], outer: Rect<T>, order: SortOrde
       for (let i = 0; i < width; i++) {
         while (Number.isFinite(lim[i]!) && lim[i]! - sky[i]! < rh && lim[i]! < end) [sky[i], lim[i]] = rangeOf(i, lim[i]!);
       }
-      ({ x, y } = lowestWindow(sky, width, rw, lim, rh));
+      found = findWindow(sky, width, rw, lim, rh);
+      ({ x, y } = found);
       if (!Number.isFinite(y)) continue;
     }
 
+    countWindow(found);
     rect.position.set(x + ox, y + oy);
     rect.wasPacked = true;
     const top = y + rh;