@slithy/prim-lib 0.3.1 → 0.4.0

package/README.md

@@ -10,15 +10,15 @@ Reconstructs an image by iteratively placing geometric shapes. Each step evaluat
 
 ### Classes
 
-- **`Canvas`** — wraps `HTMLCanvasElement`; handles image loading, pixel reads, drawing steps, and SVG output
-- **`Optimizer`** — runs the rAF loop; calls `onStep` after each shape is placed
+- **`Canvas`** — wraps `HTMLCanvasElement` or `OffscreenCanvas` (environment-detected); handles image loading, pixel reads, drawing steps, and SVG output
+- **`Optimizer`** — runs the step loop; calls `onStep` after each shape is placed. Accepts an optional `schedule` function (defaults to `requestAnimationFrame`; pass `fn => setTimeout(fn, 0)` for worker contexts)
 - **`State`** — holds the current canvas and its distance from the target
 - **`Step`** — a single candidate shape placement; computes best color and difference change
 
 ### Shapes
 
 - **`Shape`** — abstract base
-- **`Triangle`**, **`Rectangle`**, **`Ellipse`**, **`Square`**, **`Hexagon`**, **`Glyph`**, **`Debug`**
+- **`Triangle`**, **`Rectangle`**, **`Ellipse`**, **`Circle`**, **`Square`**, **`Hexagon`**, **`Glyph`**, **`Debug`**
 
 ### Types
 
@@ -38,12 +38,14 @@ interface Cfg {
   allowUpscale?: boolean // allow output larger than source image (default: false)
   scale?: number        // viewSize / computeSize ratio (set by Canvas.original)
   shapeTypes: Array<new (w: number, h: number) => ShapeInterface>
+  shapeWeights?: number[]  // per-shape selection weights (same length as shapeTypes)
   fill: 'auto' | string
 }
 ```
 
 - **`PreCfg`** — `Cfg` with optional `width`/`height`; used before image dimensions are known
 - **`ShapeInterface`** — structural interface for shapes; includes `toData(alpha, color): StepData`
+- **`Ctx2D`** — `CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D`; used for canvas operations that work in both main-thread and worker contexts
 - **`Bbox`**, **`Point`**, **`ImageDataLike`**, **`ShapeImageData`**
 
 **`RGB`** — `[number, number, number]` tuple
@@ -55,6 +57,7 @@ type StepData =
   | { t: 't';  a: number; c: RGB; pts: [number, number][] }       // Triangle
   | { t: 'r';  a: number; c: RGB; pts: [number, number][] }       // Rectangle
   | { t: 'e';  a: number; c: RGB; cx: number; cy: number; rx: number; ry: number } // Ellipse
+  | { t: 'c';  a: number; c: RGB; cx: number; cy: number; r: number }              // Circle
   | { t: 's';  a: number; c: RGB; cx: number; cy: number; r: number }              // Square
   | { t: 'h';  a: number; c: RGB; cx: number; cy: number; r: number; angle: number } // Hexagon
   | { t: 'sm'; a: number; c: RGB; cx: number; cy: number; fs: number; text: string } // Glyph
@@ -77,7 +80,7 @@ interface SerializedOutput {
 
 ```ts
 interface ReplayResult {
-  raster: HTMLCanvasElement
+  raster: HTMLCanvasElement | OffscreenCanvas
   svg: SVGSVGElement
   svgString: string
 }
