@mark1russell7/packing 0.1.5 → 0.1.7

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@mark1russell7/packing",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Rectangle packing: shelf, guillotine and skyline strategies, push cascades and measures of a layout.",
   "keywords": [
     "rectangle-packing",
@@ -50,6 +50,7 @@
   },
   "devDependencies": {
     "@mark1russell7/cue": "^1.0.2",
+    "@mark1russell7/layout-contract": "github:mark1russell7/layout-contract#710ec519027dbc122d111cc5e76a1c18877f4237&path:packages/layout-contract",
     "@types/node": "^26.6.4",
     "tsdown": "^0.23.1",
     "typescript": "^7.0.2",

package/src/check.ts

@@ -26,11 +26,16 @@ function overlap(a: Box, b: Box, tolerance: number): boolean {
  * This function counts the breaks of the 4 hard rules of the packer for an output.
  *
  * - `no-overlap`: each pair of items with their margins, and each pair of an item and an obstacle, that overlap by more than `tolerance.overlap`.
- * - `in-container`: each item with its margin that goes out of a fixed side by more than `tolerance.overlap`.
- * - `locked-kept`: each locked item that moved by more than `RECORD_EPS`, or that has no position.
- * - `complete`: each item with no position that is not in the overflow.
+ * - `in-container`: each item with its margin that goes out of a fixed side by more than `tolerance.overlap`. The inset of
+ *   the container makes each fixed side smaller (decision 3 of `docs/PACKER.md`).
+ * - `locked-kept`: each locked item that moved by more than `RECORD_EPS`, or that has no placement.
+ * - `complete`: each item with no placement that is not in the overflow. A locked item breaks `locked-kept` in its place.
  *
- * The rules read a shape of the container or of an obstacle as its bounding box. The result has no tolerance in it.
+ * A locked item with no placement stays at its input position for `no-overlap` and `in-container`. A locked item with no
+ * `x` or no `y` in the input is not locked for these rules.
+ *
+ * The rules read a shape of the container, of an obstacle or of an item as its bounding box (decision 5). The bounding box
+ * of an item shape is relative to the position of the item. The result has no tolerance in it.
  */
 export function checkHard(input: PackInput, output: PackOutput, tolerance: Pick<Tolerance, "overlap"> = DEFAULT_TOLERANCE): HardBreaks {
   const tol = tolerance.overlap;
@@ -41,18 +46,25 @@ export function checkHard(input: PackInput, output: PackOutput, tolerance: Pick<
 
   const boxes: Box[] = [];
   for (const item of input.items) {
-    const p = placements.get(item.id);
+    const lockedAt = item.locked === true && item.x !== undefined && item.y !== undefined ? { x: item.x, y: item.y } : undefined;
+    let p: Pick<PackOutput["placements"][number], "x" | "y" | "turn"> | undefined = placements.get(item.id);
     if (p === undefined) {
-      if (item.locked === true && item.x !== undefined && item.y !== undefined) breaks["locked-kept"] += 1;
-      if (!overflow.has(item.id)) breaks.complete += 1;
-      continue;
-    }
-    if (item.locked === true && item.x !== undefined && item.y !== undefined) {
-      if (Math.abs(p.x - item.x) > RECORD_EPS || Math.abs(p.y - item.y) > RECORD_EPS) breaks["locked-kept"] += 1;
+      if (lockedAt === undefined) {
+        if (!overflow.has(item.id)) breaks.complete += 1;
+        continue;
+      }
+      // A locked item with no placement breaks locked-kept, and it stays at its input position for the other rules
+      breaks["locked-kept"] += 1;
+      p = lockedAt;
+    } else if (lockedAt !== undefined) {
+      if (Math.abs(p.x - lockedAt.x) > RECORD_EPS || Math.abs(p.y - lockedAt.y) > RECORD_EPS) breaks["locked-kept"] += 1;
     }
     const placed: Item = p.turn === 90 ? turnItem(item) : item;
     const m = marginOf(placed);
-    boxes.push({ l: p.x - m.left, t: p.y - m.top, r: p.x + placed.w + m.right, b: p.y + placed.h + m.bottom });
+    const area = placed.shape === undefined ? { x: 0, y: 0, w: placed.w, h: placed.h } : boundsOf(placed.shape);
+    const l = p.x + area.x;
+    const t = p.y + area.y;
+    boxes.push({ l: l - m.left, t: t - m.top, r: l + area.w + m.right, b: t + area.h + m.bottom });
   }
 
   const moved = new Map(output.moved.map((m) => [m.id, m]));
@@ -73,11 +85,12 @@ export function checkHard(input: PackInput, output: PackOutput, tolerance: Pick<
   const y = shape?.y ?? 0;
   const w = shape?.w ?? container.w ?? Infinity;
   const h = shape?.h ?? container.h ?? Infinity;
+  const inset = container.inset ?? 0;
   const fixedW = container.fixed === "size" || container.fixed === "width";
   const fixedH = container.fixed === "size" || container.fixed === "height";
   for (const box of boxes) {
-    const outX = fixedW && (box.l < x - tol || box.r > x + w + tol);
-    const outY = fixedH && (box.t < y - tol || box.b > y + h + tol);
+    const outX = fixedW && (box.l < x + inset - tol || box.r > x + w - inset + tol);
+    const outY = fixedH && (box.t < y + inset - tol || box.b > y + h - inset + tol);
     if (outX || outY) breaks["in-container"] += 1;
   }
   return breaks;

package/src/contract.ts

@@ -72,6 +72,8 @@ export interface Item {
   margin?: number | Margin;
   /** The ports. The packer keeps them, and turns them with the item. */
   ports?: Port[];
+  /** The free data of the item. The packer does not read it, and the turn and the converters keep it. */
+  data?: Readonly<Record<string, unknown>>;
 }
 
 /** The input of a packing: a `layout-input/1` file without `edges`, with `items` for `boxes`. */

package/src/layout-input.ts

@@ -11,6 +11,8 @@ export interface Edge {
   target: string;
   sourcePort?: string;
   targetPort?: string;
+  /** The free data of the edge. The packer does not read it. */
+  data?: Readonly<Record<string, unknown>>;
 }
 
 /** The parameters of a generator: a name and a string or a number for each parameter. */

package/src/measures.ts

@@ -23,6 +23,20 @@ export interface MeasureSpec {
   min: number;
   /** The highest value. The value `Infinity` tells that the measure has no upper limit. */
   max: number;
+  /**
+   * The floor is the best value of a guard measure. The floor rule of `docs/PROMOTION.md` of `highways` reads it. Each
+   * guard of the packer has the floor 0. A measure without a floor has no floor rule.
+   */
+  floor?: number;
+  /**
+   * The tolerance is the absolute tolerance at the floor. A candidate within the tolerance ties with a default at the floor.
+   *
+   * - `pack.order.inversions` and `pack.overflow` have the tolerance 0. Thus each new inversion and each new unplaced item is a loss.
+   * - `pack.aspectError` has 0.01, approximately 1% of the aspect. An exact tiling gives the default an error of 0.
+   * - `pack.stability.mean` has 0.005 container widths, and `pack.stability.q95` has 0.01. The default often moves no item.
+   * - `pack.stability.moved` has 0.02: 2% of the items that stay. On a small change, the default often moves no item.
+   */
+  tol?: number;
 }
 
 /** The measures of one layout, by id. `measure` gives them. The values are not rounded. */
@@ -56,29 +70,33 @@ export interface MeasureOptions {
   rowTolerance?: number;
 }
 
-const spec = (id: MeasureId, family: MeasureFamily, unit: string, direction: Direction, min: number, max: number): MeasureSpec => ({
-  id,
-  family,
-  unit,
-  direction,
-  min,
-  max,
-});
+const spec = (
+  id: MeasureId,
+  family: MeasureFamily,
+  unit: string,
+  direction: Direction,
+  min: number,
+  max: number,
+  guard?: { floor: number; tol: number },
+): MeasureSpec => ({ id, family, unit, direction, min, max, ...guard });
 
-/** The facts of each measure, by id. `docs/MEASURES.md` gives the full definitions. */
+/**
+ * The facts of each measure, by id. `docs/MEASURES.md` gives the full definitions. This record is the source of the floor
+ * and the tolerance of each guard of the packer.
+ */
 export const MEASURE_SPECS: Readonly<Record<MeasureId, MeasureSpec>> = Object.freeze({
   "pack.area": spec("pack.area", "density", "square units", "lower", 0, Infinity),
   "pack.fill": spec("pack.fill", "density", "share", "higher", 0, 1),
   "pack.whitespace": spec("pack.whitespace", "density", "share", "lower", 0, 1),
   "pack.aspect": spec("pack.aspect", "aspect", "ratio", "lower", 1, Infinity),
-  "pack.aspectError": spec("pack.aspectError", "aspect", "natural log", "lower", 0, Infinity),
-  "pack.order.inversions": spec("pack.order.inversions", "order", "share", "lower", 0, 1),
+  "pack.aspectError": spec("pack.aspectError", "aspect", "natural log", "lower", 0, Infinity, { floor: 0, tol: 0.01 }),
+  "pack.order.inversions": spec("pack.order.inversions", "order", "share", "lower", 0, 1, { floor: 0, tol: 0 }),
   "pack.order.breaks": spec("pack.order.breaks", "order", "count", "lower", 0, Infinity),
   "pack.raggedness": spec("pack.raggedness", "raggedness", "share", "lower", 0, 1),
-  "pack.overflow": spec("pack.overflow", "overflow", "count", "lower", 0, Infinity),
-  "pack.stability.moved": spec("pack.stability.moved", "stability", "share", "lower", 0, 1),
-  "pack.stability.mean": spec("pack.stability.mean", "stability", "container widths", "lower", 0, Infinity),
-  "pack.stability.q95": spec("pack.stability.q95", "stability", "container widths", "lower", 0, Infinity),
+  "pack.overflow": spec("pack.overflow", "overflow", "count", "lower", 0, Infinity, { floor: 0, tol: 0 }),
+  "pack.stability.moved": spec("pack.stability.moved", "stability", "share", "lower", 0, 1, { floor: 0, tol: 0.02 }),
+  "pack.stability.mean": spec("pack.stability.mean", "stability", "container widths", "lower", 0, Infinity, { floor: 0, tol: 0.005 }),
+  "pack.stability.q95": spec("pack.stability.q95", "stability", "container widths", "lower", 0, Infinity, { floor: 0, tol: 0.01 }),
   "pack.deterministic": spec("pack.deterministic", "determinism", "boolean", "higher", 0, 1),
   "pack.search.widths": spec("pack.search.widths", "speed", "count", "lower", 0, Infinity),
   "pack.search.ms": spec("pack.search.ms", "speed", "milliseconds", "lower", 0, Infinity),

package/src/strategy.ts

@@ -1,7 +1,10 @@
 import type { Container, PackInput, PackOutput, Region } from "./contract.ts";
 
-/** For each dimension of the taxonomy, the values that a strategy supports. `docs/research/TAXONOMY.md` gives the values. */
-export interface Supports {
+/**
+ * For each dimension of the taxonomy, the values that a strategy supports. `docs/research/TAXONOMY.md` gives the values.
+ * The type is an alias, not an interface. Thus it fits the record `Supports` of the contract.
+ */
+export type Supports = {
   containerSize: ("fixed" | "freeHeight" | "freeWidth" | "freeAspect" | "freeArea")[];
   containerShape: ("rect" | "convex" | "polygon" | "circle" | "ellipse" | "holes")[];
   /** The movement of the obstacles. An empty list supports only an input with no obstacle and no locked item. */
@@ -11,7 +14,7 @@ export interface Supports {
   order: ("free" | "soft" | "hard")[];
   groups: ("none" | "flat" | "nested")[];
   mode: ("offline" | "online" | "incremental")[];
-}
+};
 
 /** A dimension of `Supports`. */
 export type Dimension = keyof Supports;