@pixerate/editor 0.198.0 → 0.199.0

package/dist/image-editor/index.js

@@ -3672,6 +3672,209 @@ function selectObjectIn(pixels, target, options = {}) {
   }
 }
 
+// src/image-editor/selection/segment/subject.ts
+function toLab(r, g, b) {
+  const lin = (v) => {
+    v /= 255;
+    return v <= 0.04045 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
+  };
+  const R = lin(r);
+  const G = lin(g);
+  const B = lin(b);
+  const f = (t) => t > 8856e-6 ? Math.cbrt(t) : 7.787 * t + 16 / 116;
+  const x = f((0.4124 * R + 0.3576 * G + 0.1805 * B) / 0.95047);
+  const y = f(0.2126 * R + 0.7152 * G + 0.0722 * B);
+  const z = f((0.0193 * R + 0.1192 * G + 0.9505 * B) / 1.08883);
+  return [116 * y - 16, 500 * (x - y), 200 * (y - z)];
+}
+function slicSuperpixels(work, target = 400, compactness = 10, rounds = 5) {
+  const { width: w, height: h, rgb } = work;
+  const n = w * h;
+  const lab = new Float32Array(n * 3);
+  for (let i = 0; i < n; i++) lab.set(toLab(rgb[i * 3], rgb[i * 3 + 1], rgb[i * 3 + 2]), i * 3);
+  const S = Math.max(2, Math.round(Math.sqrt(n / target)));
+  const seeds = [];
+  for (let y = Math.floor(S / 2); y < h; y += S) {
+    for (let x = Math.floor(S / 2); x < w; x += S) {
+      const i = y * w + x;
+      seeds.push([lab[i * 3], lab[i * 3 + 1], lab[i * 3 + 2], x, y]);
+    }
+  }
+  const k = seeds.length;
+  const label = new Int32Array(n).fill(-1);
+  const best = new Float64Array(n);
+  const m2 = (compactness / S) ** 2;
+  for (let round6 = 0; round6 < rounds; round6++) {
+    best.fill(Infinity);
+    for (let c = 0; c < k; c++) {
+      const [L, A, B, cx, cy] = seeds[c];
+      const x0 = Math.max(0, Math.floor(cx - S));
+      const x1 = Math.min(w - 1, Math.ceil(cx + S));
+      const y0 = Math.max(0, Math.floor(cy - S));
+      const y1 = Math.min(h - 1, Math.ceil(cy + S));
+      for (let y = y0; y <= y1; y++) {
+        for (let x = x0; x <= x1; x++) {
+          const i = y * w + x;
+          const d = (lab[i * 3] - L) ** 2 + (lab[i * 3 + 1] - A) ** 2 + (lab[i * 3 + 2] - B) ** 2 + m2 * ((x - cx) ** 2 + (y - cy) ** 2);
+          if (d < best[i]) {
+            best[i] = d;
+            label[i] = c;
+          }
+        }
+      }
+    }
+    const sum = new Float64Array(k * 6);
+    for (let i = 0; i < n; i++) {
+      const c = label[i];
+      sum[c * 6] += lab[i * 3];
+      sum[c * 6 + 1] += lab[i * 3 + 1];
+      sum[c * 6 + 2] += lab[i * 3 + 2];
+      sum[c * 6 + 3] += i % w;
+      sum[c * 6 + 4] += Math.floor(i / w);
+      sum[c * 6 + 5]++;
+    }
+    for (let c = 0; c < k; c++) {
+      const s = sum[c * 6 + 5];
+      if (s) seeds[c] = [sum[c * 6] / s, sum[c * 6 + 1] / s, sum[c * 6 + 2] / s, sum[c * 6 + 3] / s, sum[c * 6 + 4] / s];
+    }
+  }
+  const remap = new Int32Array(k).fill(-1);
+  let count = 0;
+  for (let i = 0; i < n; i++) if (remap[label[i]] < 0) remap[label[i]] = count++;
+  const meanLab = new Float64Array(count * 3);
+  const centre = new Float64Array(count * 2);
+  const size = new Int32Array(count);
+  for (let i = 0; i < n; i++) {
+    const c = label[i] = remap[label[i]];
+    meanLab[c * 3] += lab[i * 3];
+    meanLab[c * 3 + 1] += lab[i * 3 + 1];
+    meanLab[c * 3 + 2] += lab[i * 3 + 2];
+    centre[c * 2] += i % w;
+    centre[c * 2 + 1] += Math.floor(i / w);
+    size[c]++;
+  }
+  for (let c = 0; c < count; c++) {
+    for (let j = 0; j < 3; j++) meanLab[c * 3 + j] /= size[c];
+    centre[c * 2] /= size[c];
+    centre[c * 2 + 1] /= size[c];
+  }
+  return { label, count, lab: meanLab, centre, size };
+}
+function superpixelSaliency(sp, width, height) {
+  const { count, lab, centre, size, label } = sp;
+  const dist = (a, b) => Math.hypot(lab[a * 3] - lab[b * 3], lab[a * 3 + 1] - lab[b * 3 + 1], lab[a * 3 + 2] - lab[b * 3 + 2]);
+  const onBorder = new Uint8Array(count);
+  for (let x = 0; x < width; x++) {
+    onBorder[label[x]] = 1;
+    onBorder[label[(height - 1) * width + x]] = 1;
+  }
+  for (let y = 0; y < height; y++) {
+    onBorder[label[y * width]] = 1;
+    onBorder[label[y * width + width - 1]] = 1;
+  }
+  const border = [];
+  for (let c = 0; c < count; c++) if (onBorder[c]) border.push(c);
+  const diag = Math.hypot(width, height);
+  const unlikeBorder = new Float64Array(count);
+  const contrast = new Float64Array(count);
+  const centreBias = new Float64Array(count);
+  for (let i = 0; i < count; i++) {
+    const ds = border.map((j) => dist(i, j)).sort((a, b) => a - b);
+    unlikeBorder[i] = ds.length ? ds[Math.floor(ds.length * 0.25)] : 0;
+    let s = 0;
+    let wsum = 0;
+    for (let j = 0; j < count; j++) {
+      if (j === i) continue;
+      const dx = (centre[i * 2] - centre[j * 2]) / diag;
+      const dy = (centre[i * 2 + 1] - centre[j * 2 + 1]) / diag;
+      const wgt = size[j] * Math.exp(-(dx * dx + dy * dy) / (2 * 0.25 * 0.25));
+      s += wgt * dist(i, j);
+      wsum += wgt;
+    }
+    contrast[i] = wsum ? s / wsum : 0;
+    const cx = centre[i * 2] / width - 0.5;
+    const cy = centre[i * 2 + 1] / height - 0.5;
+    centreBias[i] = 0.4 + 0.6 * Math.exp(-(cx * cx + cy * cy) / (2 * 0.3 * 0.3));
+  }
+  let farthest = 0;
+  for (const v of unlikeBorder) farthest = Math.max(farthest, v);
+  if (farthest < 6) return new Float64Array(count);
+  const norm = (a) => {
+    let max = 0;
+    for (const v of a) max = Math.max(max, v);
+    if (max > 0) for (let i = 0; i < a.length; i++) a[i] /= max;
+  };
+  norm(unlikeBorder);
+  norm(contrast);
+  const out = new Float64Array(count);
+  for (let i = 0; i < count; i++) out[i] = unlikeBorder[i] * (0.3 + 0.7 * contrast[i]) * centreBias[i];
+  norm(out);
+  return out;
+}
+function otsuThreshold(values, weights) {
+  const BINS2 = 64;
+  const hist = new Float64Array(BINS2);
+  let total = 0;
+  for (let i = 0; i < values.length; i++) {
+    hist[Math.min(BINS2 - 1, Math.floor(values[i] * BINS2))] += weights[i];
+    total += weights[i];
+  }
+  let sumAll = 0;
+  for (let b = 0; b < BINS2; b++) sumAll += b * hist[b];
+  let wB = 0;
+  let sumB = 0;
+  let best = 0;
+  let bestT = 0.5;
+  for (let b = 0; b < BINS2 - 1; b++) {
+    wB += hist[b];
+    if (!wB) continue;
+    const wF = total - wB;
+    if (!wF) break;
+    sumB += b * hist[b];
+    const between = wB * wF * (sumB / wB - (sumAll - sumB) / wF) ** 2;
+    if (between > best) {
+      best = between;
+      bestT = (b + 1) / BINS2;
+    }
+  }
+  return bestT;
+}
+function findSubject(pixels, options = {}) {
+  const work = workImage(pixels);
+  const { width: w, height: h } = work;
+  const sp = slicSuperpixels(work);
+  const sal = superpixelSaliency(sp, w, h);
+  const t = otsuThreshold(sal, sp.size);
+  const n = w * h;
+  const initial = new Uint8Array(n);
+  const hardBg = new Uint8Array(n);
+  const hardFg = new Uint8Array(n);
+  const strong = t + 0.6 * (1 - t);
+  for (let i = 0; i < n; i++) {
+    const s = sal[sp.label[i]];
+    if (s >= t) initial[i] = 1;
+    if (s >= strong) hardFg[i] = 1;
+  }
+  for (let x = 0; x < w; x++) {
+    for (const y of [0, h - 1]) if (sal[sp.label[y * w + x]] < t * 0.5) hardBg[y * w + x] = 1;
+  }
+  for (let y = 0; y < h; y++) {
+    for (const x of [0, w - 1]) if (sal[sp.label[y * w + x]] < t * 0.5) hardBg[y * w + x] = 1;
+  }
+  const empty = (reason) => ({ selection: createSelectionMask(pixels.width, pixels.height), reason });
+  let guessed = 0;
+  for (let i = 0; i < n; i++) guessed += initial[i];
+  if (!guessed || guessed > n * 0.95) return empty("Nothing stands out from the background.");
+  const roi = { x: 0, y: 0, width: w, height: h };
+  const label = grabCutLabels(work, { roi, initial, hardBg, hardFg }, 5);
+  keepMainPieces(label, w, h, null);
+  let kept = 0;
+  for (let i = 0; i < n; i++) kept += label[i];
+  if (kept < n * 2e-3) return empty("Nothing stands out from the background.");
+  if (kept > n * 0.97) return empty("The whole image looks like one subject; select it with select_all instead.");
+  return { selection: upscaleRegion(work, pixels, roi, label, options.enhanceEdge ?? false) };
+}
+
 // src/image-editor/layers/shape-type-ui.ts
 var DEFAULT_SHAPE_TOOL_OPTIONS = {
   kind: "rect",
@@ -6459,7 +6662,7 @@ var ImageEditorController = class {
     this.state.layers = next;
     this.notify();
   }
-  /** The registered segmentation provider, or `null` (then `selectSubject` is unavailable). */
+  /** The registered segmentation provider, or `null` (then `selectSubject` finds the most salient subject without a model). */
   get segmentationProvider() {
     return this.segmentation;
   }
@@ -9831,11 +10034,24 @@ var ImageEditorController = class {
    * Select › Subject: asks the segmentation provider for the objects matching `target` ("the
    * dog", "the sky") in the flattened image and selects their shapes, combined with the
    * selection by `mode`, as one undo step. Returns what was found (labels and bounds in natural
-   * pixels); an empty list leaves the selection as it was. Throws without a provider.
+   * pixels); an empty list leaves the selection as it was. Without a provider, the subject that
+   * stands out most is found classically (superpixels, saliency, Otsu, GrabCut): `target` can't
+   * choose it, and `method: 'saliency'` and a `note` say so.
    */
-  async selectSubject(target, options = {}) {
+  async selectSubject(target = "", options = {}) {
     const provider = this.segmentation;
-    if (!provider) throw new Error("Select Subject needs a segmentation provider (setSegmentationProvider).");
+    if (!provider) {
+      const pixels = await this.requirePixels({});
+      options.signal?.throwIfAborted();
+      const { selection, reason } = findSubject(pixels, { enhanceEdge: options.enhanceEdge });
+      if (selection.bounds) this.shapeCommand(selection, options);
+      const unused = target.trim() ? ` "${target.trim()}" was not used to choose it.` : "";
+      return {
+        segments: selection.bounds ? [{ label: "subject", bounds: selection.bounds }] : [],
+        method: "saliency",
+        note: reason ?? `No segmentation model is set, so the subject that stands out most was selected.${unused}`
+      };
+    }
     const description = target.trim();
     if (!description) throw new Error("Describe the subject to select.");
     const { width, height } = this.naturalSize;
@@ -9861,7 +10077,7 @@ var ImageEditorController = class {
       options.signal?.throwIfAborted();
     }
     if (mask) this.shapeCommand(mask, options);
-    return { segments: segments.filter((s) => s.bounds) };
+    return { segments: segments.filter((s) => s.bounds), method: "model" };
   }
   /** Quick Mask view (tints the unselected area). View state: no undo step. */
   setQuickMask(on) {
@@ -11156,7 +11372,7 @@ var ImageEditorController = class {
     }
     if (src.colorSpace !== "rgb") throw new LayerOperationError("Colours are given as #rrggbb, so the source profile must be RGB.");
     const t = Transform.create(src, dst, { intent: options.intent ?? "relative", bpc: options.bpc ?? true });
-    const toLab = Transform.create(src, builtinProfile("lab-d50"), { intent: "relative", bpc: false });
+    const toLab2 = Transform.create(src, builtinProfile("lab-d50"), { intent: "relative", bpc: false });
     return colors.map((input) => {
       const m = /^#?([0-9a-f]{6})$/i.exec(input.trim());
       if (!m) throw new LayerOperationError(`Invalid colour "${input}"; use #rrggbb.`);
@@ -11166,7 +11382,7 @@ var ImageEditorController = class {
       t.eval(rgb, out);
       const values = Array.from(out.subarray(0, t.outputs), (v) => Math.round(Math.min(1, Math.max(0, v)) * 1e4) / 1e4);
       const l = new Float32Array(3);
-      toLab.eval(rgb, l);
+      toLab2.eval(rgb, l);
       const lab = [Math.round(l[0] * 1e4) / 100, Math.round((l[1] * 255 - 128) * 100) / 100, Math.round((l[2] * 255 - 128) * 100) / 100];
       const res = { input, values, lab };
       if (dst.colorSpace === "rgb") res.hex = `#${values.map((v) => Math.round(v * 255).toString(16).padStart(2, "0")).join("")}`;
@@ -13738,6 +13954,7 @@ function createImageSelectionTools(controller) {
     selectPolygonTool,
     quickSelectTool,
     selectObjectTool,
+    createImageSubjectSelectionTool(controller),
     lineTool,
     magicWandTool,
     colorRangeTool,
@@ -13774,49 +13991,50 @@ function createImageSubjectSelectionTool(controller) {
   return {
     name: "select_subject",
     title: "Select a subject",
-    description: 'Select \u203A Subject: an AI segmentation model finds the objects matching target (a description such as "the dog", "the house", "the sky") in the flattened image and selects their outlines, combined with the selection by mode. Use it to cut a subject out by its contour (then layer_via_copy for a layer of just that subject); describe one object precisely to get only that one. One undoable step. Returns the selection and the objects found (label, bounds); none found leaves the selection unchanged.',
+    description: 'Select \u203A Subject: selects the main subject of the flattened image, combined with the selection by mode. With a segmentation model set by the host, target (a description such as "the dog" or "the house") chooses which objects; describe one object precisely to get only that one. Without a model, the subject that stands out most from the background is found classically (superpixel saliency and GrabCut): target cannot choose it, and method "saliency" and a note say so. Then check it with capture_view and fix it with quick_select or select_object. One undoable step. Returns the selection, the objects found (label, bounds), method ("model" or "saliency") and any note; none found leaves the selection unchanged.',
     inputSchema: {
       type: "object",
       properties: {
-        target: { type: "string", minLength: 1, description: "What to select, in words." },
+        target: { type: "string", description: "What to select, in words. Needed with a model; ignored without one." },
         maxSegments: {
           type: "integer",
           minimum: 1,
           maximum: 32,
-          description: "Select at most this many matching objects (default the model\u2019s; 1 for a single subject)."
+          description: "With a model: select at most this many matching objects (default the model\u2019s; 1 for a single subject)."
         },
         mode: modeSchema,
-        feather: { type: "number", minimum: 0, description: "Feather radius in pixels (default 0)." }
+        feather: { type: "number", minimum: 0, description: "Feather radius in pixels (default 0)." },
+        enhanceEdge: { type: "boolean", description: "Without a model: smoother, less blocky edges (Auto-Enhance; default false)." }
       },
-      required: ["target"],
       additionalProperties: false
     },
     annotations: { ...writeAnnotations("Select a subject"), openWorldHint: true },
-    handler: async ({ target, maxSegments, mode, feather }, context) => {
-      if (typeof target !== "string" || !target.trim()) throw new Error("target must describe what to select.");
+    handler: async ({ target, maxSegments, mode, feather, enhanceEdge }, context) => {
+      if (target !== void 0 && typeof target !== "string") throw new Error("target must be a description in words.");
+      if (controller.segmentationProvider && !String(target ?? "").trim()) throw new Error("target must describe what to select (a model is set, and it selects by description).");
       const perform = context?.perform;
-      const { segments } = await controller.selectSubject(target, {
+      const { segments, method, note } = await controller.selectSubject(String(target ?? ""), {
         mode: parseSelectionMode(mode),
         feather: num2(feather, 0),
         maxSegments: typeof maxSegments === "number" ? Math.max(1, Math.round(maxSegments)) : void 0,
+        enhanceEdge: enhanceEdge === true,
         signal: context?.signal,
         // Under playback the cursor traces what the model found, as a lasso, before it is selected.
         beforeApply: perform ? (outlines) => perform(planOutlineTrace(outlines)) : void 0
       });
-      return { ...summary(controller), found: segments };
+      return { ...summary(controller), found: segments, method, ...note ? { note } : {} };
     }
   };
 }
 function createImageSegmentationToolProvider(controller, options = {}) {
-  const tool = createImageSubjectSelectionTool(controller);
   return withImagePlayback(
     {
       id: options.id ?? "image-segmentation",
       namespace: options.namespace,
       title: "Image segmentation",
-      description: "Select \u203A Subject: select objects in the image by description through an AI segmentation model.",
+      description: "Deprecated: select_subject is in the image editor tool provider.",
       skill: "pixerate-image-editor",
-      tools: () => controller.segmentationProvider ? [tool] : []
+      tools: () => []
     },
     options.playbackSurface
   );
@@ -20450,6 +20668,7 @@ export {
   findAdjustmentControl,
   findLayer,
   findLayerControl,
+  findSubject,
   findWebGpu,
   finishTile,
   fitParagraphRuns,
@@ -20471,6 +20690,7 @@ export {
   getViewportMetrics,
   getViewportProjection,
   globalImageCache,
+  grabCutLabels,
   gradientDabColor,
   grainCatch,
   grainHeights,
@@ -20562,6 +20782,7 @@ export {
   isTransformAnchor,
   isValidWarp,
   keepDeepSamples,
+  keepMainPieces,
   kelvinToTemperature,
   keysWeight,
   latticeViscosity,
@@ -20674,6 +20895,7 @@ export {
   offsetVectorMask,
   openMaskFile,
   openPsdFile,
+  otsuThreshold,
   packRgba,
   packWetParams,
   paintGradientMappingFor,
@@ -20863,6 +21085,7 @@ export {
   shiftCoverage,
   simplifyPixelPath,
   skinToneRange,
+  slicSuperpixels,
   smartFilterRows,
   smartObjectLayers,
   smoothCoverage,
@@ -20893,6 +21116,7 @@ export {
   styleAt,
   subpathsToSvgPath,
   sumHistograms,
+  superpixelSaliency,
   surfaceBytes,
   surfaceDepth,
   surfaceFromDeepPixels,

package/dist/image-editor/selection/segment/grabcut.d.cts

@@ -7,6 +7,7 @@
  */
 import type { CropBox, ImagePoint } from '../../types.cjs';
 import { type PixelBuffer, type SelectionMask } from '../mask.cjs';
+import { type Rect, type WorkImage } from './work.cjs';
 /** A mixture of {@link K} full-covariance Gaussians over RGB. */
 export declare class ColorGmm {
     private readonly logWeight;
@@ -24,6 +25,23 @@ export declare class ColorGmm {
     /** The component most likely to have produced the colour. */
     nearest(r: number, g: number, b: number): number;
 }
+/** Pixels fixed to one side, and a starting guess, over a window of the work image. */
+export interface GrabCutSetup {
+    roi: Rect;
+    /** Per window pixel: 1 = starts inside the object. */
+    initial: Uint8Array;
+    /** Per window pixel: 1 = fixed outside. */
+    hardBg: Uint8Array;
+    /** Per window pixel: 1 = fixed inside. */
+    hardFg: Uint8Array | null;
+}
+/** GrabCut over the setup's window; returns 1 for the object per window pixel. */
+export declare function grabCutLabels(work: WorkImage, setup: GrabCutSetup, iterations: number): Uint8Array;
+/**
+ * Keeps the object's main parts: the pieces (4-connected) holding `seed` (window index), or
+ * without one, every piece at least a fifth the size of the largest.
+ */
+export declare function keepMainPieces(label: Uint8Array, rw: number, rh: number, seed: number | null): void;
 export interface ObjectSelectionOptions {
     /** Smoother, less blocky edges (Auto-Enhance). Default false. */
     enhanceEdge?: boolean;

package/dist/image-editor/selection/segment/grabcut.d.ts

@@ -7,6 +7,7 @@
  */
 import type { CropBox, ImagePoint } from '../../types.js';
 import { type PixelBuffer, type SelectionMask } from '../mask.js';
+import { type Rect, type WorkImage } from './work.js';
 /** A mixture of {@link K} full-covariance Gaussians over RGB. */
 export declare class ColorGmm {
     private readonly logWeight;
@@ -24,6 +25,23 @@ export declare class ColorGmm {
     /** The component most likely to have produced the colour. */
     nearest(r: number, g: number, b: number): number;
 }
+/** Pixels fixed to one side, and a starting guess, over a window of the work image. */
+export interface GrabCutSetup {
+    roi: Rect;
+    /** Per window pixel: 1 = starts inside the object. */
+    initial: Uint8Array;
+    /** Per window pixel: 1 = fixed outside. */
+    hardBg: Uint8Array;
+    /** Per window pixel: 1 = fixed inside. */
+    hardFg: Uint8Array | null;
+}
+/** GrabCut over the setup's window; returns 1 for the object per window pixel. */
+export declare function grabCutLabels(work: WorkImage, setup: GrabCutSetup, iterations: number): Uint8Array;
+/**
+ * Keeps the object's main parts: the pieces (4-connected) holding `seed` (window index), or
+ * without one, every piece at least a fifth the size of the largest.
+ */
+export declare function keepMainPieces(label: Uint8Array, rw: number, rh: number, seed: number | null): void;
 export interface ObjectSelectionOptions {
     /** Smoother, less blocky edges (Auto-Enhance). Default false. */
     enhanceEdge?: boolean;

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

@@ -2,3 +2,4 @@ export * from './maxflow.cjs';
 export * from './work.cjs';
 export * from './quick.cjs';
 export * from './grabcut.cjs';
+export * from './subject.cjs';

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

@@ -2,3 +2,4 @@ export * from './maxflow.js';
 export * from './work.js';
 export * from './quick.js';
 export * from './grabcut.js';
+export * from './subject.js';

package/dist/image-editor/selection/segment/subject.d.cts

@@ -0,0 +1,44 @@
+/**
+ * Select Subject without a segmentation model: the most salient subject, found classically.
+ *
+ * 1. SLIC superpixels (Achanta et al., 2012) group the reduced image into a few hundred patches of
+ *    similar colour.
+ * 2. Each patch's saliency is how unlike the image's border it is (the border is mostly
+ *    background), times how much it contrasts with the patches around it (region contrast, Cheng
+ *    et al., 2015), times a mild preference for the centre.
+ * 3. Otsu's threshold splits the patches into a first guess at the subject.
+ * 4. GrabCut refines that guess along the image's edges, with the clearly-background border fixed.
+ *
+ * It cannot tell which object a description names: it selects what stands out.
+ */
+import type { PixelBuffer, SelectionMask } from '../mask.cjs';
+import { type WorkImage } from './work.cjs';
+export interface Superpixels {
+    /** Superpixel of each work pixel. */
+    label: Int32Array;
+    count: number;
+    /** Mean L*a*b* per superpixel, 3 values each. */
+    lab: Float64Array;
+    /** Mean position per superpixel, in work pixels, 2 values each. */
+    centre: Float64Array;
+    size: Int32Array;
+}
+/** SLIC superpixels of the work image: about `target` of them, `compactness` 10 (L*a*b* units). */
+export declare function slicSuperpixels(work: WorkImage, target?: number, compactness?: number, rounds?: number): Superpixels;
+/** Saliency 0..1 of each superpixel (see the module comment). */
+export declare function superpixelSaliency(sp: Superpixels, width: number, height: number): Float64Array;
+/** Otsu's threshold of `values` (0..1) weighted by `weights`. */
+export declare function otsuThreshold(values: ArrayLike<number>, weights: ArrayLike<number>): number;
+/** What {@link findSubject} found. */
+export interface FoundSubject {
+    selection: SelectionMask;
+    /** Why nothing was selected, when nothing was. */
+    reason?: string;
+}
+/**
+ * The most salient subject of `pixels` as a selection of the whole image (empty, with a reason,
+ * when nothing stands out from the background).
+ */
+export declare function findSubject(pixels: PixelBuffer, options?: {
+    enhanceEdge?: boolean;
+}): FoundSubject;

package/dist/image-editor/selection/segment/subject.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Select Subject without a segmentation model: the most salient subject, found classically.
+ *
+ * 1. SLIC superpixels (Achanta et al., 2012) group the reduced image into a few hundred patches of
+ *    similar colour.
+ * 2. Each patch's saliency is how unlike the image's border it is (the border is mostly
+ *    background), times how much it contrasts with the patches around it (region contrast, Cheng
+ *    et al., 2015), times a mild preference for the centre.
+ * 3. Otsu's threshold splits the patches into a first guess at the subject.
+ * 4. GrabCut refines that guess along the image's edges, with the clearly-background border fixed.
+ *
+ * It cannot tell which object a description names: it selects what stands out.
+ */
+import type { PixelBuffer, SelectionMask } from '../mask.js';
+import { type WorkImage } from './work.js';
+export interface Superpixels {
+    /** Superpixel of each work pixel. */
+    label: Int32Array;
+    count: number;
+    /** Mean L*a*b* per superpixel, 3 values each. */
+    lab: Float64Array;
+    /** Mean position per superpixel, in work pixels, 2 values each. */
+    centre: Float64Array;
+    size: Int32Array;
+}
+/** SLIC superpixels of the work image: about `target` of them, `compactness` 10 (L*a*b* units). */
+export declare function slicSuperpixels(work: WorkImage, target?: number, compactness?: number, rounds?: number): Superpixels;
+/** Saliency 0..1 of each superpixel (see the module comment). */
+export declare function superpixelSaliency(sp: Superpixels, width: number, height: number): Float64Array;
+/** Otsu's threshold of `values` (0..1) weighted by `weights`. */
+export declare function otsuThreshold(values: ArrayLike<number>, weights: ArrayLike<number>): number;
+/** What {@link findSubject} found. */
+export interface FoundSubject {
+    selection: SelectionMask;
+    /** Why nothing was selected, when nothing was. */
+    reason?: string;
+}
+/**
+ * The most salient subject of `pixels` as a selection of the whole image (empty, with a reason,
+ * when nothing stands out from the background).
+ */
+export declare function findSubject(pixels: PixelBuffer, options?: {
+    enhanceEdge?: boolean;
+}): FoundSubject;

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

@@ -23,8 +23,8 @@ export interface ImageSegmentationToolProviderOptions {
 /** The `select_subject` tool: Select › Subject through the controller's segmentation provider. */
 export declare function createImageSubjectSelectionTool(controller: ImageEditorController): AgentTool;
 /**
- * Agent tools that need the controller's segmentation provider (`select_subject`). The list is
- * empty while no provider is set, so a host can register this once and the tool appears when a
- * model is available.
+ * @deprecated `select_subject` is now one of the selection tools of `createImageEditorToolProvider`
+ * (it works without a model too), so this provider lists no tools; it stays so hosts that register
+ * it keep working. Remove it from your registry.
  */
 export declare function createImageSegmentationToolProvider(controller: ImageEditorController, options?: ImageSegmentationToolProviderOptions): AgentToolProvider;

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

@@ -23,8 +23,8 @@ export interface ImageSegmentationToolProviderOptions {
 /** The `select_subject` tool: Select › Subject through the controller's segmentation provider. */
 export declare function createImageSubjectSelectionTool(controller: ImageEditorController): AgentTool;
 /**
- * Agent tools that need the controller's segmentation provider (`select_subject`). The list is
- * empty while no provider is set, so a host can register this once and the tool appears when a
- * model is available.
+ * @deprecated `select_subject` is now one of the selection tools of `createImageEditorToolProvider`
+ * (it works without a model too), so this provider lists no tools; it stays so hosts that register
+ * it keep working. Remove it from your registry.
  */
 export declare function createImageSegmentationToolProvider(controller: ImageEditorController, options?: ImageSegmentationToolProviderOptions): AgentToolProvider;

package/package.json

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

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

@@ -221,7 +221,7 @@ in the source frame at the document's bit depth, colour mode and profile. Read
 | `list_controls` | Get every base control (id, label, section, min, max, step, default, `requiresProcess`), each layer kind's settable controls (plus `opacity`), the blend mode ids and the `layers.<layerId>.<controlId>` path format. Call once per session before writing. |
 | `get_selection` | Read the active selection: `empty`, `bounds` (natural pixels), `area` in pixels, `percent` of the image and a description. Check it after every select or modify step and before masking: a wand that covered 90% of the image is the wrong selection. |
 | `list_channels` | Read the alpha channels (saved selections): id, name, bounds, percent, overlay and visibility, and whether Quick Mask mode is on. |
-| `select_subject` | Select › Subject (only when the host has a segmentation model): `target` describes what to select ("the dog", "the sky"); an AI model finds the matching objects and selects their outlines, combined by `mode`. `maxSegments` 1 for a single subject. Returns the selection and `found` (label, bounds per object); nothing found leaves the selection unchanged. |
+| `select_subject` | Select › Subject. With a host segmentation model, `target` describes what to select ("the dog", "the sky") and the model's outlines are selected (`maxSegments` 1 for one). Without one, the subject that stands out most is found classically; `target` can't choose it (`method: "saliency"`, `note`). Combined by `mode`. Returns the selection, `found` (label, bounds) and `method`; nothing found leaves the selection unchanged. |
 | `list_layers` | Read the layer stack bottom to top as a tree: id, type (`pixel`, `adjustment`, `group`, `shape`, `annotation`, `smart`; smart objects add their `contents`, `smartFilters` and `filterMask`; shapes a `shape` summary of component ops and kinds and paint types, and `annotation` when migrated from one), name, document `bounds` of pixel layers, visibility, opacity, `fillOpacity`, blend, `clipped`, locks, a `mask` summary, an `effects` summary (master switch, scale, effect ids and kinds), pixel-layer `filters` (the Background's `develop` filter is the base adjustments), adjustment `kind` and `params`, group `children`, and which layer is `active`. Call it to understand a document with more than the Background before changing it; adjustment layer ids work with every adjustment-layer tool. |
 | `list_layer_effects` | Read one layer's effects: `enabled` (master switch), `scale` (Scale Effects), `margin` (px they reach beyond the shape), `fromPsd`, and every effect with `id`, `kind`, `label` and all its settings. Also returns the `globalLight`, the `patterns` pattern effects can use and the effect `kinds`. Call before changing effects you did not add. |
 | `get_image_info` | Read the geometry: source `image` size, `crop` box (source pixels, or null), `rotation` degrees, `flipH` / `flipV`, the `output` size after crop and rotation, `bitDepth` (8, 16 or 32), the layer count and `canUndo` / `canRedo`. Call before cropping or selecting so coordinates are right. |

package/skills/pixerate-image-selection-masking/SKILL.md

@@ -97,7 +97,7 @@ This skill is the method. `pixerate-image-editor` has the full tool reference.
 | --- | --- |
 | Geometric areas: a frame, a screen, a band | `select_rect` / `select_ellipse`, with `feather` for soft transitions |
 | One object among others, where you can box it (a product on a table, a person in a group) | `select_object` with a `rect` a little larger than the object on every side; then `quick_select` add / subtract strokes for what it missed |
-| A subject with a clear outline (product, person, animal) | `select_subject` if the host has a model; else `select_object` around it, or `select_polygon` with `snapToEdges` (12–30 points within `width` of the edge), then `refine_selection` |
+| A subject with a clear outline (product, person, animal) | `select_subject` (with a host model, by description; without one it takes whatever stands out most, so check `method` and the result); else `select_object` around it, or `select_polygon` with `snapToEdges` (12–30 points within `width` of the edge), then `refine_selection` |
 | An area or subject that differs from its surroundings (a shirt, a sky, a car) | `quick_select` with strokes painted inside it, away from the edge (`size` a fraction of its width); `add` / `subtract` strokes where it fell short or leaked |
 | A low-contrast or busy outline the edges don't follow | `select_polygon` without `snapToEdges`, along the contour (20–60 points) |
 | Flat backdrop or solid colour (studio white, green screen, sky without clouds) | `magic_wand` on the backdrop (`tolerance` 20–40; `distance: "perceptual"` for gradients), then `invert_selection` |
@@ -158,6 +158,9 @@ This skill is the method. `pixerate-image-editor` has the full tool reference.
   30–60), check `percent`, and grow with `mode: "add"`.
 - **Box instead of outline:** `select_rect` around a subject masks its background too. Trace
   the contour.
+- **Select Subject without a model picks the wrong thing:** it selects what stands out most from
+  the image's border, which may be a bright sign rather than the person. When `method` is
+  `saliency`, check with `capture_view`; if it's wrong, use `select_object` with a box.
 - **Object Selection takes part of the background:** inside the box, anything that looks
   unlike the background around the box counts as the object. Tighten the box, or `subtract` a
   `quick_select` stroke on the extra. With `point`, it may stop at an inner edge of a
@@ -212,7 +215,7 @@ This skill is the method. `pixerate-image-editor` has the full tool reference.
 - `fill_pixels`, `blur_stroke`: fill or soften the selection in Quick Mask mode
 - `magic_wand`: similar colour from a seed
 - `select_color_range`: colour samples, hue, tone and skin presets
-- `select_subject`: a subject by description (needs a host model)
+- `select_subject`: a subject by description with a host model; without one, the most salient subject
 - `load_selection_from_image`: AI or saved mattes
 - `load_selection_from_mask`: a layer mask back to a selection
 - `set_selection_display`: ants, Quick Mask tint or hidden