@mark1russell7/packing 0.2.0 → 0.2.1

package/package.json

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

package/src/adapters.ts

@@ -8,6 +8,7 @@ import { pack } from "./pack.ts";
 import { pushCascade } from "./push.ts";
 import { Rect } from "./rect.ts";
 import { packSkyline } from "./skyline.ts";
+import { spaceOf } from "./space.ts";
 import { assertSupported, cellOf, UnsupportedCell, type PackContext, type SizeSearch, type Strategy, type Supports } from "./strategy.ts";
 
 /** The options of the strategies `rows`, `skyline` and `shelf`. */
@@ -26,10 +27,13 @@ export interface PushStrategyOptions {
   maxShovesPerItem: number;
 }
 
-/** The cells of `rows`, `skyline` and `shelf`, without the movement of the obstacles. */
+/**
+ * The cells of `rows`, `skyline` and `shelf`, without the movement of the obstacles. The container layer of `src/space.ts`
+ * gives them each container shape.
+ */
 const LAYOUT_CELLS = {
   containerSize: ["fixed", "freeHeight", "freeWidth", "freeAspect", "freeArea"],
-  containerShape: ["rect"],
+  containerShape: ["rect", "convex", "polygon", "circle", "ellipse", "holes"],
   itemShape: ["rect"],
   rotation: ["none"],
   groups: ["none"],
@@ -55,7 +59,7 @@ function packFixedWidth(id: "rows" | "skyline" | "shelf", input: PackInput, opti
   const start = now();
   const frame = buildFrame(input);
   const rects = rectsOf(frame);
-  if (frame.w > 0) pack(rects, outerOf(frame), { strategy: id, sortOrder: options.sortOrder });
+  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 } }] };
 }
