@mark1russell7/packing 0.2.0 → 0.2.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@mark1russell7/packing",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Rectangle packing: shelf, guillotine and skyline strategies, push cascades and measures of a layout.",
   "keywords": [
     "rectangle-packing",
@@ -49,7 +49,7 @@
     "node": ">=22.12"
   },
   "dependencies": {
-    "@mark1russell7/layout-contract": "^0.2.1"
+    "@mark1russell7/layout-contract": "^0.2.4"
   },
   "devDependencies": {
     "@mark1russell7/cue": "^1.0.2",

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/check.ts

@@ -1,7 +1,7 @@
-import { boundsOf, regionHitsRect, translate, type PackHard, type Rect, type Region } from "@mark1russell7/layout-contract";
+import { boundsOf, rectInRegion, regionHitsRect, translate, type ContainerTest, type PackHard, type Rect, type Region } from "@mark1russell7/layout-contract";
 import { DEFAULT_TOLERANCE, marginOf, RECORD_EPS, turnItem, type Item, type PackInput, type PackOutput, type Placement, type Tolerance } from "./contract.ts";
 
-export type { PackHard } from "@mark1russell7/layout-contract";
+export type { ContainerTest, PackHard } from "@mark1russell7/layout-contract";
 
 /** A box with its margin: the left, top, right and bottom edges. */
 interface Box {
@@ -36,8 +36,17 @@ function inner(box: Box, tolerance: number): Rect {
  * The test of an obstacle is exact: a circle, an ellipse and a polygon with holes count only their insides, as in `packHard`.
  * The rules read a shape of the container 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.
+ *
+ * With `options.exactContainer`, a shaped container with the size `fixed` also uses its true outline for `in-container`.
+ * A box then counts when `rectInRegion` of the contract tells that it is not in the shape, as in `packHard`.
+ * For that test, the box grows by the inset and becomes smaller by `tolerance.overlap` on each side. The default is `false`.
  */
-export function checkHard(input: PackInput, output: PackOutput, tolerance: Pick<Tolerance, "overlap"> = DEFAULT_TOLERANCE): PackHard {
+export function checkHard(
+  input: PackInput,
+  output: PackOutput,
+  tolerance: Pick<Tolerance, "overlap"> = DEFAULT_TOLERANCE,
+  options: ContainerTest = {},
+): PackHard {
   const tol = tolerance.overlap;
   const placements = new Map<string, Placement>();
   for (const p of output.placements) if (!placements.has(p.id)) placements.set(p.id, p);
@@ -94,11 +103,13 @@ export function checkHard(input: PackInput, output: PackOutput, tolerance: Pick<
   const inset = container.inset ?? 0;
   const fixedW = container.fixed === "size" || container.fixed === "width";
   const fixedH = container.fixed === "size" || container.fixed === "height";
+  const exact = options.exactContainer === true && container.fixed === "size" ? container.shape : undefined;
   let outside = 0;
   for (const box of boxes) {
     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) outside += 1;
+    else if (exact !== undefined && !rectInRegion(exact, inner({ l: box.l - inset, t: box.t - inset, r: box.r + inset, b: box.b + inset }, tol))) outside += 1;
   }
   return { "no-overlap": overlaps, "in-container": outside, "locked-kept": lockedKept, complete };
 }

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";
@@ -68,7 +69,7 @@ export {
 export { logSweep, push, rows, shelf, skyline, type LayoutStrategyOptions, type PushStrategyOptions } from "./adapters.ts";
 export { fromRects, toRects } from "./convert.ts";
 export { packWith, strategies, strategy } from "./registry.ts";
-export { checkHard, type PackHard } from "./check.ts";
+export { checkHard, type ContainerTest, type PackHard } from "./check.ts";
 export {
   canonicalJson,
   countCell,

package/src/measures.ts

@@ -3,6 +3,7 @@
 import type { MeasureSpec as ContractMeasureSpec, Direction } from "@mark1russell7/layout-contract";
 import { RECORD_EPS, type PackInput, type PackOutput } from "./contract.ts";
 import { aspectError } from "./free.ts";
+import { overflowBound } from "./overflow.ts";
 import { round3 } from "./layout-input.ts";
 
 /** The direction of a measure comes from the contract: `lower` when a lower value is better, `higher` when a higher value is better. */
@@ -12,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.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.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.
@@ -47,6 +48,11 @@ export interface LayoutMeasures {
   "pack.order.breaks": number;
   "pack.raggedness": number;
   "pack.overflow": number;
+  "pack.overflow.rate": number;
+  "pack.overflow.area": number;
+  "pack.overflow.forced": number;
+  "pack.overflow.forcedArea": number;
+  "pack.overflow.excess": number;
   "pack.search.widths": number;
   "pack.search.ms": number;
 }
@@ -74,29 +80,43 @@ const spec = (
   direction: Direction,
   min: number,
   max: number,
+  minEffect: MeasureSpec["minEffect"],
   guard?: { floor: number; tol: number },
-): MeasureSpec => ({ id, family, unit, direction, min, max, ...guard });
+): MeasureSpec => ({ id, family, unit, direction, min, max, ...(minEffect === undefined ? {} : { minEffect }), ...guard });
+
+/** The minimum effect of an area or a ratio of lengths: 1% of the larger value. */
+const REL = Object.freeze({ rel: 0.01 });
 
 /**
  * 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.
+ * and the tolerance of each guard of the packer, and of the minimum effect of each measure.
+ *
+ * - A count and a share of counts have the minimum effect 0. Thus each change of a count is an effect.
+ * - A share of an area from 0 to 1 has 0.005. A guard has its tolerance.
+ * - An area and a ratio of lengths have `{ rel: 0.01 }`: 1% of the larger value.
+ * - The time has no minimum effect, because the times of CI change each time.
  */
 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, { 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, { 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),
+  "pack.area": spec("pack.area", "density", "square units", "lower", 0, Infinity, REL),
+  "pack.fill": spec("pack.fill", "density", "share", "higher", 0, 1, 0.005),
+  "pack.whitespace": spec("pack.whitespace", "density", "share", "lower", 0, 1, 0.005),
+  "pack.aspect": spec("pack.aspect", "aspect", "ratio", "lower", 1, Infinity, REL),
+  "pack.aspectError": spec("pack.aspectError", "aspect", "natural log", "lower", 0, Infinity, 0.01, { floor: 0, tol: 0.01 }),
+  "pack.order.inversions": spec("pack.order.inversions", "order", "share", "lower", 0, 1, 0, { floor: 0, tol: 0 }),
+  "pack.order.breaks": spec("pack.order.breaks", "order", "count", "lower", 0, Infinity, 0),
+  "pack.raggedness": spec("pack.raggedness", "raggedness", "share", "lower", 0, 1, 0.005),
+  "pack.overflow": spec("pack.overflow", "overflow", "count", "lower", 0, Infinity, 0, { floor: 0, tol: 0 }),
+  "pack.overflow.rate": spec("pack.overflow.rate", "overflow", "share", "lower", 0, 1, 0),
+  "pack.overflow.area": spec("pack.overflow.area", "overflow", "share", "lower", 0, 1, 0.005),
+  "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.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 }),
+  "pack.deterministic": spec("pack.deterministic", "determinism", "boolean", "higher", 0, 1, 0),
+  "pack.search.widths": spec("pack.search.widths", "speed", "count", "lower", 0, Infinity, 0),
+  "pack.search.ms": spec("pack.search.ms", "speed", "milliseconds", "lower", 0, Infinity, undefined),
 });
 
 /** A placed box: the rectangle of an item at its position, with its rank. */
@@ -183,6 +203,8 @@ function traceSum(output: PackOutput, id: string): number {
  * - The boxes are the placed items with a width and a height above 0. The hull is the smallest rectangle around them.
  * - An empty layout gives the area 0, the aspect 1 and the aspect error 0. Its fill is 0 and its whitespace is 1.
  * - 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.
  *
  * @example
  * ```ts
@@ -225,6 +247,17 @@ export function measure(input: PackInput, output: PackOutput, options: MeasureOp
   const rights = rowsOf(boxes, tolerance).map((r) => r.right);
   const spread = rights.length > 0 ? Math.max(...rights) - Math.min(...rights) : 0;
 
+  // The overflow: the unplaced items, their area, and the part that no packer can place
+  const unplaced = new Set(output.overflow);
+  let itemArea = 0;
+  let unplacedArea = 0;
+  for (const item of input.items) {
+    const a = Math.max(0, item.w) * Math.max(0, item.h);
+    itemArea += a;
+    if (unplaced.has(item.id)) unplacedArea += a;
+  }
+  const bound = overflowBound(input);
+
   return {
     "pack.area": hullArea,
     "pack.fill": fill,
@@ -234,7 +267,12 @@ export function measure(input: PackInput, output: PackOutput, options: MeasureOp
     "pack.order.inversions": pairs > 0 ? inversions / pairs : 0,
     "pack.order.breaks": breaks,
     "pack.raggedness": hull.w > 0 ? spread / hull.w : 0,
-    "pack.overflow": new Set(output.overflow).size,
+    "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.forced": bound.forced,
+    "pack.overflow.forcedArea": itemArea > 0 ? Math.min(1, bound.area / itemArea) : 0,
+    "pack.overflow.excess": Math.max(0, unplaced.size - bound.forced),
     "pack.search.widths": traceSum(output, "pack.search.widths"),
     "pack.search.ms": traceSum(output, "pack.search.ms"),
   };

package/src/overflow.ts

@@ -0,0 +1,332 @@
+// The forced overflow of roadmap item k59 (docs/MEASURES.md, "Overflow"): a lower bound of the count of items that no
+// packer can place in a fixed container. `measure` uses it for `pack.overflow.forced` and `pack.overflow.forcedArea`.
+
+import { boundsOf } from "@mark1russell7/layout-contract";
+import { DEFAULT_TOLERANCE, type Item, type PackInput, type Region } from "./contract.ts";
+
+/** A rectangle: its top-left corner and its size. */
+interface Box {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+/** A ring of a polygon. */
+type Ring = readonly (readonly [number, number])[];
+
+/** A region that the items cannot use: a fixed obstacle or a locked item. */
+interface Blocked {
+  region: Region;
+  box: Box;
+}
+
+/** The lower bound of the overflow of one input. `overflowBound` gives it. */
+export interface OverflowBound {
+  /** The count of items that no packer can place. It is a lower bound. */
+  readonly forced: number;
+  /** The area that no packer can place. It is a lower bound of the area of the unplaced items. */
+  readonly area: number;
+  /** The upper bound of the free area of a fixed container, or `Infinity` when a side is free. */
+  readonly free: number;
+}
+
+/** This function gives the area of a ring by the shoelace formula. The direction of the ring does not count. */
+function ringArea(ring: Ring): number {
+  let sum = 0;
+  for (let i = 0; i < ring.length; i++) {
+    const a = ring[i]!;
+    const b = ring[(i + 1) % ring.length]!;
+    sum += a[0] * b[1] - b[0] * a[1];
+  }
+  return Math.abs(sum) / 2;
+}
+
+/**
+ * This function gives the area of a region that an item cannot use. A polygon loses the area of its holes. Thus a hole
+ * that is out of the polygon makes the area too small, and the free area stays an upper bound.
+ */
+function blockedArea(region: Region): number {
+  switch (region.kind) {
+    case "rect":
+      return Math.max(0, region.w) * Math.max(0, region.h);
+    case "circle":
+      return Math.PI * region.r ** 2;
+    case "ellipse":
+      return Math.PI * region.rx * region.ry;
+    case "polygon": {
+      let area = ringArea(region.points);
+      for (const hole of region.holes ?? []) area -= ringArea(hole);
+      return Math.max(0, area);
+    }
+  }
+}
+
+/** This function tells if the insides of two rectangles have a common point. Two rectangles with a common edge do not. */
+function boxesOverlap(a: Box, b: Box): boolean {
+  return Math.min(a.x + a.w, b.x + b.w) - Math.max(a.x, b.x) > 0 && Math.min(a.y + a.h, b.y + b.h) - Math.max(a.y, b.y) > 0;
+}
+
+/** This function tells if rectangle `a` is in rectangle `b`. */
+function boxIn(a: Box, b: Box): boolean {
+  return a.x >= b.x && a.y >= b.y && a.x + a.w <= b.x + b.w && a.y + a.h <= b.y + b.h;
+}
+
+/** This function gives the rectangle made smaller by `d` on each side. */
+function shrink(b: Box, d: number): Box {
+  return { x: b.x + d, y: b.y + d, w: Math.max(0, b.w - 2 * d), h: Math.max(0, b.h - 2 * d) };
+}
+
+/** This function tells if a point is in a ring, by the even-odd rule. */
+function pointInRing(x: number, y: number, ring: Ring): boolean {
+  let inside = false;
+  for (let i = 0, j = ring.length - 1; i < ring.length; j = i++) {
+    const [xi, yi] = ring[i]!;
+    const [xj, yj] = ring[j]!;
+    if (yi > y !== yj > y && x < ((xj - xi) * (y - yi)) / (yj - yi) + xi) inside = !inside;
+  }
+  return inside;
+}
+
+/** This function tells if a segment has a part of a length above 0 in the open rectangle. The Liang-Barsky clip gives it. */
+function segmentHitsBox(ax: number, ay: number, bx: number, by: number, r: Box): boolean {
+  let t0 = 0;
+  let t1 = 1;
+  const dx = bx - ax;
+  const dy = by - ay;
+  const clip = (p: number, q: number): boolean => {
+    if (p === 0) return q > 0;
+    const t = q / p;
+    if (p < 0) {
+      if (t > t1) return false;
+      if (t > t0) t0 = t;
+    } else {
+      if (t < t0) return false;
+      if (t < t1) t1 = t;
+    }
+    return true;
+  };
+  return clip(-dx, ax - r.x) && clip(dx, r.x + r.w - ax) && clip(-dy, ay - r.y) && clip(dy, r.y + r.h - ay) && t1 > t0;
+}
+
+/**
+ * This function tells if a rectangle is in a polygon with holes. No edge of a ring crosses the inside of the rectangle.
+ * No vertex is in it, and its center is in the polygon by the even-odd rule.
+ */
+function boxInPolygon(b: Box, rings: readonly Ring[]): boolean {
+  for (const ring of rings) {
+    for (let i = 0; i < ring.length; i++) {
+      const p = ring[i]!;
+      const q = ring[(i + 1) % ring.length]!;
+      if (p[0] > b.x && p[0] < b.x + b.w && p[1] > b.y && p[1] < b.y + b.h) return false;
+      if (segmentHitsBox(p[0], p[1], q[0], q[1], b)) return false;
+    }
+  }
+  const cx = b.x + b.w / 2;
+  const cy = b.y + b.h / 2;
+  let inside = false;
+  for (const ring of rings) if (pointInRing(cx, cy, ring)) inside = !inside;
+  return inside;
+}
+
+/** This function tells if a rectangle is in a region of a container. A rectangle with no size is in no region. */
+function boxInShape(b: Box, shape: Region): boolean {
+  if (!(b.w > 0 && b.h > 0)) return false;
+  // A small shrink keeps a rectangle on the outline in the shape
+  const s = shrink(b, 1e-9 * Math.max(1, b.w, b.h));
+  switch (shape.kind) {
+    case "rect":
+      return boxIn(b, { x: shape.x, y: shape.y, w: shape.w, h: shape.h });
+    case "circle":
+    case "ellipse": {
+      const rx = shape.kind === "circle" ? shape.r : shape.rx;
+      const ry = shape.kind === "circle" ? shape.r : shape.ry;
+      const inside = (x: number, y: number): boolean => ((x - shape.cx) / rx) ** 2 + ((y - shape.cy) / ry) ** 2 <= 1;
+      return inside(s.x, s.y) && inside(s.x + s.w, s.y) && inside(s.x, s.y + s.h) && inside(s.x + s.w, s.y + s.h);
+    }
+    case "polygon":
+      return boxInPolygon(s, [shape.points, ...(shape.holes ?? [])]);
+  }
+}
+
+/**
+ * This function gives the area of a container shape. A hole counts only when its bounding box is in the outer ring.
+ * Also, that box has no common point with the box of a hole before it. Thus the area is not too small.
+ */
+function shapeArea(shape: Region): number {
+  if (shape.kind !== "polygon") return blockedArea(shape);
+  let area = ringArea(shape.points);
+  const kept: Box[] = [];
+  for (const hole of shape.holes ?? []) {
+    const box = boundsOf({ kind: "polygon", points: hole });
+    if (!boxInPolygon(shrink(box, 1e-9 * Math.max(1, box.w, box.h)), [shape.points])) continue;
+    if (kept.some((k) => boxesOverlap(k, box))) continue;
+    kept.push(box);
+    area -= ringArea(hole);
+  }
+  return Math.max(0, area);
+}
+
+/**
+ * This function gives the area of the union of rectangles, each cut to the rectangle `clip`. A sweep over the x edges
+ * adds the merged y intervals of each slab.
+ */
+function unionArea(boxes: readonly Box[], clip: Box): number {
+  const cut: Box[] = [];
+  for (const b of boxes) {
+    const x0 = Math.max(b.x, clip.x);
+    const y0 = Math.max(b.y, clip.y);
+    const x1 = Math.min(b.x + b.w, clip.x + clip.w);
+    const y1 = Math.min(b.y + b.h, clip.y + clip.h);
+    if (x1 > x0 && y1 > y0) cut.push({ x: x0, y: y0, w: x1 - x0, h: y1 - y0 });
+  }
+  const xs = [...new Set(cut.flatMap((b) => [b.x, b.x + b.w]))].toSorted((a, b) => a - b);
+  let area = 0;
+  for (let i = 0; i + 1 < xs.length; i++) {
+    const left = xs[i]!;
+    const right = xs[i + 1]!;
+    const spans = cut
+      .filter((b) => b.x <= left && b.x + b.w >= right)
+      .map((b) => [b.y, b.y + b.h] as const)
+      .toSorted((p, q) => p[0] - q[0]);
+    let covered = 0;
+    let top = -Infinity;
+    let bottom = -Infinity;
+    for (const [s, e] of spans) {
+      if (s > bottom) {
+        covered += bottom - top > 0 ? bottom - top : 0;
+        top = s;
+        bottom = e;
+      } else bottom = Math.max(bottom, e);
+    }
+    covered += bottom - top > 0 ? bottom - top : 0;
+    area += covered * (right - left);
+  }
+  return area;
+}
+
+/** This function gives the rectangle of the container: the bounding box of its shape, or 0, 0, `w`, `h`. */
+function containerBox(input: PackInput): Box {
+  const { container } = input;
+  if (container.shape !== undefined) return boundsOf(container.shape);
+  return { x: 0, y: 0, w: container.w ?? Infinity, h: container.h ?? Infinity };
+}
+
+/** This function tells if an item is locked at a position. Such an item is not a candidate of the overflow. */
+const lockedAt = (item: Item): boolean => item.locked === true && item.x !== undefined && item.y !== undefined;
+
+/** This function gives the rectangle of an item at its position: the bounding box of its shape, or its size. */
+function itemBox(item: Item): Box {
+  const s = item.shape === undefined ? { x: 0, y: 0, w: item.w, h: item.h } : boundsOf(item.shape);
+  return { x: (item.x ?? 0) + s.x, y: (item.y ?? 0) + s.y, w: s.w, h: s.h };
+}
+
+/** This function gives the smallest area of an item: its rectangle, or the area of its shape when that is smaller. */
+function itemArea(item: Item): number {
+  const rect = Math.max(0, item.w) * Math.max(0, item.h);
+  return item.shape === undefined ? rect : Math.min(rect, blockedArea(item.shape));
+}
+
+/**
+ * This function gives an upper bound of the free area of a container with a fixed size. The bound ignores the gap and
+ * the margins, thus it is not too small.
+ *
+ * - The container area is the inner rectangle (the container less the inset). A shape gives the smaller of that and its exact area.
+ * - A rectangle container loses the exact union of the fixed rectangle obstacles and the locked items in the inner rectangle.
+ * - A shape loses only the regions that are fully in it and in the inner rectangle, with no common point between their boxes.
+ * - An obstacle with `move` can go out of the way. Thus the bound does not subtract it.
+ */
+export function freeAreaBound(input: PackInput): number {
+  const bounds = containerBox(input);
+  const inset = input.container.inset ?? 0;
+  const inner = shrink(bounds, inset);
+  if (!(inner.w > 0 && inner.h > 0)) return 0;
+  const blocked: Blocked[] = [];
+  for (const o of input.obstacles ?? []) if (o.move === undefined) blocked.push({ region: o.region, box: boundsOf(o.region) });
+  for (const item of input.items) {
+    if (!lockedAt(item)) continue;
+    const box = itemBox(item);
+    blocked.push({ region: { kind: "rect", ...box }, box });
+  }
+
+  const shape = input.container.shape;
+  const innerArea = inner.w * inner.h;
+  const inInner = (b: Box): boolean => b.w > 0 && b.h > 0 && boxIn(b, inner);
+  if (shape === undefined || shape.kind === "rect") {
+    const rects = blocked.filter((b) => b.region.kind === "rect");
+    let free = innerArea - unionArea(rects.map((b) => b.box), inner);
+    const kept: Box[] = [];
+    for (const b of blocked) {
+      if (b.region.kind === "rect" || !inInner(b.box)) continue;
+      if (rects.some((r) => boxesOverlap(r.box, b.box)) || kept.some((k) => boxesOverlap(k, b.box))) continue;
+      kept.push(b.box);
+      free -= blockedArea(b.region);
+    }
+    return Math.max(0, free);
+  }
+
+  let free = Math.min(innerArea, shapeArea(shape));
+  const kept: Box[] = [];
+  for (const b of blocked) {
+    if (!inInner(b.box) || !boxInShape(b.box, shape) || kept.some((k) => boxesOverlap(k, b.box))) continue;
+    kept.push(b.box);
+    free -= blockedArea(b.region);
+  }
+  return Math.max(0, free);
+}
+
+/**
+ * This function gives a lower bound of the overflow of an input: the items that no packer can place, and their area.
+ *
+ * - The candidates are the items that are not locked at a position.
+ * - A fixed side forces each candidate that is longer than the side less the inset, in each turn that the item permits.
+ * - A fixed size also forces the fewest other candidates that make the rest fit the free area of `freeAreaBound`. These are the largest ones.
+ * - The area of the bound is the area of the long items, plus the part of the area of the rest above the free area.
+ * - The margins and the gap do not count. A slack of the overlap tolerance along the edge of each candidate keeps the bound valid.
+ * - A container with no fixed side gives 0.
+ */
+export function overflowBound(input: PackInput): OverflowBound {
+  const { container } = input;
+  const fixedW = container.fixed === "size" || container.fixed === "width";
+  const fixedH = container.fixed === "size" || container.fixed === "height";
+  if (!fixedW && !fixedH) return { forced: 0, area: 0, free: Infinity };
+  const tol = DEFAULT_TOLERANCE.overlap;
+  const bounds = containerBox(input);
+  const inset = container.inset ?? 0;
+  const maxW = fixedW ? bounds.w - 2 * inset + 2 * tol : Infinity;
+  const maxH = fixedH ? bounds.h - 2 * inset + 2 * tol : Infinity;
+
+  let forced = 0;
+  let area = 0;
+  let slack = 0;
+  const rest: number[] = [];
+  for (const item of input.items) {
+    if (lockedAt(item)) continue;
+    const box = itemBox(item);
+    const w = Math.min(item.w, box.w);
+    const h = Math.min(item.h, box.h);
+    const fits = (w <= maxW && h <= maxH) || (item.turnable === true && h <= maxW && w <= maxH);
+    const a = itemArea(item);
+    if (!fits) {
+      forced += 1;
+      area += a;
+      continue;
+    }
+    rest.push(a);
+    slack += 2 * tol * (Math.max(0, w) + Math.max(0, h));
+  }
+  if (!(fixedW && fixedH)) return { forced, area, free: Infinity };
+
+  const free = freeAreaBound(input);
+  // An item can go out of the container by the tolerance, thus the edge of the container adds a slack too
+  const room = free + slack + 2 * tol * (Math.max(0, bounds.w) + Math.max(0, bounds.h));
+  let sum = rest.reduce((s, a) => s + a, 0);
+  area += Math.max(0, sum - room);
+  // The largest items go first, so the count of the dropped items is the smallest count that fits the area
+  for (const a of rest.toSorted((p, q) => q - p)) {
+    if (sum <= room || !(a > 0)) break;
+    sum -= a;
+    forced += 1;
+  }
+  return { forced, area, free };
+}

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;