@mark1russell7/packing 0.1.2 → 0.1.3

package/src/adapters.ts

@@ -0,0 +1,261 @@
+// The adapters of 0.1 (docs/PACKER.md): each function of 0.1 runs behind the Packer interface as a strategy.
+
+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 type { SortOrder } from "./order.ts";
+import { pack } from "./pack.ts";
+import { pushCascade } from "./push.ts";
+import { Rect } from "./rect.ts";
+import { packSkyline } from "./skyline.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`. */
+export interface LayoutStrategyOptions {
+  /** The order of the items before the packing. The items are in the order of their rank first. */
+  sortOrder: SortOrder;
+  /** The number of widths that the first pass of the size search `log-sweep` tries. */
+  samples: number;
+}
+
+/** The options of the strategy `push`. */
+export interface PushStrategyOptions {
+  /** The order of the items that the cascade does not place. */
+  sortOrder: SortOrder;
+  /** The most shoves for each item. The cascade stops at this limit. */
+  maxShovesPerItem: number;
+}
+
+/** The cells of `rows`, `skyline` and `shelf`, without the movement of the obstacles. */
+const LAYOUT_CELLS = {
+  containerSize: ["fixed", "freeHeight", "freeWidth", "freeAspect", "freeArea"],
+  containerShape: ["rect"],
+  itemShape: ["rect"],
+  rotation: ["none"],
+  groups: ["none"],
+  mode: ["offline"],
+} as const satisfies Partial<Supports>;
+
+/** This function makes the supports of a strategy, with copies of each list. */
+function supportsOf(cells: { [D in keyof Supports]: readonly Supports[D][number][] }): Supports {
+  return {
+    containerSize: [...cells.containerSize],
+    containerShape: [...cells.containerShape],
+    obstacleMove: [...cells.obstacleMove],
+    itemShape: [...cells.itemShape],
+    rotation: [...cells.rotation],
+    order: [...cells.order],
+    groups: [...cells.groups],
+    mode: [...cells.mode],
+  };
+}
+
+/** This function packs an input with a fixed size or a fixed width with one strategy of `pack`. */
+function packFixedWidth(id: "rows" | "skyline" | "shelf", input: PackInput, options: LayoutStrategyOptions): PackOutput {
+  const start = now();
+  const frame = buildFrame(input);
+  const rects = rectsOf(frame);
+  if (frame.w > 0) pack(rects, outerOf(frame), { strategy: id, sortOrder: options.sortOrder });
+  const output = readFrame(input, frame, []);
+  output.trace.push({ id, ms: now() - start, measures: { "pack.overflow": output.overflow.length } });
+  return output;
+}
+
+/** This function makes the strategy of one function of `pack`. */
+function layoutStrategy(
+  id: "rows" | "skyline" | "shelf",
+  family: string,
+  catalog: string[],
+  cells: Pick<Supports, "obstacleMove" | "order">,
+): Strategy<LayoutStrategyOptions> {
+  const self: Strategy<LayoutStrategyOptions> = {
+    id,
+    family,
+    catalog,
+    supports: supportsOf({ ...LAYOUT_CELLS, ...cells }),
+    defaults: { sortOrder: "height-desc", samples: 48 },
+    deterministic: true,
+    pack(input, options, context) {
+      assertSupported(self.supports, input);
+      const o = { ...self.defaults, ...options };
+      switch (input.container.fixed) {
+        case "height":
+          return viaAxes(input, context.previous, (turned) => packFixedWidth(id, turned, o));
+        case "none":
+          return logSweep.search(input, self, context, o);
+        default:
+          return packFixedWidth(id, input, o);
+      }
+    },
+  };
+  return self;
+}
+
+/**
+ * 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`.
+ */
+export const rows: Strategy<LayoutStrategyOptions> = layoutStrategy("rows", "shelf", ["rows-gap-fill", "rows-input"], {
+  obstacleMove: [],
+  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`.
+ */
+export const skyline: Strategy<LayoutStrategyOptions> = layoutStrategy("skyline", "skyline", ["skyline-bl"], {
+  obstacleMove: ["fixed"],
+  order: ["free", "soft"],
+});
+
+/**
+ * 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`.
+ */
+export const shelf: Strategy<LayoutStrategyOptions> = layoutStrategy("shelf", "shelf", ["shelf-nf", "shelf-nfdh"], {
+  obstacleMove: ["fixed"],
+  order: ["free", "soft", "hard"],
+});
+
+/**
+ * The size search `log-sweep` uses `packFree` of 0.1.2: widths on a log scale, then the widths near the best width. It
+ * wraps `rows`, `skyline` and `shelf`. The objective is the area of the frame times `1 + aspectWeight * aspectError`.
+ */
+export const logSweep: SizeSearch = {
+  id: "log-sweep",
+  search(input: PackInput, inner: Strategy, context: PackContext, options?: unknown): PackOutput {
+    if (input.container.fixed !== "none") return inner.pack(input, options ?? inner.defaults, context);
+    const id = inner.id;
+    if (id !== "rows" && id !== "skyline" && id !== "shelf") throw new UnsupportedCell("containerSize", cellOf(input).containerSize);
+    const o = { ...(inner.defaults as LayoutStrategyOptions), ...(options as Partial<LayoutStrategyOptions> | undefined) };
+    const start = now();
+    const frame = buildFrame(input);
+    const result = packFree(rectsOf(frame), new Rect<number>(), {
+      strategy: id,
+      sortOrder: o.sortOrder,
+      samples: o.samples,
+      aspect: input.container.aspect ?? 1,
+      aspectWeight: input.container.aspectWeight ?? 1,
+    });
+    const ms = now() - start;
+    const runs = result.tried.length + 1;
+    const output = readFrame(input, frame, []);
+    output.trace.push(
+      { 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 } },
+    );
+    return output;
+  },
+};
+
+/** This function tells if the insides of two rectangles overlap by more than `EPS`. */
+function overlaps(a: Rect, b: Rect): boolean {
+  return (
+    Math.min(a.right(), b.right()) - Math.max(a.position.x, b.position.x) > EPS &&
+    Math.min(a.bottom(), b.bottom()) - Math.max(a.position.y, b.position.y) > EPS
+  );
+}
+
+/** This function packs an input with a fixed size or a fixed width with a push cascade. */
+function pushFixedWidth(input: PackInput, options: PushStrategyOptions, previous: PackOutput | undefined): PackOutput {
+  const start = now();
+  const frame = buildFrame(input, true);
+  const before = new Map(previous?.placements.map((p) => [p.id, p]));
+  const positioned: Entry[] = [];
+  const pending: Entry[] = [];
+  const obstacles = frame.entries.filter((e) => e.obstacle !== undefined);
+  const starts = new Map(obstacles.map((e) => [e, { x: e.rect.position.x, y: e.rect.position.y }]));
+  const lockedItems = frame.entries.filter((e) => e.item !== undefined && e.rect.locked);
+
+  for (const e of frame.entries) {
+    const item = e.item;
+    if (item === undefined || e.rect.locked) continue;
+    const x = item.x ?? before.get(item.id)?.x;
+    const y = item.y ?? before.get(item.id)?.y;
+    if (x === undefined || y === undefined) {
+      pending.push(e);
+      continue;
+    }
+    e.rect.position.set(x - e.dx - frame.ox, y - e.dy - frame.oy);
+    positioned.push(e);
+  }
+
+  // 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);
+  for (const e of positioned) {
+    pushCascade(e.rect, inPlay, { gap: 0, maxShoves });
+    e.rect.locked = true;
+  }
+
+  // An obstacle that the cascade pushed out of the container or onto a locked item goes back to its start
+  const { bounds } = frame;
+  const moved: PackOutput["moved"] = [];
+  for (const e of obstacles) {
+    const startAt = starts.get(e)!;
+    const x = e.rect.position.x + e.dx + frame.ox;
+    const y = e.rect.position.y + e.dy + frame.oy;
+    const b = boundsOf(e.obstacle!.region);
+    const out = x < bounds.x - EPS || y < bounds.y - EPS || x + b.w > bounds.x + bounds.w + EPS || y + b.h > bounds.y + bounds.h + EPS;
+    if (out || lockedItems.some((l) => overlaps(l.rect, e.rect))) e.rect.position.set(startAt.x, startAt.y);
+    else if (Math.abs(e.rect.position.x - startAt.x) > EPS || Math.abs(e.rect.position.y - startAt.y) > EPS) moved.push({ id: e.obstacle!.id, x, y });
+  }
+  const pushMs = now() - start;
+
+  // Each item that is out of the area or overlaps a kept rectangle goes to the skyline, around the kept rectangles
+  const kept = [...obstacles, ...lockedItems].map((e) => e.rect);
+  for (const e of positioned) {
+    const r = e.rect;
+    const inside = r.position.x >= -EPS && r.position.y >= -EPS && r.right() <= frame.w + EPS && r.bottom() <= frame.h + EPS;
+    if (inside && !kept.some((k) => overlaps(k, r))) kept.push(r);
+    else pending.push(e);
+  }
+  const skylineStart = now();
+  for (const r of kept) {
+    r.locked = true;
+    r.wasPacked = true;
+  }
+  if (pending.length > 0 && frame.w > 0) {
+    for (const e of pending) {
+      e.rect.locked = false;
+      e.rect.wasPacked = false;
+    }
+    packSkyline([...pending.map((e) => e.rect), ...kept], outerOf(frame), { sortOrder: options.sortOrder });
+  }
+  const output = readFrame(input, frame, [], moved);
+  output.trace.push(
+    { id: "push", ms: pushMs, measures: { "pack.push.moved": moved.length } },
+    { id: "skyline", ms: now() - skylineStart, measures: { "pack.push.replaced": pending.length, "pack.overflow": output.overflow.length } },
+  );
+  return output;
+}
+
+/**
+ * The strategy `push` uses `pushCascade`. Each item starts at its `x` and `y`, or at its place in `context.previous`.
+ * Each item in rank order pushes the items and the movable obstacles that it overlaps. Then `packSkyline` places the
+ * items with no start, and the items that still overlap. The output tells each obstacle that moved.
+ */
+export const push: Strategy<PushStrategyOptions> = {
+  id: "push",
+  family: "incremental",
+  catalog: ["incremental-push"],
+  supports: supportsOf({
+    containerSize: ["fixed", "freeHeight", "freeWidth"],
+    containerShape: ["rect"],
+    obstacleMove: ["fixed", "free"],
+    itemShape: ["rect"],
+    rotation: ["none"],
+    order: ["free", "soft"],
+    groups: ["none"],
+    mode: ["incremental"],
+  }),
+  defaults: { sortOrder: "height-desc", maxShovesPerItem: 8 },
+  deterministic: true,
+  pack(input, options, context) {
+    assertSupported(push.supports, input);
+    const o = { ...push.defaults, ...options };
+    if (input.container.fixed === "height") return viaAxes(input, context.previous, (turned, previous) => pushFixedWidth(turned, o, previous));
+    return pushFixedWidth(input, o, context.previous);
+  },
+};

package/src/check.ts

@@ -0,0 +1,84 @@
+import { DEFAULT_TOLERANCE, marginOf, RECORD_EPS, turnItem, type Item, type PackInput, type PackOutput, type Tolerance } from "./contract.ts";
+import { boundsOf } from "./frame.ts";
+
+/** The count of the breaks of each hard rule of the packer (`docs/FORMAT.md`). A good run has 0 for each rule. */
+export interface HardBreaks {
+  "no-overlap": number;
+  "in-container": number;
+  "locked-kept": number;
+  complete: number;
+}
+
+/** A box with its margin: the left, top, right and bottom edges. */
+interface Box {
+  l: number;
+  t: number;
+  r: number;
+  b: number;
+}
+
+/** This function tells if the insides of two boxes overlap by more than a tolerance on each axis. */
+function overlap(a: Box, b: Box, tolerance: number): boolean {
+  return Math.min(a.r, b.r) - Math.max(a.l, b.l) > tolerance && Math.min(a.b, b.b) - Math.max(a.t, b.t) > tolerance;
+}
+
+/**
+ * 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.
+ *
+ * The rules read a shape of the container or of an obstacle as its bounding box. 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;
+  const placements = new Map<string, PackOutput["placements"][number]>();
+  for (const p of output.placements) if (!placements.has(p.id)) placements.set(p.id, p);
+  const overflow = new Set(output.overflow);
+  const breaks: HardBreaks = { "no-overlap": 0, "in-container": 0, "locked-kept": 0, complete: 0 };
+
+  const boxes: Box[] = [];
+  for (const item of input.items) {
+    const p = 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;
+    }
+    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 moved = new Map(output.moved.map((m) => [m.id, m]));
+  const obstacles: Box[] = (input.obstacles ?? []).map((o) => {
+    const b = boundsOf(o.region);
+    const at = moved.get(o.id) ?? b;
+    return { l: at.x, t: at.y, r: at.x + b.w, b: at.y + b.h };
+  });
+
+  for (const [i, a] of boxes.entries()) {
+    for (let j = i + 1; j < boxes.length; j++) if (overlap(a, boxes[j]!, tol)) breaks["no-overlap"] += 1;
+    for (const o of obstacles) if (overlap(a, o, tol)) breaks["no-overlap"] += 1;
+  }
+
+  const { container } = input;
+  const shape = container.shape === undefined ? undefined : boundsOf(container.shape);
+  const x = shape?.x ?? 0;
+  const y = shape?.y ?? 0;
+  const w = shape?.w ?? container.w ?? Infinity;
+  const h = shape?.h ?? container.h ?? Infinity;
+  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);
+    if (outX || outY) breaks["in-container"] += 1;
+  }
+  return breaks;
+}

package/src/contract.ts

@@ -0,0 +1,203 @@
+// The data types of the Packer contract (docs/PACKER.md). They are plain data, with no class and no method.
+// The shared package `@mark1russell7/layout-contract` gets these types later. Until then, this file is a local copy.
+
+/** A region. The forms and the rules are those of `docs/FORMAT.md`. The y axis points down. */
+export type Region =
+  | { kind: "rect"; x: number; y: number; w: number; h: number }
+  | { kind: "polygon"; points: [number, number][]; holes?: [number, number][][] }
+  | { kind: "circle"; cx: number; cy: number; r: number }
+  | { kind: "ellipse"; cx: number; cy: number; rx: number; ry: number };
+
+/** The container of a packing. */
+export interface Container {
+  /** The width. Without it, the packer searches the width. */
+  w?: number;
+  /** The height. Without it, the packer searches the height. */
+  h?: number;
+  /** The sides that stay: `size` keeps `w` and `h`, `width` keeps `w`, `height` keeps `h`, and `none` searches both. */
+  fixed: "size" | "width" | "height" | "none";
+  /** The target aspect (the width divided by the height) for the value `none` of `fixed`. The default is 1. */
+  aspect?: number;
+  /** The weight of the aspect error in the objective. The value 0 gives the least area. The default is 1. */
+  aspectWeight?: number;
+  /** The shape. Without it, the container is the rectangle from 0, 0 to `w`, `h`. */
+  shape?: Region;
+  /** The space between the border and the items with their margins. The default is 0. */
+  inset?: number;
+}
+
+/** An obstacle: an area that no item enters. */
+export interface Obstacle {
+  id: string;
+  region: Region;
+  /** Without it, the obstacle stays. With it, the packer can move the obstacle for `cost` times the distance. */
+  move?: { cost: number };
+}
+
+/** The margin of an item on each side. */
+export interface Margin {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+}
+
+/** A port on the border of an item. */
+export interface Port {
+  id: string;
+  side: "top" | "right" | "bottom" | "left";
+  /** The point on the border of the item, relative to its top-left corner. Without it, the router chooses the point. */
+  x?: number;
+  y?: number;
+}
+
+/** An item to pack. The file format names it a box. */
+export interface Item {
+  id: string;
+  w: number;
+  h: number;
+  /** The reading order. Without it, the index in the array is the rank. */
+  rank?: number;
+  group?: string;
+  parent?: string;
+  /** A shape relative to the origin of the item. Without it, the item is the rectangle `w` by `h`. */
+  shape?: Region;
+  /** A locked item keeps `x` and `y`. The packer reads it as an obstacle. */
+  locked?: boolean;
+  x?: number;
+  y?: number;
+  /** The value `true` lets the packer turn the item by 90 degrees. The default is `false`. */
+  turnable?: boolean;
+  /** A ring around the item that no other item and no route enters. The default is 0. */
+  margin?: number | Margin;
+  /** The ports. The packer keeps them, and turns them with the item. */
+  ports?: Port[];
+}
+
+/** The input of a packing: a `layout-input/1` file without `edges`, with `items` for `boxes`. */
+export interface PackInput {
+  container: Container;
+  items: Item[];
+  obstacles?: Obstacle[];
+  /** The free space between two items with their margins. Routes use this space. The default is 0. */
+  gap?: number;
+}
+
+/** The position of one item after the packing. */
+export interface Placement {
+  id: string;
+  x: number;
+  y: number;
+  /** The turn: 0 or 90, only for an item with `turnable` set to `true`. */
+  turn?: 0 | 90;
+}
+
+/** The facts of one stage of a packing. */
+export interface StageTrace {
+  /** The id of the stage, for example `skyline` or `log-sweep`. */
+  id: string;
+  /** The time of the stage in milliseconds. */
+  ms: number;
+  /** The measures of the stage, by the names of `docs/FORMAT.md`. */
+  measures: Record<string, number>;
+}
+
+/** The output of a packing. The output does not change the input. */
+export interface PackOutput {
+  placements: Placement[];
+  /** The ids of the items that the packer did not place. */
+  overflow: string[];
+  /** The size of the container after the packing. For a free size, the size that the search found. */
+  size: { w: number; h: number };
+  /** The new positions of the obstacles that moved. */
+  moved: { id: string; x: number; y: number }[];
+  /** The facts of each stage, for the site and the records. */
+  trace: StageTrace[];
+}
+
+/** The tolerances of the hard rules. */
+export interface Tolerance {
+  /** The rule `no-overlap`: two boxes overlap only by more than this value. */
+  overlap: number;
+  /** The router rule that a route does not go through a box. */
+  through: number;
+}
+
+/** The tolerance for the comparison of two numbers in an engine. */
+export const EPS = 1e-6;
+
+/** The tolerance for the comparison of two numbers of a file. The files round to 3 decimals. */
+export const RECORD_EPS = 1e-3;
+
+/** The default tolerances of the hard rules. Each record writes its tolerances in its top-level field `tolerance`. */
+export const DEFAULT_TOLERANCE: Readonly<Tolerance> = Object.freeze({ overlap: 0.001, through: 0.5 });
+
+/** This function gives the margin of an item on each side. A number is the same margin on each side. */
+export function marginOf(item: Pick<Item, "margin">): Margin {
+  const m = item.margin ?? 0;
+  if (typeof m === "number") return { top: m, right: m, bottom: m, left: m };
+  return { top: m.top, right: m.right, bottom: m.bottom, left: m.left };
+}
+
+/** The side of a port after a turn of 90 degrees clockwise. */
+const TURNED_SIDE = { top: "right", right: "bottom", bottom: "left", left: "top" } as const;
+
+/** This function gives the point `px`, `py` of an item of height `h` after a turn of 90 degrees clockwise. */
+export function turnPoint(px: number, py: number, h: number): [number, number] {
+  return [h - py, px];
+}
+
+/** This function turns a port of an item of height `h` by 90 degrees clockwise. The side turns from top to right. */
+export function turnPort(port: Port, h: number): Port {
+  const turned: Port = { id: port.id, side: TURNED_SIDE[port.side] };
+  if (port.x !== undefined && port.y !== undefined) {
+    const [x, y] = turnPoint(port.x, port.y, h);
+    turned.x = x;
+    turned.y = y;
+  } else if (port.x !== undefined) {
+    // Only x is set: x becomes the new y, and the router chooses the new x
+    turned.y = port.x;
+  } else if (port.y !== undefined) {
+    // Only y is set: h - y becomes the new x, and the router chooses the new y
+    turned.x = h - port.y;
+  }
+  return turned;
+}
+
+/** This function turns a region relative to an item of height `h` by 90 degrees clockwise. */
+export function turnRegion(region: Region, h: number): Region {
+  switch (region.kind) {
+    case "rect":
+      return { kind: "rect", x: h - region.y - region.h, y: region.x, w: region.h, h: region.w };
+    case "circle": {
+      const [cx, cy] = turnPoint(region.cx, region.cy, h);
+      return { kind: "circle", cx, cy, r: region.r };
+    }
+    case "ellipse": {
+      const [cx, cy] = turnPoint(region.cx, region.cy, h);
+      return { kind: "ellipse", cx, cy, rx: region.ry, ry: region.rx };
+    }
+    case "polygon": {
+      const turnRing = (ring: [number, number][]): [number, number][] => ring.map(([x, y]) => turnPoint(x, y, h));
+      const turned: Region = { kind: "polygon", points: turnRing(region.points) };
+      if (region.holes) turned.holes = region.holes.map(turnRing);
+      return turned;
+    }
+  }
+}
+
+/**
+ * This function gives an item after a turn of 90 degrees clockwise, with the y axis down (decision 1 of
+ * `docs/PACKER.md`). The width and the height change places. The top-left corner, the id and the other fields stay.
+ * The ports, the shape and the margin turn with the item. The function does not change its argument.
+ */
+export function turnItem(item: Item): Item {
+  const turned: Item = { ...item, w: item.h, h: item.w };
+  if (item.ports) turned.ports = item.ports.map((p) => turnPort(p, item.h));
+  if (item.shape) turned.shape = turnRegion(item.shape, item.h);
+  if (item.margin !== undefined && typeof item.margin !== "number") {
+    const m = item.margin;
+    turned.margin = { top: m.left, right: m.top, bottom: m.right, left: m.bottom };
+  }
+  return turned;
+}

package/src/convert.ts

@@ -0,0 +1,51 @@
+import type { Item, PackInput, PackOutput } from "./contract.ts";
+import type { Rect } from "./rect.ts";
+
+/**
+ * This function makes a `PackInput` from the `Rect` objects of 0.1. The id of each item is the index of its rectangle.
+ *
+ * - `fixedSize` gives `fixed` set to `size`, `fixedWidth` gives `width`, and an outer rectangle without them gives `none`.
+ * - A locked rectangle gives a locked item at its position.
+ * - An outer rectangle at a position other than 0, 0 gives a rectangle shape at that position.
+ */
+export function fromRects<T>(rects: readonly Rect<T>[], outer: Rect<T>): PackInput {
+  const fixed = outer.fixedSize ? "size" : outer.fixedWidth ? "width" : "none";
+  const container: PackInput["container"] = { fixed };
+  if (fixed !== "none") container.w = outer.size.x;
+  if (fixed === "size") container.h = outer.size.y;
+  if (outer.position.x !== 0 || outer.position.y !== 0) {
+    container.shape = { kind: "rect", x: outer.position.x, y: outer.position.y, w: outer.size.x, h: outer.size.y };
+  }
+  const items = rects.map((r, i): Item => {
+    const item: Item = { id: String(i), w: r.size.x, h: r.size.y };
+    if (r.locked) {
+      item.locked = true;
+      item.x = r.position.x;
+      item.y = r.position.y;
+    }
+    return item;
+  });
+  return { container, items };
+}
+
+/**
+ * This function writes an output back into the `Rect` objects of `fromRects`. It sets the position and `wasPacked` of
+ * each rectangle, and the free sides of the outer rectangle. It gives the outer rectangle.
+ */
+export function toRects<T>(output: PackOutput, rects: Rect<T>[], outer: Rect<T>): Rect<T> {
+  const placements = new Map(output.placements.map((p) => [p.id, p]));
+  for (const [i, r] of rects.entries()) {
+    const p = placements.get(String(i));
+    if (p === undefined) {
+      r.wasPacked = r.locked;
+      continue;
+    }
+    r.position.set(p.x, p.y);
+    r.wasPacked = true;
+  }
+  if (!outer.fixedSize) {
+    if (!outer.fixedWidth) outer.size.x = output.size.w;
+    outer.size.y = output.size.h;
+  }
+  return outer;
+}