@@ -91,17 +95,18 @@ function layoutStrategy(
 }
 
 /**
- * The strategy `rows` uses `packRows`: a guillotine row packing with a recursive gap fill. It supports no obstacle and
- * no locked item, because `packRows` does not go around them. Turnable items, groups and shapes throw `UnsupportedCell`.
+ * The strategy `rows` uses `packRows`: a guillotine row packing with a recursive gap fill. With obstacles, locked items or a
+ * container shape, the rows go around the holes of the free space and lose the gap fill. Turnable items, groups and item
+ * shapes throw `UnsupportedCell`.
  */
 export const rows: Strategy<LayoutStrategyOptions> = layoutStrategy("rows", "shelf", ["rows-gap-fill", "rows-input"], {
-  obstacleMove: [],
+  obstacleMove: ["fixed"],
   order: ["free", "soft", "hard"],
 });
 
 /**
  * The strategy `skyline` uses `packSkyline`: each item goes to the lowest place where it fits. It packs around the
- * locked items and the fixed obstacles. Turnable items, groups and shapes throw `UnsupportedCell`.
+ * locked items and the fixed obstacles, in each container shape. Turnable items, groups and item shapes throw `UnsupportedCell`.
  */
 export const skyline: Strategy<LayoutStrategyOptions> = layoutStrategy("skyline", "skyline", ["skyline-bl"], {
   obstacleMove: ["fixed"],
@@ -110,7 +115,7 @@ export const skyline: Strategy<LayoutStrategyOptions> = layoutStrategy("skyline"
 
 /**
  * The strategy `shelf` uses `packShelf`: rows filled left to right, around the locked items and the fixed obstacles.
- * With the sort order `input`, the rows keep the rank order. Turnable items, groups and shapes throw `UnsupportedCell`.
+ * With the sort order `input`, the rows keep the rank order. Turnable items, groups and item shapes throw `UnsupportedCell`.
  */
 export const shelf: Strategy<LayoutStrategyOptions> = layoutStrategy("shelf", "shelf", ["shelf-nf", "shelf-nfdh"], {
   obstacleMove: ["fixed"],
@@ -133,6 +138,7 @@ export const logSweep: SizeSearch = {
     const result = packFree(rectsOf(frame), new Rect<number>(), {
       strategy: id,
       sortOrder: o.sortOrder,
+      space: spaceOf(input, frame),
       samples: o.samples,
       aspect: input.container.aspect ?? 1,
       aspectWeight: input.container.aspectWeight ?? 1,

package/src/index.ts

@@ -1,7 +1,8 @@
 export { Vector } from "./vector.ts";
 export { Rect } from "./rect.ts";
 export { pack, packRows, type PackOptions, type PackLayoutOptions } from "./pack.ts";
-export { packSkyline, lowestWindow } from "./skyline.ts";
+export { packSkyline, lowestWindow, type SkylineOptions } from "./skyline.ts";
+export { freeSpace, type FreeSpace, type FreeSpan, type SpaceRect } from "./space.ts";
 export { packShelf, type ShelfOptions } from "./shelf.ts";
 export { packFree, aspectError, type FreeWidthOptions, type FreeWidthResult, type FreeWidthTry } from "./free.ts";
 export { compareRects, SORT_ORDERS, type SortOrder } from "./order.ts";

package/src/pack.ts

@@ -1,13 +1,19 @@
 import { compareRects, type SortOrder } from "./order.ts";
 import { Rect } from "./rect.ts";
-import { packShelf } from "./shelf.ts";
+import { packRowsInSpace, packShelf } from "./shelf.ts";
 import { packSkyline } from "./skyline.ts";
+import type { FreeSpace } from "./space.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 free space of the container: `freeSpace` of the input. With a space that is not plain, each strategy packs into
+   * the outline of the container and around its holes. The rows of `packRows` also go around the locked rectangles.
+   */
+  space?: FreeSpace;
 }
 
 /** The options of `pack` */
@@ -85,9 +91,14 @@ function packRow<T>(rects: Rect<T>[], outer: Rect<T>, order: SortOrder): boolean
  * 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.
+ *
+ * With `options.space`, the rows go around the locked rectangles and the holes of the space, inside its outline. A space
+ * that is plain, with no locked rectangle, gives the rows of 0.1.
  */
 export function packRows<T>(rects: Rect<T>[], outer: Rect<T>, options: PackOptions = {}): Rect<T> {
   const order = options.sortOrder ?? "height-desc";
+  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));
   return outer;

package/src/shelf.ts

@@ -1,10 +1,16 @@
 import { compareRects, type SortOrder } from "./order.ts";
 import type { Rect } from "./rect.ts";
+import { firstFit, type FreeSpace, type FreeSpan } from "./space.ts";
 
 /** The options of `packShelf` */
 export interface ShelfOptions {
   /** The order of the rectangles before the packing. The default is `height-desc`. */
   sortOrder?: SortOrder;
+  /**
+   * The free space of the container: `freeSpace` of the input. Without it, or when it is plain, the packer uses only the
+   * outer rectangle and the locked rectangles.
+   */
+  space?: FreeSpace;
 }
 
 /** An obstacle in the coordinates of the outer rectangle */
@@ -52,8 +58,10 @@ function nextTop(obstacles: readonly Box[], top: number, bottom: number): number
  * - A rectangle wider than the outer rectangle goes on its own row, at the left edge, and overflows.
  * - It does not change the width. Without `fixedSize`, the height grows to the content. With `fixedSize`, a
  *   rectangle that does not fit is not packed: its `wasPacked` stays `false`.
+ * - With a space that is not plain, `packRowsInSpace` packs the rows into the outline of the space and around its holes.
  */
 export function packShelf<T>(rects: Rect<T>[], outer: Rect<T>, options: ShelfOptions = {}): Rect<T> {
+  if (options.space !== undefined && !options.space.plain) return packRowsInSpace(rects, outer, options.sortOrder ?? "height-desc", options.space);
   const width = outer.size.x;
   const obstacles: Box[] = [];
   let contentBottom = 0;
@@ -119,3 +127,102 @@ export function packShelf<T>(rects: Rect<T>[], outer: Rect<T>, options: ShelfOpt
   if (!outer.fixedSize) outer.size.y = Math.max(outer.size.y, contentBottom);
   return outer;
 }
+
+/**
+ * This function gives the first x from `start` where a rectangle of width `w` fits. There, it crosses no locked rectangle,
+ * and it is in a free span of its band. It takes `firstFreeX` and `firstFit` in turn until they agree. It gives `Infinity` when no x fits.
+ */
+function placeInBand(obstacles: readonly Box[], spans: readonly FreeSpan[], start: number, w: number, top: number, bottom: number): number {
+  let x = start;
+  for (;;) {
+    const free = firstFreeX(obstacles, x, w, top, bottom);
+    const fit = firstFit(spans, free, w);
+    if (fit === free || !Number.isFinite(fit)) return fit;
+    x = fit;
+  }
+}
+
+/**
+ * This function packs rectangles into rows inside a free space. `packShelf` and `packRows` use it when the space is not
+ * plain. It sets the position of each rectangle and gives the outer rectangle.
+ *
+ * - A rectangle goes to the first x from the row cursor where it fits in the space and crosses no locked rectangle.
+ * - When it does not fit, a new row starts under the current row. An empty row steps down to `nextY` of the space.
+ * - When the steps of an empty row find no place, the row goes back to its last top edge. Later rectangles can use it.
+ * - A rectangle wider than the outer rectangle overflows. Without `fixedSize`, it goes on its own row at the left edge.
+ */
+export function packRowsInSpace<T>(rects: Rect<T>[], outer: Rect<T>, order: SortOrder, space: FreeSpace): Rect<T> {
+  const width = outer.size.x;
+  const ox = outer.position.x;
+  const oy = outer.position.y;
+  const limit = outer.fixedSize ? outer.size.y : Infinity;
+  const obstacles: Box[] = [];
+  let contentBottom = 0;
+  for (const rect of rects) {
+    if (!rect.locked) continue;
+    rect.wasPacked = true;
+    const left = rect.position.x - ox;
+    const top = rect.position.y - oy;
+    obstacles.push({ left, top, right: left + rect.size.x, bottom: top + rect.size.y });
+    contentBottom = Math.max(contentBottom, top + rect.size.y);
+  }
+  // The x in the row, in the coordinates of the outer rectangle, or Infinity
+  const place = (start: number, w: number, top: number, h: number): number => {
+    const spans = space.band(top + oy, top + h + oy).map((s) => ({ start: s.start - ox, end: s.end - ox }));
+    return placeInBand(obstacles, spans, start, w, top, top + h);
+  };
+
+  let rowTop = 0;
+  let rowBottom = 0;
+  let cursor = 0;
+  let rowEmpty = true;
+  for (const rect of rects.toSorted(compareRects(order))) {
+    if (rect.wasPacked) continue;
+    const w = rect.size.x;
+    const h = rect.size.y;
+    if (!(w > 0 && h > 0)) continue;
+    if (w > width) {
+      if (outer.fixedSize) continue;
+      const top = rowEmpty ? rowTop : rowBottom;
+      rect.position.set(ox, top + oy);
+      rect.wasPacked = true;
+      rowTop = top + h;
+      rowBottom = rowTop;
+      cursor = 0;
+      rowEmpty = true;
+      contentBottom = Math.max(contentBottom, top + h);
+      continue;
+    }
+
+    let x = place(cursor, w, rowTop, h);
+    if (!(x + w <= width) && !rowEmpty) {
+      rowTop = rowBottom;
+      cursor = 0;
+      rowEmpty = true;
+      x = place(0, w, rowTop, h);
+    }
+    // The steps of an empty row. They stay only when the rectangle finds a place.
+    let top = rowTop;
+    while (!(x + w <= width) && top + h <= limit) {
+      const next = Math.min(space.nextY(top + oy, top + h + oy, w) - oy, nextTop(obstacles, top, top + h));
+      if (!Number.isFinite(next)) break;
+      top = next;
+      x = place(0, w, top, h);
+    }
+    if (!(x + w <= width) || top + h > limit) continue;
+    if (top !== rowTop) {
+      rowTop = top;
+      rowBottom = top;
+    }
+
+    rect.position.set(x + ox, rowTop + oy);
+    rect.wasPacked = true;
+    rowEmpty = false;
+    cursor = x + w;
+    rowBottom = Math.max(rowBottom, rowTop + h);
+    contentBottom = Math.max(contentBottom, rowTop + h);
+  }
+
+  if (!outer.fixedSize) outer.size.y = Math.max(outer.size.y, contentBottom);
+  return outer;
+}

package/src/skyline.ts

@@ -1,12 +1,17 @@
 import { compareRects, type SortOrder } from "./order.ts";
 import type { Rect } from "./rect.ts";
+import type { FreeSpace } from "./space.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.
+ *
+ * With `limit`, a window is valid only when its height plus `rh` is not more than the smallest value of
+ * `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): { x: number; y: number } {
+export function lowestWindow(skyline: ArrayLike<number>, width: number, rw: number, limit?: ArrayLike<number>, rh = 0): { x: number; y: number } {
+  if (limit !== undefined) return lowestLimitedWindow(skyline, limit, width, rw, rh);
   const deque = new Int32Array(width);
   let head = 0;
   let tail = 0;
@@ -27,6 +32,45 @@ export function lowestWindow(skyline: ArrayLike<number>, width: number, rw: numb
   return { x: bestX, y: bestY };
 }
 
+/** 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 } {
+  const high = new Int32Array(width);
+  const low = new Int32Array(width);
+  let hh = 0;
+  let ht = 0;
+  let lh = 0;
+  let lt = 0;
+  let bestX = 0;
+  let bestY = Infinity;
+  for (let i = 0; i < width; i++) {
+    while (ht > hh && skyline[high[ht - 1]!]! <= skyline[i]!) ht--;
+    high[ht++] = i;
+    if (high[hh]! <= i - rw) hh++;
+    while (lt > lh && limit[low[lt - 1]!]! >= limit[i]!) lt--;
+    low[lt++] = i;
+    if (low[lh]! <= i - rw) lh++;
+    if (i >= rw - 1) {
+      const max = skyline[high[hh]!]!;
+      if (max < bestY && max + rh <= limit[low[lh]!]!) {
+        bestY = max;
+        bestX = i - rw + 1;
+      }
+    }
+  }
+  return { x: bestX, y: bestY };
+}
+
+/** The options of `packSkyline` */
+export interface SkylineOptions {
+  /** The order of the rectangles before the packing. The default is `height-desc`. */
+  sortOrder?: SortOrder;
+  /**
+   * The free space of the container: `freeSpace` of the input. Without it, or when it is plain, the skyline uses only the
+   * outer rectangle and the locked rectangles.
+   */
+  space?: FreeSpace;
+}
+
 /**
  * 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.
@@ -38,8 +82,11 @@ export function lowestWindow(skyline: ArrayLike<number>, width: number, rw: numb
  * - 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.
+ * - With a space that is not plain, each cell gets its start and its limit from `column` of the space. The space holds
+ *   the obstacles and the locked items, thus the locked rectangles only keep their positions.
  */
-export function packSkyline<T>(rects: Rect<T>[], outer: Rect<T>, options: { sortOrder?: SortOrder } = {}): Rect<T> {
+export function packSkyline<T>(rects: Rect<T>[], outer: Rect<T>, options: SkylineOptions = {}): Rect<T> {
+  if (options.space !== undefined && !options.space.plain) return packSkylineInSpace(rects, outer, options.sortOrder ?? "height-desc", options.space);
   // 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;
@@ -81,3 +128,79 @@ export function packSkyline<T>(rects: Rect<T>[], outer: Rect<T>, options: { sort
   }
   return outer;
 }
+
+/**
+ * This function packs rectangles with a skyline in a free space. Each cell has a free range: the skyline is its start,
+ * and `limit` is its end. A cell with less room than the lowest rectangle left goes to its next free range.
+ */
+function packSkylineInSpace<T>(rects: Rect<T>[], outer: Rect<T>, order: SortOrder, space: FreeSpace): Rect<T> {
+  const width = Math.floor(outer.size.x);
+  if (width <= 0) return outer;
+  const ox = outer.position.x;
+  const oy = outer.position.y;
+  const end = outer.fixedSize ? outer.size.y : Infinity;
+  for (const rect of rects) if (rect.locked) rect.wasPacked = true;
+
+  // The free range of a cell from a y, in the coordinates of the outer rectangle
+  const rangeOf = (i: number, from: number): [number, number] => {
+    const r = space.column(ox + i, ox + i + 1, from + oy);
+    if (r === undefined) return [Infinity, -Infinity];
+    return [r.start - oy, Math.min(r.end - oy, end)];
+  };
+  const skyline = new Float64Array(width);
+  const limit = new Float64Array(width);
+  for (let i = 0; i < width; i++) [skyline[i], limit[i]] = rangeOf(i, 0);
+
+  const sorted = rects.toSorted(compareRects(order)).filter((r) => !r.wasPacked && Math.ceil(r.size.x) > 0 && r.size.y > 0);
+  // The lowest height of the rectangles from each index of the sorted list to its end
+  const lowest = new Float64Array(sorted.length + 1).fill(Infinity);
+  for (let k = sorted.length - 1; k >= 0; k--) lowest[k] = Math.min(lowest[k + 1]!, sorted[k]!.size.y);
+  const advance = (k: number): void => {
+    const need = lowest[k]!;
+    if (!Number.isFinite(need)) return;
+    for (let i = 0; i < width; i++) {
+      while (Number.isFinite(limit[i]!) && limit[i]! - skyline[i]! < need && limit[i]! < end) [skyline[i], limit[i]] = rangeOf(i, limit[i]!);
+    }
+  };
+
+  for (const [k, rect] of sorted.entries()) {
+    advance(k);
+    const rw = Math.ceil(rect.size.x);
+    const rh = rect.size.y;
+    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 (Number.isFinite(skyline[i]!) && skyline[i]! > y) y = skyline[i]!;
+      rect.position.set(x + ox, y + oy);
+      rect.wasPacked = true;
+      outer.size.y = Math.max(outer.size.y, y + rh);
+      continue;
+    }
+    ({ x, y } = lowestWindow(skyline, width, rw, limit, rh));
+    let sky: Float64Array = skyline;
+    let lim: Float64Array = limit;
+    if (!Number.isFinite(y)) {
+      // The second try: each cell goes to its first free range with room for this rectangle
+      sky = skyline.slice();
+      lim = limit.slice();
+      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));
+      if (!Number.isFinite(y)) continue;
+    }
+
+    rect.position.set(x + ox, y + oy);
+    rect.wasPacked = true;
+    const top = y + rh;
+    for (let i = x; i < x + rw; i++) {
+      skyline[i] = top;
+      limit[i] = lim[i]!;
+    }
+    if (!outer.fixedSize) outer.size.y = Math.max(outer.size.y, top);
+  }
+  return outer;
+}