@pixerate/editor 0.204.0 → 0.206.0

package/dist/image-editor/index.js

@@ -4015,10 +4015,10 @@ function edgeWidth(guide, w, h, r) {
   for (let i = 0; i < n; i++) out[i] = (hi[i] - lo[i]) / Math.max(gm[i], 1e-4);
   return out;
 }
-function refineCoverage(guide, m, w, h, params = {}) {
+function refineCoverage(guide, m, w, h, params = {}, band = null) {
   const p = normalizeRefineEdgeParams(params);
   let a = Float32Array.from(m);
-  if (p.radius > 0 && guide) {
+  if ((p.radius > 0 || band) && guide) {
     const n = w * h;
     const boundary = new Uint8Array(n);
     let any = false;
@@ -4033,14 +4033,15 @@ function refineCoverage(guide, m, w, h, params = {}) {
         }
       }
     }
-    if (any) {
+    if (any || band) {
       const dist = distanceTransform(boundary, w, h);
-      const r = gfRadius(p);
+      const r = band ? Math.max(4, gfRadius(p)) : gfRadius(p);
       const q = guidedFilterColor(guide, m, w, h, r);
       const widths = p.smartRadius ? edgeWidth(guide, w, h, r) : null;
       for (let i = 0; i < n; i++) {
         const reff = widths ? Math.min(Math.max(p.radius, 1.5), Math.max(1.5, widths[i])) : p.radius;
-        const wgt = Math.min(1, Math.max(0, reff + 1 - dist[i]));
+        const edge = p.radius > 0 ? Math.min(1, Math.max(0, reff + 1 - dist[i])) : 0;
+        const wgt = band ? Math.max(edge, Math.min(1, Math.max(0, band[i]))) : edge;
         if (wgt > 0) {
           const qi = Math.min(1, Math.max(0, q[i]));
           a[i] = m[i] + (qi - m[i]) * wgt;
@@ -4081,17 +4082,24 @@ function guidePlanes(pixels, win) {
   }
   return [r, g, b];
 }
-function refineSelection(pixels, mask, params = {}) {
+function refineSelection(pixels, mask, params = {}, refineBrush = null) {
   const p = normalizeRefineEdgeParams(params);
   if (pixels && (pixels.width !== mask.width || pixels.height !== mask.height)) {
     throw new Error("Refine Edge needs pixels the size of the selection");
   }
   if (!mask.bounds) return mask;
-  const halo = refineEdgeHalo(p);
-  const x0 = Math.max(0, mask.bounds.x - halo);
-  const y0 = Math.max(0, mask.bounds.y - halo);
-  const x1 = Math.min(mask.width, mask.bounds.x + mask.bounds.width + halo);
-  const y1 = Math.min(mask.height, mask.bounds.y + mask.bounds.height + halo);
+  const brush = refineBrush?.bounds ? refineBrush : null;
+  const halo = refineEdgeHalo(p) + (brush ? 2 * Math.max(4, gfRadius(p)) : 0);
+  const b = brush ? {
+    x: Math.min(mask.bounds.x, brush.bounds.x),
+    y: Math.min(mask.bounds.y, brush.bounds.y),
+    r: Math.max(mask.bounds.x + mask.bounds.width, brush.bounds.x + brush.bounds.width),
+    btm: Math.max(mask.bounds.y + mask.bounds.height, brush.bounds.y + brush.bounds.height)
+  } : { x: mask.bounds.x, y: mask.bounds.y, r: mask.bounds.x + mask.bounds.width, btm: mask.bounds.y + mask.bounds.height };
+  const x0 = Math.max(0, b.x - halo);
+  const y0 = Math.max(0, b.y - halo);
+  const x1 = Math.min(mask.width, b.r + halo);
+  const y1 = Math.min(mask.height, b.btm + halo);
   const ww = x1 - x0;
   const wh = y1 - y0;
   const m = new Float32Array(ww * wh);
@@ -4099,8 +4107,17 @@ function refineSelection(pixels, mask, params = {}) {
     const src = (y0 + y) * mask.width + x0;
     for (let x = 0; x < ww; x++) m[y * ww + x] = mask.data[src + x] / 255;
   }
-  const guide = pixels && p.radius > 0 ? guidePlanes(pixels, { x: x0, y: y0, width: ww, height: wh }) : null;
-  const refined = refineCoverage(guide, m, ww, wh, p);
+  const guide = pixels && (p.radius > 0 || brush) ? guidePlanes(pixels, { x: x0, y: y0, width: ww, height: wh }) : null;
+  let band = null;
+  if (brush) {
+    band = new Float32Array(ww * wh);
+    const bd = brush.data;
+    for (let y = 0; y < wh; y++) {
+      const src = (y0 + y) * mask.width + x0;
+      for (let x = 0; x < ww; x++) band[y * ww + x] = bd[src + x] / 255;
+    }
+  }
+  const refined = refineCoverage(guide, m, ww, wh, p, band);
   const out = new Uint8Array(mask.width * mask.height);
   for (let y = 0; y < wh; y++) {
     const dst = (y0 + y) * mask.width + x0;
@@ -4108,6 +4125,49 @@ function refineSelection(pixels, mask, params = {}) {
   }
   return createSelectionMask(mask.width, mask.height, out);
 }
+function decontaminateColors(rgba, coverage, w, h, amount, radius = 8) {
+  const out = Uint8ClampedArray.from(rgba);
+  const n = w * h;
+  const k = Math.min(1, Math.max(0, amount));
+  if (k === 0) return out;
+  const r = Math.max(2, Math.round(radius));
+  const fgW = new Float32Array(n);
+  const bgW = new Float32Array(n);
+  for (let i = 0; i < n; i++) {
+    fgW[i] = coverage[i] >= 250 ? 1 : 0;
+    bgW[i] = coverage[i] <= 5 ? 1 : 0;
+  }
+  const meanOf = (weights, radiusPx) => {
+    const wm = boxMean(weights, w, h, radiusPx);
+    const planes = [0, 1, 2].map((c) => {
+      const v = new Float32Array(n);
+      for (let i = 0; i < n; i++) v[i] = rgba[i * 4 + c] * weights[i];
+      const m = boxMean(v, w, h, radiusPx);
+      for (let i = 0; i < n; i++) m[i] = wm[i] > 1e-6 ? m[i] / wm[i] : NaN;
+      return m;
+    });
+    return { weight: wm, planes };
+  };
+  const fg = meanOf(fgW, r);
+  const fgWide = meanOf(fgW, r * 3);
+  const bg = meanOf(bgW, r);
+  for (let i = 0; i < n; i++) {
+    const c = coverage[i];
+    if (c <= 5 || c >= 250) continue;
+    const a = c / 255;
+    for (let ch = 0; ch < 3; ch++) {
+      const C = rgba[i * 4 + ch];
+      const B = bg.planes[ch][i];
+      const Fm = Number.isNaN(fg.planes[ch][i]) ? fgWide.planes[ch][i] : fg.planes[ch][i];
+      let F;
+      if (a >= 0.5 && !Number.isNaN(B)) F = (C - (1 - a) * B) / a;
+      else if (!Number.isNaN(Fm)) F = Fm;
+      else F = C;
+      out[i * 4 + ch] = Math.round(C + k * (Math.min(255, Math.max(0, F)) - C));
+    }
+  }
+  return out;
+}
 
 // src/image-editor/selection/segment/guided.ts
 function workPlanes(work) {
@@ -5259,6 +5319,66 @@ function segmentsToSelection(width, height, results) {
   return out;
 }
 
+// src/image-editor/selection/refine-edits.ts
+var REFINE_EDIT_KINDS = ["quick-select", "brush", "refine-brush"];
+function brushStrokeMask(width, height, points, size, hardness = 1) {
+  const r = Math.max(0.5, size / 2);
+  const solid = r * Math.min(1, Math.max(0, hardness));
+  let x0 = Infinity, y0 = Infinity, x1 = -Infinity, y1 = -Infinity;
+  for (const p of points) {
+    x0 = Math.min(x0, p.x);
+    y0 = Math.min(y0, p.y);
+    x1 = Math.max(x1, p.x);
+    y1 = Math.max(y1, p.y);
+  }
+  const bx = Math.max(0, Math.floor(x0 - r - 1));
+  const by = Math.max(0, Math.floor(y0 - r - 1));
+  const bw = Math.min(width, Math.ceil(x1 + r + 1)) - bx;
+  const bh = Math.min(height, Math.ceil(y1 + r + 1)) - by;
+  if (!(bw > 0 && bh > 0)) return createSelectionMask(width, height);
+  const out = new Uint8Array(bw * bh);
+  const segs = points.length === 1 ? [[points[0], points[0]]] : points.slice(1).map((p, i) => [points[i], p]);
+  for (let y = 0; y < bh; y++) {
+    for (let x = 0; x < bw; x++) {
+      const px2 = bx + x + 0.5;
+      const py = by + y + 0.5;
+      let d = Infinity;
+      for (const [a, b] of segs) {
+        const dx = b.x - a.x;
+        const dy = b.y - a.y;
+        const len2 = dx * dx + dy * dy;
+        const t = len2 > 0 ? Math.min(1, Math.max(0, ((px2 - a.x) * dx + (py - a.y) * dy) / len2)) : 0;
+        d = Math.min(d, Math.hypot(px2 - a.x - t * dx, py - a.y - t * dy));
+      }
+      let v = d <= solid ? 1 : solid >= r ? 0 : 1 - (d - solid) / (r - solid);
+      v = Math.min(v, Math.min(1, Math.max(0, r + 0.5 - d)));
+      out[y * bw + x] = Math.round(Math.max(0, v) * 255);
+    }
+  }
+  return selectionFromRegion(width, height, { x: bx, y: by, width: bw, height: bh }, out);
+}
+function applyRefineEdits(pixels, selection, edits, width, height) {
+  let sel = selection?.bounds ? selection : null;
+  let band = null;
+  for (const e of edits) {
+    if (!e.points.length) throw new Error(`A ${e.kind} stroke needs at least one point.`);
+    if (e.kind === "refine-brush") {
+      band = combineSelections(band, brushStrokeMask(width, height, e.points, e.size ?? 40), "add");
+      continue;
+    }
+    const mode = e.mode ?? "add";
+    let region;
+    if (e.kind === "quick-select") {
+      if (!pixels) throw new Error("Quick Selection strokes need the image pixels.");
+      region = quickSelectStroke(pixels, e.points, { size: e.size, selection: sel, grow: mode === "add" });
+    } else {
+      region = brushStrokeMask(width, height, e.points, e.size ?? 20, e.hardness ?? 1);
+    }
+    sel = combineSelections(sel, region, mode);
+  }
+  return { selection: sel, refineBrush: band };
+}
+
 // src/image-editor/selection/stroke.ts
 function selectionRing(sel, width, location) {
   const half = location === "center" ? width / 2 : width;
@@ -10280,6 +10400,107 @@ var ImageEditorController = class {
     const pixels = (params.radius ?? 0) > 0 ? await this.requirePixels(options) : null;
     return this.setSelection(refineSelection(pixels, sel, params));
   }
+  /**
+   * Select and Mask's output: refines the selection with `params`, then puts the result where
+   * `output` says, as one undo step:
+   * - `selection`: the refined selection;
+   * - `layer-mask`: a mask on the layer (`layerId`, default the active one), then deselects;
+   * - `new-layer`: a new layer of the layer's selected pixels (Layer via Copy), the source hidden;
+   * - `new-layer-with-mask`: a copy of the layer masked by the selection, the source hidden.
+   * `decontaminate` (0..100, new-layer outputs only) replaces the old background's colour in the
+   * soft edge with the subject's own (see `decontaminateColors`).
+   *
+   * `edits` are the workspace's strokes, applied first in order (Quick Selection, Brush and
+   * Refine Edge Brush; see `RefineEdit`); with them, an empty selection is a valid start.
+   * `refineMode: 'object'` asks the segmentation provider for the object in the selection's
+   * bounds and refines from its outline, kept to near the selection's edge.
+   */
+  async refineSelectionTo(params, output = "selection", options = {}) {
+    const edits = options.edits ?? [];
+    const refineMode = options.refineMode ?? "color";
+    if (!this.state.selection?.bounds && !edits.length) throw new Error("Nothing is selected; select first, or pass edits that paint a selection.");
+    if (refineMode === "object" && !this.segmentation) {
+      throw new Error("Object aware refinement needs a segmentation model (setSegmentationProvider); use refineMode color.");
+    }
+    const amount = Math.min(100, Math.max(0, options.decontaminate ?? 0)) / 100;
+    const toLayer = output === "new-layer" || output === "new-layer-with-mask";
+    if (amount > 0 && !toLayer) throw new Error("Decontaminate colors writes the cleaned colours to a new layer: use output new-layer or new-layer-with-mask.");
+    let layerId;
+    if (output !== "selection") {
+      layerId = options.layerId ?? this.state.activeLayerId ?? void 0;
+      if (!layerId) throw new LayerOperationError("No layer given and none is active; pass layerId (see list_layers).");
+      const layer = requireLayer(this.state.layers, layerId).layer;
+      if (toLayer && layer.type !== "pixel") throw new LayerOperationError(`Output ${output} needs a pixel layer; "${layerId}" is a ${layer.type} layer.`);
+    }
+    const needsPixels = (params.radius ?? 0) > 0 || edits.some((e) => e.kind !== "brush");
+    const pixels = needsPixels ? await this.requirePixels(options) : null;
+    const { width, height } = this.naturalSize;
+    const edited = applyRefineEdits(pixels, this.state.selection ?? null, edits, width, height);
+    let sel = edited.selection;
+    if (!sel?.bounds) throw new Error("The edits leave nothing selected; paint with mode add first.");
+    if (refineMode === "object") {
+      const b = sel.bounds;
+      const found = await this.modelObject({ rect: b }, options.signal);
+      if (!found) throw new Error("The segmentation model found no object in the selection; use refineMode color.");
+      const near = modifySelection(sel, "expand", Math.max(4, params.radius ?? 8));
+      const clipped = combineSelections(found, near, "intersect");
+      if (!clipped?.bounds) throw new Error("The segmentation model found no object in the selection; use refineMode color.");
+      sel = clipped;
+    }
+    const refined = refineSelection(pixels, sel, params, edited.refineBrush);
+    if (!refined.bounds) throw new Error("Refining left nothing selected; use a smaller shiftEdge or contrast.");
+    return this.asOneStep(() => {
+      this.setSelection(refined);
+      if (output === "selection") return { output, refineMode };
+      if (output === "layer-mask") {
+        this.addLayerMask(layerId, "selection");
+        this.setSelection(null);
+        return { output, layerId, refineMode };
+      }
+      let newLayerId2;
+      if (output === "new-layer") newLayerId2 = this.layerViaCopy({ layerId });
+      else {
+        newLayerId2 = this.duplicateLayer(layerId);
+        this.addLayerMask(newLayerId2, "selection");
+        this.state.activeTarget = "pixels";
+      }
+      if (amount > 0) this.decontaminateLayer(newLayerId2, layerId, refined, amount, Math.max(4, params.radius ?? 0));
+      this.setLayerProperties(layerId, { visible: false });
+      this.setSelection(null);
+      return { output, layerId, newLayerId: newLayerId2, refineMode };
+    });
+  }
+  /**
+   * Decontaminate Colors along the soft edge of `coverage`: the colours are estimated from the
+   * source layer (whose background is still there) and written into layer `id`'s RGB, keeping
+   * its alpha.
+   */
+  decontaminateLayer(id, sourceId, coverage, amount, radius) {
+    const layer = requireLayer(this.state.layers, id).layer;
+    const source = requireLayer(this.state.layers, sourceId).layer;
+    if (layer.type !== "pixel" || source.type !== "pixel" || !coverage.bounds) return;
+    const { width, height } = this.naturalSize;
+    const pad = Math.ceil(radius * 3);
+    const b = coverage.bounds;
+    const x0 = Math.max(0, b.x - pad);
+    const y0 = Math.max(0, b.y - pad);
+    const box = { x: x0, y: y0, width: Math.min(width, b.x + b.width + pad) - x0, height: Math.min(height, b.y + b.height + pad) - y0 };
+    const src = { x: box.x - layer.offset.x, y: box.y - layer.offset.y, width: box.width, height: box.height };
+    const surface = this.surfaceOf(layer);
+    const rgba = readRegion(surface, src);
+    const original = readRegion(this.surfaceOf(source), { x: box.x - source.offset.x, y: box.y - source.offset.y, width: box.width, height: box.height });
+    const cov = new Uint8Array(box.width * box.height);
+    const all = coverage.data;
+    for (let y = 0; y < box.height; y++) cov.set(all.subarray((box.y + y) * width + box.x, (box.y + y) * width + box.x + box.width), y * box.width);
+    const cleaned = decontaminateColors(original, cov, box.width, box.height, amount, radius);
+    for (let i = 3; i < cleaned.length; i += 4) cleaned[i] = rgba[i];
+    const next = mapLayer(this.state.layers, id, (l) => {
+      const updated = { ...l, surface: writeRegion(surface, src, cleaned) };
+      delete updated.source;
+      return updated;
+    });
+    this.commitLayers(next);
+  }
   /**
    * Loads a selection from a mask image (an AI segmentation, a saved mask): a data URL / URL or
    * RGBA pixels, by luminance (white = selected) or a channel. Any size; it is resampled.
@@ -13251,6 +13472,12 @@ var REFINE_EDGE_CONTROLS = [
   { id: "contrast", label: "Contrast", min: 0, max: 100, step: 1, unit: "%" },
   { id: "shiftEdge", label: "Shift Edge", min: -100, max: 100, step: 1, unit: "%" }
 ];
+var REFINE_OUTPUTS = [
+  { id: "selection", label: "Selection" },
+  { id: "layer-mask", label: "Layer Mask" },
+  { id: "new-layer", label: "New Layer" },
+  { id: "new-layer-with-mask", label: "New Layer with Layer Mask" }
+];
 function describeSelection(mask) {
   if (!mask || !mask.bounds) return "No selection";
   const pct2 = selectionArea(mask) / (mask.width * mask.height) * 100;
@@ -13459,31 +13686,69 @@ function createImageSelectionTools(controller) {
   const refine = {
     name: "refine_selection",
     title: "Refine the selection edge",
-    description: "Refine Edge: snaps the selection edge to the image within radius pixels (edge-aware guided filter), then smooth (0-100), feather (px), contrast (0-100) and shiftEdge (-100..100 %). Use it after loading a coarse AI mask. One undoable step.",
+    description: "Select and Mask / Refine Edge: snaps the selection edge to the image within radius pixels (edge-aware guided filter), then smooth (0-100), feather (px), contrast (0-100) and shiftEdge (-100..100 %), and puts the result where output says: the selection (default), a layer-mask on layerId (default the active layer; then deselects), a new-layer of its selected pixels, or a new-layer-with-mask (a masked copy); the new-layer outputs hide the source layer. decontaminate (0-100, new-layer outputs only) replaces the old background colour in soft edges (hair, fur) with the subject's own. Use it after loading a coarse AI mask, or to cut a subject out cleanly. edits are the Select and Mask workspace's strokes, applied first in order: quick-select (grows to the region's edges), brush (paints the selection in or out) and refine-brush (marks hair or fur for the edge to be re-estimated there); with edits, an empty selection is a valid start. refineMode object (needs a host segmentation model) refines from the model's outline of the object. One undoable step. Returns the selection, refineMode and, for layer outputs, layerId and newLayerId.",
     inputSchema: {
       type: "object",
       properties: {
-        radius: { type: "number", minimum: 0, maximum: 64, description: "Edge detection radius in pixels." },
+        radius: { type: "number", minimum: 0, maximum: 64, description: "Edge detection radius in pixels (default 8)." },
         smartRadius: { type: "boolean", description: "Adapt the radius to hard and soft edges." },
         smooth: { type: "number", minimum: 0, maximum: 100, description: "Smooth the edge outline (0-100)." },
         feather: { type: "number", minimum: 0, maximum: 250, description: "Feather the edge (pixels)." },
         contrast: { type: "number", minimum: 0, maximum: 100, description: "Sharpen the edge transition (0-100)." },
-        shiftEdge: { type: "number", minimum: -100, maximum: 100, description: "Move the edge out (+) or in (-), in percent." }
+        shiftEdge: { type: "number", minimum: -100, maximum: 100, description: "Move the edge out (+) or in (-), in percent." },
+        output: {
+          type: "string",
+          enum: ["selection", "layer-mask", "new-layer", "new-layer-with-mask"],
+          description: "Where the result goes (default selection). layer-mask keeps every pixel and is easiest to revise; new-layer-with-mask too, on a copy."
+        },
+        layerId: { type: "string", description: "The layer for layer outputs (default the active layer; see list_layers). New-layer outputs need a pixel layer." },
+        decontaminate: { type: "number", minimum: 0, maximum: 100, description: "Decontaminate Colors amount 0-100 (default 0), only with output new-layer or new-layer-with-mask." },
+        edits: {
+          type: "array",
+          description: "Strokes applied before refining, in order.",
+          items: {
+            type: "object",
+            properties: {
+              kind: { type: "string", enum: ["quick-select", "brush", "refine-brush"], description: "quick-select grows to edges; brush paints directly; refine-brush marks soft detail (hair) for the edge to be re-estimated." },
+              points: { type: "array", minItems: 1, items: pointSchema, description: "The stroke path in natural image pixels (one point is a dab)." },
+              size: { type: "number", minimum: 1, maximum: 2500, description: "Brush diameter in natural image pixels (default 30 quick-select, 20 brush, 40 refine-brush)." },
+              mode: { type: "string", enum: ["add", "subtract"], description: "quick-select and brush: add (default) or subtract." },
+              hardness: { type: "number", minimum: 0, maximum: 1, description: "brush: the solid share of the radius, 0..1 (default 1)." }
+            },
+            required: ["kind", "points"],
+            additionalProperties: false
+          }
+        },
+        refineMode: { type: "string", enum: ["color", "object"], description: "color (default): refine from the image colours; object: from a host segmentation model's outline of the object (needs a model)." }
       },
       additionalProperties: false
     },
     annotations: writeAnnotations("Refine the selection edge"),
     handler: async (params) => {
-      if (!controller.getSelection()) throw new Error("Nothing is selected.");
-      await controller.refineSelection({
-        radius: num2(params.radius, 8),
-        smartRadius: params.smartRadius === true,
-        smooth: num2(params.smooth, 0),
-        feather: num2(params.feather, 0),
-        contrast: num2(params.contrast, 0),
-        shiftEdge: num2(params.shiftEdge, 0)
-      });
-      return summary(controller);
+      const edits = Array.isArray(params.edits) ? params.edits.map((e) => ({ ...e, points: (e.points ?? []).map((p) => ({ x: num2(p?.x, NaN), y: num2(p?.y, NaN) })) })) : [];
+      for (const e of edits) {
+        if (!e.points.every((p) => Number.isFinite(p.x) && Number.isFinite(p.y))) throw new Error("Each edit needs points of { x, y } in natural image pixels.");
+        if (e.kind === "refine-brush" && e.mode !== void 0) throw new Error("refine-brush strokes have no mode; they mark where the edge is re-estimated.");
+      }
+      if (!controller.getSelection() && !edits.length) throw new Error("Nothing is selected.");
+      const result = await controller.refineSelectionTo(
+        {
+          radius: num2(params.radius, 8),
+          smartRadius: params.smartRadius === true,
+          smooth: num2(params.smooth, 0),
+          feather: num2(params.feather, 0),
+          contrast: num2(params.contrast, 0),
+          shiftEdge: num2(params.shiftEdge, 0)
+        },
+        params.output ?? "selection",
+        {
+          layerId: typeof params.layerId === "string" ? params.layerId : void 0,
+          decontaminate: num2(params.decontaminate, 0),
+          edits,
+          refineMode: params.refineMode === "object" ? "object" : "color"
+        }
+      );
+      return { ...summary(controller), ...result };
     }
   };
   const applyMask = {
@@ -20702,6 +20967,8 @@ export {
   PsdError,
   QUICK_MASK_TARGET,
   REFINE_EDGE_CONTROLS,
+  REFINE_EDIT_KINDS,
+  REFINE_OUTPUTS,
   RETOUCH_CHOICES,
   RETOUCH_OPTION_CONTROLS,
   RETOUCH_SAMPLES,
@@ -20813,6 +21080,7 @@ export {
   applyParams,
   applyProcess2Adjustments,
   applyProcess2Float,
+  applyRefineEdits,
   applyRegionBlur,
   applyRegionMosaic,
   applyRetouchToTile,
@@ -20845,6 +21113,7 @@ export {
   boxQuad,
   boxToCurvePoint,
   bradfordAdaptation,
+  brushStrokeMask,
   brushstrokeDataUrl,
   brushstrokeKey,
   brushstrokeSamples,
@@ -20950,6 +21219,7 @@ export {
   decodePng,
   decodePngDataUrl,
   decodeSelectionRle,
+  decontaminateColors,
   deepBytes,
   deepTile,
   defaultActiveLayerId,

package/dist/image-editor/selection/index.d.cts

@@ -14,3 +14,4 @@ export * from './mask-files.cjs';
 export * from './path.cjs';
 export * from './magnetic.cjs';
 export * from './segment/index.cjs';
+export * from './refine-edits.cjs';

package/dist/image-editor/selection/index.d.ts

@@ -14,3 +14,4 @@ export * from './mask-files.js';
 export * from './path.js';
 export * from './magnetic.js';
 export * from './segment/index.js';
+export * from './refine-edits.js';

package/dist/image-editor/selection/refine-edits.d.cts

@@ -0,0 +1,41 @@
+/**
+ * The Select and Mask workspace's strokes as plain data, so an agent can send what a person
+ * paints: Quick Selection strokes (grow to the region's edges), Brush strokes (paint the
+ * selection in or out directly) and Refine Edge Brush strokes (mark where the edge should be
+ * re-estimated from the image, e.g. over hair).
+ */
+import type { ImagePoint } from '../types.cjs';
+import { type PixelBuffer, type SelectionMask } from './mask.cjs';
+/** One stroke in the workspace, in natural image pixels. */
+export type RefineEdit = {
+    kind: 'quick-select';
+    points: ImagePoint[];
+    size?: number;
+    mode?: 'add' | 'subtract';
+} | {
+    kind: 'brush';
+    points: ImagePoint[];
+    size?: number;
+    mode?: 'add' | 'subtract';
+    hardness?: number;
+} | {
+    kind: 'refine-brush';
+    points: ImagePoint[];
+    size?: number;
+};
+export declare const REFINE_EDIT_KINDS: readonly ["quick-select", "brush", "refine-brush"];
+/**
+ * Coverage of a round brush of diameter `size` dragged along `points` (one point is a dab), over
+ * a `width × height` image. `hardness` 0..1 (default 1): the solid share of the radius; the rest
+ * fades out. The edge is anti-aliased either way.
+ */
+export declare function brushStrokeMask(width: number, height: number, points: readonly ImagePoint[], size: number, hardness?: number): SelectionMask;
+/**
+ * Applies `edits` in order to `selection` (`null` starts empty) over `pixels` (needed for
+ * Quick Selection strokes). Returns the edited selection and the Refine Edge Brush's painted
+ * area (`null` when there were no such strokes), for `refineSelection`.
+ */
+export declare function applyRefineEdits(pixels: PixelBuffer | null, selection: SelectionMask | null, edits: readonly RefineEdit[], width: number, height: number): {
+    selection: SelectionMask | null;
+    refineBrush: SelectionMask | null;
+};

package/dist/image-editor/selection/refine-edits.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The Select and Mask workspace's strokes as plain data, so an agent can send what a person
+ * paints: Quick Selection strokes (grow to the region's edges), Brush strokes (paint the
+ * selection in or out directly) and Refine Edge Brush strokes (mark where the edge should be
+ * re-estimated from the image, e.g. over hair).
+ */
+import type { ImagePoint } from '../types.js';
+import { type PixelBuffer, type SelectionMask } from './mask.js';
+/** One stroke in the workspace, in natural image pixels. */
+export type RefineEdit = {
+    kind: 'quick-select';
+    points: ImagePoint[];
+    size?: number;
+    mode?: 'add' | 'subtract';
+} | {
+    kind: 'brush';
+    points: ImagePoint[];
+    size?: number;
+    mode?: 'add' | 'subtract';
+    hardness?: number;
+} | {
+    kind: 'refine-brush';
+    points: ImagePoint[];
+    size?: number;
+};
+export declare const REFINE_EDIT_KINDS: readonly ["quick-select", "brush", "refine-brush"];
+/**
+ * Coverage of a round brush of diameter `size` dragged along `points` (one point is a dab), over
+ * a `width × height` image. `hardness` 0..1 (default 1): the solid share of the radius; the rest
+ * fades out. The edge is anti-aliased either way.
+ */
+export declare function brushStrokeMask(width: number, height: number, points: readonly ImagePoint[], size: number, hardness?: number): SelectionMask;
+/**
+ * Applies `edits` in order to `selection` (`null` starts empty) over `pixels` (needed for
+ * Quick Selection strokes). Returns the edited selection and the Refine Edge Brush's painted
+ * area (`null` when there were no such strokes), for `refineSelection`.
+ */
+export declare function applyRefineEdits(pixels: PixelBuffer | null, selection: SelectionMask | null, edits: readonly RefineEdit[], width: number, height: number): {
+    selection: SelectionMask | null;
+    refineBrush: SelectionMask | null;
+};

package/dist/image-editor/selection/refine.d.cts

@@ -42,10 +42,12 @@ export declare function guidedFilterColor(guide: readonly [Float32Array, Float32
 export declare function edgeWidth(guide: readonly [Float32Array, Float32Array, Float32Array], w: number, h: number, r: number): Float32Array;
 /**
  * Refines soft coverage `m` (`w × h`, 0..1) with `guide` (three 0..1 planes, required when
- * `radius > 0`): edge-aware re-estimation in a band around the edge, then smooth, feather,
- * contrast and shift edge, in that order.
+ * `radius > 0` or a `band` is given): edge-aware re-estimation in a band around the edge, then
+ * smooth, feather, contrast and shift edge, in that order. `band` (0..1 per pixel, the Refine
+ * Edge Brush) adds to the band where it is painted, so hair or fur far from the edge is
+ * re-estimated too.
  */
-export declare function refineCoverage(guide: readonly [Float32Array, Float32Array, Float32Array] | null, m: Float32Array, w: number, h: number, params?: RefineEdgeParams): Float32Array;
+export declare function refineCoverage(guide: readonly [Float32Array, Float32Array, Float32Array] | null, m: Float32Array, w: number, h: number, params?: RefineEdgeParams, band?: ArrayLike<number> | null): Float32Array;
 /** Three 0..1 planes of a window of an RGBA buffer. */
 export declare function guidePlanes(pixels: PixelBuffer, win?: CropBox): [Float32Array, Float32Array, Float32Array];
 /**
@@ -53,4 +55,13 @@ export declare function guidePlanes(pixels: PixelBuffer, win?: CropBox): [Float3
  * same size). Work is confined to the mask's bounds grown by {@link refineEdgeHalo}, so a small
  * selection on a large image stays cheap.
  */
-export declare function refineSelection(pixels: PixelBuffer | null, mask: SelectionMask, params?: RefineEdgeParams): SelectionMask;
+export declare function refineSelection(pixels: PixelBuffer | null, mask: SelectionMask, params?: RefineEdgeParams, refineBrush?: SelectionMask | null): SelectionMask;
+/**
+ * Decontaminate Colors: along a soft edge, a pixel's colour is part subject and part the old
+ * background (C = αF + (1 − α)B), which shows as a fringe once the subject is on a new background.
+ * Each edge pixel's colour is replaced (by `amount`, 0..1) with an estimate of the subject's own
+ * colour: unmixed from the background's local mean where the pixel is mostly subject, and the
+ * subject's local mean where it is mostly background. Only RGB changes; pixels fully in or out
+ * are kept. `rgba` and `coverage` (0..255) cover the same `w × h` region; returns new RGBA.
+ */
+export declare function decontaminateColors(rgba: ArrayLike<number>, coverage: ArrayLike<number>, w: number, h: number, amount: number, radius?: number): Uint8ClampedArray;

package/dist/image-editor/selection/refine.d.ts

@@ -42,10 +42,12 @@ export declare function guidedFilterColor(guide: readonly [Float32Array, Float32
 export declare function edgeWidth(guide: readonly [Float32Array, Float32Array, Float32Array], w: number, h: number, r: number): Float32Array;
 /**
  * Refines soft coverage `m` (`w × h`, 0..1) with `guide` (three 0..1 planes, required when
- * `radius > 0`): edge-aware re-estimation in a band around the edge, then smooth, feather,
- * contrast and shift edge, in that order.
+ * `radius > 0` or a `band` is given): edge-aware re-estimation in a band around the edge, then
+ * smooth, feather, contrast and shift edge, in that order. `band` (0..1 per pixel, the Refine
+ * Edge Brush) adds to the band where it is painted, so hair or fur far from the edge is
+ * re-estimated too.
  */
-export declare function refineCoverage(guide: readonly [Float32Array, Float32Array, Float32Array] | null, m: Float32Array, w: number, h: number, params?: RefineEdgeParams): Float32Array;
+export declare function refineCoverage(guide: readonly [Float32Array, Float32Array, Float32Array] | null, m: Float32Array, w: number, h: number, params?: RefineEdgeParams, band?: ArrayLike<number> | null): Float32Array;
 /** Three 0..1 planes of a window of an RGBA buffer. */
 export declare function guidePlanes(pixels: PixelBuffer, win?: CropBox): [Float32Array, Float32Array, Float32Array];
 /**
@@ -53,4 +55,13 @@ export declare function guidePlanes(pixels: PixelBuffer, win?: CropBox): [Float3
  * same size). Work is confined to the mask's bounds grown by {@link refineEdgeHalo}, so a small
  * selection on a large image stays cheap.
  */
-export declare function refineSelection(pixels: PixelBuffer | null, mask: SelectionMask, params?: RefineEdgeParams): SelectionMask;
+export declare function refineSelection(pixels: PixelBuffer | null, mask: SelectionMask, params?: RefineEdgeParams, refineBrush?: SelectionMask | null): SelectionMask;
+/**
+ * Decontaminate Colors: along a soft edge, a pixel's colour is part subject and part the old
+ * background (C = αF + (1 − α)B), which shows as a fringe once the subject is on a new background.
+ * Each edge pixel's colour is replaced (by `amount`, 0..1) with an estimate of the subject's own
+ * colour: unmixed from the background's local mean where the pixel is mostly subject, and the
+ * subject's local mean where it is mostly background. Only RGB changes; pixels fully in or out
+ * are kept. `rgba` and `coverage` (0..255) cover the same `w × h` region; returns new RGBA.
+ */
+export declare function decontaminateColors(rgba: ArrayLike<number>, coverage: ArrayLike<number>, w: number, h: number, amount: number, radius?: number): Uint8ClampedArray;

package/dist/image-editor/selection/tool-options.d.cts

@@ -79,5 +79,10 @@ export interface RefineEdgeControl {
 }
 /** Sliders of the Refine Edge panel. */
 export declare const REFINE_EDGE_CONTROLS: readonly RefineEdgeControl[];
+/** Select and Mask's outputs, in menu order. */
+export declare const REFINE_OUTPUTS: readonly {
+    id: 'selection' | 'layer-mask' | 'new-layer' | 'new-layer-with-mask';
+    label: string;
+}[];
 /** A one-line status: "No selection" or "W × H px selected (n % of the image)". */
 export declare function describeSelection(mask: SelectionMask | null | undefined): string;

package/dist/image-editor/selection/tool-options.d.ts

@@ -79,5 +79,10 @@ export interface RefineEdgeControl {
 }
 /** Sliders of the Refine Edge panel. */
 export declare const REFINE_EDGE_CONTROLS: readonly RefineEdgeControl[];
+/** Select and Mask's outputs, in menu order. */
+export declare const REFINE_OUTPUTS: readonly {
+    id: 'selection' | 'layer-mask' | 'new-layer' | 'new-layer-with-mask';
+    label: string;
+}[];
 /** A one-line status: "No selection" or "W × H px selected (n % of the image)". */
 export declare function describeSelection(mask: SelectionMask | null | undefined): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixerate/editor",
-  "version": "0.204.0",
+  "version": "0.206.0",
   "description": "UI-agnostic rich text and media editing core library",
   "author": "Pixerate",
   "license": "MIT",

package/skills/pixerate-image-editor/SKILL.md

@@ -269,7 +269,7 @@ in the source frame at the document's bit depth, colour mode and profile. Read
 | `grow_selection` | Select › Grow: add connected pixels within `tolerance` (default 32) of a selected colour; follows colour, not distance. `sample`, `sampleMerged`. Fails when nothing is selected. Returns the summary. |
 | `select_similar` | Select › Similar: add every pixel in the image within `tolerance` of a selected colour, connected or not. Fails when nothing is selected. Returns the summary. |
 | `reselect` | Bring back the last selection `deselect` cleared (one undo step). Fails when there is none. Returns the summary. |
-| `refine_selection` | Select and Mask: snap the selection edge to image edges within `radius` px (0..64, default 8), with `smartRadius`, `smooth` 0..100, `feather` px, `contrast` 0..100 and `shiftEdge` -100..100 %, then `output` to `selection` (default), `layer-mask`, `new-layer` or `new-layer-with-mask` (on `layerId`, default active; new layers hide the source), with `decontaminate` 0..100 for new layers. One step; returns `layerId` / `newLayerId`. Use on hair, fur, foliage or after a coarse AI mask. |
+| `refine_selection` | Select and Mask: snap the selection edge to image edges within `radius` px (0..64, default 8), with `smartRadius`, `smooth` 0..100, `feather` px, `contrast` 0..100 and `shiftEdge` -100..100 %, then `output` to `selection` (default), `layer-mask`, `new-layer` or `new-layer-with-mask` (on `layerId`, default active; new layers hide the source), with `decontaminate` 0..100 for new layers. `edits` (`quick-select`, `brush` add/subtract, `refine-brush` over hair) apply first; `refineMode: "object"` uses the host model. One step; returns `refineMode`, `layerId` / `newLayerId`. Use on hair, fur, foliage or a coarse AI mask. |
 | `update_adjustment_layer` | Change a layer's `enabled` (false hides it without deleting), `blend`, `opacity` (0..1) or `name` in one undo step. Returns the layer. Its parameters change with `set_adjustments`. Toggle `enabled` to compare a layer's effect before and after. |
 | `move_adjustment_layer` | Move a layer to index `to` (0 = bottom, applied first; past the top means top). Order matters: a curves layer above a hue/saturation layer works on its output. Fails when the layer is already there. Returns the ids bottom to top. |
 | `remove_adjustment_layer` | Delete a layer and its mask. Prefer hiding it with `update_adjustment_layer` when the user may want it back. Returns the remaining ids. |