@@ -87,6 +90,10 @@ interface ReplayResult {
 
 **`replayOutput(data: SerializedOutput): ReplayResult`** — reconstructs canvas and SVG natively from serialized output, without re-running the optimizer. Useful for restoring saved results from localStorage or a database.
 
+**`renderStepToCtx(data: StepData, ctx: Ctx2D): void`** — renders a single `StepData` onto a 2D canvas context. Used internally by `replayOutput` and by `runWorker` to incrementally apply worker-posted steps to the display canvas.
+
+**`stepDataToSVGElement(data: StepData): SVGElement`** — creates a DOM `SVGElement` from a `StepData`. Used internally by `replayOutput` and by `runWorker` to build the live SVG incrementally on the main thread.
+
 ### Utilities
 
 - **`getFill(data: ImageDataLike): string`** — computes a fill color (average of corner pixels) from image data
@@ -101,14 +108,17 @@ interface ReplayResult {
 - **ESM only** — no CommonJS; no `importScripts()`
 - **Canvas reuse** — the original creates a new `<canvas>` element for every shape rasterization call (~58,000 per run at default settings). `prim-lib` reuses a single module-level canvas, growing it only when a larger bbox is seen. This delivered a ~27× speedup (37 s → ~0.8 s rasterize time per run)
 - **`willReadFrequently: true`** — canvas contexts used for `getImageData` are created with this flag, keeping pixel data in CPU memory and suppressing browser warnings
-- **Workers removed** — the original included worker stubs (`importScripts()`-based, not ESM-compatible). Workers were investigated and benchmarked; after the canvas reuse optimization, a batched worker implementation matched single-threaded performance. Workers are not used
+- **Worker-compatible** — `Canvas` detects its environment: in a browser context it creates `HTMLCanvasElement`; in a worker it creates `OffscreenCanvas` (same 2D API). `Canvas.fromBitmap()` loads an image from an `ImageBitmap` (worker-compatible) rather than `new Image()`. `Optimizer` accepts an injectable `schedule` function so callers can substitute `setTimeout` for `requestAnimationFrame` in worker contexts. The original included `importScripts()`-based worker stubs (not ESM-compatible) which were removed; worker support is now done properly via `prim-interface`'s `runWorker()`
 - **Architecture split** — the original is a single-layer library. Here, `prim-lib` is the pure algorithm (no knowledge of how images arrive or where results go), and `prim-interface` is the adapter that wires it to the browser
 - **`PreCfg` / `Cfg` distinction** — `Canvas.original()` accepts `PreCfg` (optional `width`/`height`) and resolves to a fully-populated `Cfg`, making the config lifecycle explicit in the types
 - **Serialization** — `StepData` / `SerializedOutput` allow completed runs to be stored compactly and replayed via `replayOutput()` without re-running the optimizer
+- **Additional shapes** — `Circle`, `Square`, `Hexagon`, and `Glyph` are not in the original; `Circle` is a uniform-radius variant of `Ellipse`
+- **Shape weighting** — `shapeWeights` allows biased shape selection with a guaranteed distribution: the optimizer pre-allocates exact per-shape step counts (largest-remainder rounding) and shuffles them, so the final mix always matches the requested weights
 
 ## Architecture notes
 
-- `Shape.rasterize()` reuses a single module-level canvas (`_rasterCanvas`) grown to the max shape size seen; avoids per-call `createElement('canvas')` which was the dominant cost (27x speedup)
-- `Cfg.shapeTypes` holds shape constructors; shapes are chosen randomly each step
-- `PreCfg` exists to bridge the gap between call time (dimensions unknown) and runtime (dimensions set by `Canvas.original()`)
-- `Canvas.svgRoot()` is a static helper shared by `Canvas.empty()` and `replayOutput()` to create the SVG root with clip path and background fill
+- `Shape.rasterize()` reuses a single module-level canvas (`_rasterCanvas`) grown to the max shape size seen; in a worker, this is an `OffscreenCanvas` (environment-detected by the `Canvas` constructor). Avoids per-call canvas creation which was the dominant cost (27x speedup)
+- `Cfg.shapeTypes` holds shape constructors; shapes are chosen randomly each step unless `shapeWeights` is set
+- When `shapeWeights` is provided (same length as `shapeTypes`), `Optimizer` builds a step plan at construction time: each shape type is allocated an exact number of slots proportional to its weight (using largest-remainder rounding), then the plan is Fisher-Yates shuffled. This guarantees the final shape distribution matches the weights, rather than just biasing random selection
+- `PreCfg` exists to bridge the gap between call time (dimensions unknown) and runtime (dimensions set by `Canvas.original()` or `Canvas.fromBitmap()`)
+- `Canvas.svgRoot()` is a static helper shared by `Canvas.empty()` and `replayOutput()` to create the SVG root with clip path and background fill; it uses DOM APIs and is main-thread only

package/dist/index.d.ts

@@ -30,7 +30,7 @@ interface ShapeInterface {
     rasterize(alpha: number): {
         getImageData(): ImageDataLike;
     };
-    render(ctx: CanvasRenderingContext2D): void;
+    render(ctx: Ctx2D): void;
 }
 interface Cfg {
     width: number;
@@ -57,6 +57,7 @@ type PreCfg = Omit<Cfg, 'width' | 'height'> & {
     height?: number;
 };
 type RGB = [number, number, number];
+type Ctx2D = CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;
 type StepData = {
     t: 't';
     a: number;
@@ -119,17 +120,18 @@ interface DrawableStep {
     alpha: number;
     color: string;
     shape: {
-        render(ctx: CanvasRenderingContext2D): void;
+        render(ctx: Ctx2D): void;
     };
 }
 declare class Canvas {
-    node: HTMLCanvasElement;
-    ctx: CanvasRenderingContext2D;
+    node: HTMLCanvasElement | OffscreenCanvas;
+    ctx: Ctx2D;
     _imageData: ImageData | null;
     static svgRoot(width: number, height: number, fill: string): SVGSVGElement;
     static empty(cfg: Cfg, svg: true): SVGSVGElement;
     static empty(cfg: Cfg, svg?: false): Canvas;
     static original(url: string, cfg: PreCfg): Promise<Canvas>;
+    static fromBitmap(bitmap: ImageBitmap, cfg: PreCfg): Canvas;
     static test(cfg: PreCfg): Canvas;
     constructor(width: number, height: number, willReadFrequently?: boolean);
     clone(): Canvas;
@@ -167,6 +169,7 @@ declare class Step {
     mutate(): Step;
 }
 
+type ShapeCtor = new (w: number, h: number) => ShapeInterface;
 declare class Optimizer {
     cfg: Cfg;
     state: State;
@@ -174,7 +177,9 @@ declare class Optimizer {
     _steps: number;
     _stopped: boolean;
     _paused: boolean;
-    constructor(original: Canvas, cfg: Cfg);
+    _stepPlan: ShapeCtor[];
+    _schedule: (fn: () => void) => void;
+    constructor(original: Canvas, cfg: Cfg, schedule?: (fn: () => void) => void);
     start(): void;
     stop(): void;
     pause(): void;
@@ -196,7 +201,7 @@ declare class Shape implements ShapeInterface {
     rasterize(alpha: number): {
         getImageData(): ImageDataLike;
     };
-    render(_ctx: CanvasRenderingContext2D): void;
+    render(_ctx: Ctx2D): void;
 }
 declare class Polygon extends Shape {
     points: Point[];
@@ -294,11 +299,13 @@ declare function computeColorAndDifferenceChange(offset: Bbox, imageData: ShapeI
     differenceChange: number;
 };
 
+declare function renderStepToCtx(data: StepData, ctx: Ctx2D): void;
+declare function stepDataToSVGElement(data: StepData): SVGElement;
 interface ReplayResult {
-    raster: HTMLCanvasElement;
+    raster: HTMLCanvasElement | OffscreenCanvas;
     svg: SVGSVGElement;
     svgString: string;
 }
 declare function replayOutput(data: SerializedOutput): ReplayResult;
 
-export { type Bbox, Canvas, type Cfg, Circle, Debug, Ellipse, Glyph, Hexagon, type ImageDataLike, Optimizer, type Point, type PreCfg, type RGB, Rectangle, type ReplayResult, SVGNS, type SerializedOutput, Shape, type ShapeImageData, type ShapeInterface, Square, State, Step, type StepData, Triangle, clamp, clampColor, computeColorAndDifferenceChange, difference, differenceToDistance, distanceToDifference, getFill, parseColor, replayOutput, stepPerf };
+export { type Bbox, Canvas, type Cfg, Circle, type Ctx2D, Debug, Ellipse, Glyph, Hexagon, type ImageDataLike, Optimizer, type Point, type PreCfg, type RGB, Rectangle, type ReplayResult, SVGNS, type SerializedOutput, Shape, type ShapeImageData, type ShapeInterface, Square, State, Step, type StepData, Triangle, clamp, clampColor, computeColorAndDifferenceChange, difference, differenceToDistance, distanceToDifference, getFill, parseColor, renderStepToCtx, replayOutput, stepDataToSVGElement, stepPerf };

package/dist/index.js

@@ -190,6 +190,22 @@ var Canvas = class _Canvas {
       };
     });
   }
+  static fromBitmap(bitmap, cfg) {
+    const w = bitmap.width;
+    const h = bitmap.height;
+    const computeScale = getScale(w, h, cfg.computeSize, cfg.allowUpscale);
+    cfg.width = w / computeScale;
+    cfg.height = h / computeScale;
+    const viewScale = getScale(w, h, cfg.viewSize, cfg.allowUpscale);
+    cfg.scale = computeScale / viewScale;
+    const fullCfg = { ...cfg, width: cfg.width, height: cfg.height };
+    const canvas = this.empty(fullCfg);
+    canvas.ctx.drawImage(bitmap, 0, 0, fullCfg.width, fullCfg.height);
+    if (cfg.fill === "auto") {
+      cfg.fill = getFill(canvas.getImageData());
+    }
+    return canvas;
+  }
   static test(cfg) {
     cfg.width = cfg.computeSize;
     cfg.height = cfg.computeSize;
@@ -216,10 +232,17 @@ var Canvas = class _Canvas {
     return canvas;
   }
   constructor(width, height, willReadFrequently = false) {
-    this.node = document.createElement("canvas");
-    this.node.width = width;
-    this.node.height = height;
-    this.ctx = this.node.getContext("2d", { willReadFrequently });
+    if (typeof document !== "undefined") {
+      const el = document.createElement("canvas");
+      el.width = width;
+      el.height = height;
+      this.node = el;
+      this.ctx = el.getContext("2d", { willReadFrequently });
+    } else {
+      const el = new OffscreenCanvas(width, height);
+      this.node = el;
+      this.ctx = el.getContext("2d", { willReadFrequently });
+    }
     this._imageData = null;
   }
   clone() {
@@ -854,6 +877,22 @@ var Debug = class extends Shape {
 };
 
 // src/optimizer.ts
+function buildStepPlan(cfg) {
+  const { shapeTypes, shapeWeights, steps } = cfg;
+  if (!shapeWeights || shapeWeights.length !== shapeTypes.length) return [];
+  const total = shapeWeights.reduce((sum, w) => sum + w, 0);
+  const floats = shapeWeights.map((w) => w / total * steps);
+  const floors = floats.map(Math.floor);
+  const remainder = steps - floors.reduce((s, n) => s + n, 0);
+  const indices = floats.map((f, i) => ({ i, frac: f - floors[i] })).sort((a, b) => b.frac - a.frac).slice(0, remainder).map((x) => x.i);
+  const counts = floors.map((n, i) => indices.includes(i) ? n + 1 : n);
+  const plan = shapeTypes.flatMap((ctor, i) => Array(counts[i]).fill(ctor));
+  for (let i = plan.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    [plan[i], plan[j]] = [plan[j], plan[i]];
+  }
+  return plan;
+}
 var Optimizer = class {
   cfg;
   state;
@@ -861,7 +900,9 @@ var Optimizer = class {
   _steps;
   _stopped;
   _paused;
-  constructor(original, cfg) {
+  _stepPlan;
+  _schedule;
+  constructor(original, cfg, schedule = (fn) => requestAnimationFrame(fn)) {
     this.cfg = cfg;
     this.state = new State(original, Canvas.empty(cfg));
     this._steps = 0;
@@ -869,6 +910,8 @@ var Optimizer = class {
     this._paused = false;
     this.onStep = () => {
     };
+    this._stepPlan = buildStepPlan(cfg);
+    this._schedule = schedule;
   }
   start() {
     this._stopped = false;
@@ -904,15 +947,16 @@ var Optimizer = class {
       return;
     }
     if (this._steps < this.cfg.steps) {
-      requestAnimationFrame(() => this._addShape());
+      this._schedule(() => this._addShape());
     }
   }
   _findBestStep() {
     const LIMIT = this.cfg.shapes;
+    const ctor = this._stepPlan[this._steps];
     let bestStep = null;
     const promises = [];
     for (let i = 0; i < LIMIT; i++) {
-      const shape = Shape.create(this.cfg);
+      const shape = ctor ? new ctor(this.cfg.width, this.cfg.height) : Shape.create(this.cfg);
       const promise = new Step(shape, this.cfg).compute(this.state).then((step) => {
         if (!bestStep || step.distance < bestStep.distance) {
           bestStep = step;
@@ -957,7 +1001,7 @@ function hexPoints(cx, cy, r, angle) {
     return [~~(cx + r * Math.cos(a)), ~~(cy + r * Math.sin(a))];
   });
 }
-function renderStep(data, ctx) {
+function renderStepToCtx(data, ctx) {
   ctx.globalAlpha = data.a;
   ctx.fillStyle = rgbString(data.c);
   switch (data.t) {
@@ -1002,7 +1046,7 @@ function renderStep(data, ctx) {
     }
   }
 }
-function stepToSVG(data) {
+function stepDataToSVGElement(data) {
   const color = rgbString(data.c);
   const opacity = data.a.toFixed(2);
   let node;
@@ -1070,8 +1114,8 @@ function replayOutput(data) {
   svg.setAttribute("width", String(vw));
   svg.setAttribute("height", String(vh));
   for (const step of data.steps) {
-    renderStep(step, raster.ctx);
-    svg.appendChild(stepToSVG(step));
+    renderStepToCtx(step, raster.ctx);
+    svg.appendChild(stepDataToSVGElement(step));
   }
   const svgString = new XMLSerializer().serializeToString(svg);
   return { raster: raster.node, svg, svgString };
@@ -1099,6 +1143,8 @@ export {
   distanceToDifference,
   getFill,
   parseColor,
+  renderStepToCtx,
   replayOutput,
+  stepDataToSVGElement,
   stepPerf
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slithy/prim-lib",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Core engine for primitive-based image reconstruction.",
   "type": "module",
   "exports": {
@@ -14,11 +14,11 @@
   ],
   "sideEffects": false,
   "devDependencies": {
-    "@vitest/coverage-v8": "^4.1.0",
-    "jsdom": "^28",
+    "@vitest/coverage-v8": "^4.1.2",
+    "jsdom": "^29.0.1",
     "tsup": "^8",
     "typescript": "^5",
-    "vitest": "^4",
+    "vitest": "^4.1.2",
     "@slithy/eslint-config": "0.0.0",
     "@slithy/tsconfig": "0.0.0"
   },