@pixerate/editor 0.197.0 → 0.198.0

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

@@ -30,6 +30,8 @@ export declare function snapTo45(from: ImagePoint, point: ImagePoint): ImagePoin
  * - Quick Selection: drag (or click) a brush stroke; on `end` it grows into the region painted on,
  *   out to its edges (async: await {@link settled}). With the New mode and a selection already
  *   there, strokes add, as in Photoshop; Alt subtracts.
+ * - Object Selection: drag a box around an object, or click on it; on `end` the object is
+ *   selected (async: await {@link settled}).
  * - Single row / column: a click selects a 1 px line across the image.
  *
  * Shift adds, Alt subtracts, both intersect (overriding the options bar mode). While dragging,
@@ -54,7 +56,7 @@ export declare class SelectionGesture {
     private pending;
     constructor(controller: ImageEditorController, getOptions: () => SelectionToolOptions);
     get active(): boolean;
-    /** Resolves once a Quick Selection stroke has been applied. */
+    /** Resolves once a Quick Selection stroke or an Object Selection has been applied. */
     get settled(): Promise<void>;
     /** The anchors of a Magnetic Lasso being drawn (empty otherwise). */
     get magneticAnchors(): ImagePoint[];

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

@@ -30,6 +30,8 @@ export declare function snapTo45(from: ImagePoint, point: ImagePoint): ImagePoin
  * - Quick Selection: drag (or click) a brush stroke; on `end` it grows into the region painted on,
  *   out to its edges (async: await {@link settled}). With the New mode and a selection already
  *   there, strokes add, as in Photoshop; Alt subtracts.
+ * - Object Selection: drag a box around an object, or click on it; on `end` the object is
+ *   selected (async: await {@link settled}).
  * - Single row / column: a click selects a 1 px line across the image.
  *
  * Shift adds, Alt subtracts, both intersect (overriding the options bar mode). While dragging,
@@ -54,7 +56,7 @@ export declare class SelectionGesture {
     private pending;
     constructor(controller: ImageEditorController, getOptions: () => SelectionToolOptions);
     get active(): boolean;
-    /** Resolves once a Quick Selection stroke has been applied. */
+    /** Resolves once a Quick Selection stroke or an Object Selection has been applied. */
     get settled(): Promise<void>;
     /** The anchors of a Magnetic Lasso being drawn (empty otherwise). */
     get magneticAnchors(): ImagePoint[];

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

@@ -0,0 +1,45 @@
+/**
+ * Object Selection: GrabCut (Rother, Kolmogorov & Blake, 2004) from a box drawn around an object
+ * or a click on it. Two colour models, mixtures of five Gaussians each, are fitted to what is
+ * currently inside and outside the object; a graph cut relabels every pixel by them and by the
+ * edges between neighbours; the two steps repeat until the labels settle. It runs on the reduced
+ * copy of the image and is scaled back up with an anti-aliased edge, as Quick Selection is.
+ */
+import type { CropBox, ImagePoint } from '../../types.cjs';
+import { type PixelBuffer, type SelectionMask } from '../mask.cjs';
+/** A mixture of {@link K} full-covariance Gaussians over RGB. */
+export declare class ColorGmm {
+    private readonly logWeight;
+    private readonly mean;
+    /** Inverse covariances, row-major 3 × 3. */
+    private readonly inv;
+    /** ln(weight) − ½ ln((2π)³ |Σ|) per component; −∞ for an empty one. */
+    private readonly logNorm;
+    /** Fits the components to the pixels `ids` of `rgb`, each in component `comp[id]`. */
+    fit(rgb: Float32Array, ids: ArrayLike<number>, comp: Uint8Array): void;
+    /** ln p(colour | component k), up to the shared constant. */
+    private componentLog;
+    /** −ln p(colour) under the mixture (large for colours the model hasn't seen). */
+    cost(r: number, g: number, b: number): number;
+    /** The component most likely to have produced the colour. */
+    nearest(r: number, g: number, b: number): number;
+}
+export interface ObjectSelectionOptions {
+    /** Smoother, less blocky edges (Auto-Enhance). Default false. */
+    enhanceEdge?: boolean;
+    /** Most rounds of fitting and cutting (default 5; it stops early once the labels settle). */
+    iterations?: number;
+}
+/** What to select: a box around the object, or a point on it (natural pixels). */
+export type ObjectTarget = {
+    rect: CropBox;
+} | {
+    point: ImagePoint;
+};
+/**
+ * Object Selection over `pixels`: the object in `target.rect` (everything outside the box is
+ * background), or the object under `target.point` (searched for in a window around it that grows
+ * while the object reaches its border). Returns a selection of the whole image, empty when
+ * nothing stands out.
+ */
+export declare function selectObjectIn(pixels: PixelBuffer, target: ObjectTarget, options?: ObjectSelectionOptions): SelectionMask;

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

@@ -0,0 +1,45 @@
+/**
+ * Object Selection: GrabCut (Rother, Kolmogorov & Blake, 2004) from a box drawn around an object
+ * or a click on it. Two colour models, mixtures of five Gaussians each, are fitted to what is
+ * currently inside and outside the object; a graph cut relabels every pixel by them and by the
+ * edges between neighbours; the two steps repeat until the labels settle. It runs on the reduced
+ * copy of the image and is scaled back up with an anti-aliased edge, as Quick Selection is.
+ */
+import type { CropBox, ImagePoint } from '../../types.js';
+import { type PixelBuffer, type SelectionMask } from '../mask.js';
+/** A mixture of {@link K} full-covariance Gaussians over RGB. */
+export declare class ColorGmm {
+    private readonly logWeight;
+    private readonly mean;
+    /** Inverse covariances, row-major 3 × 3. */
+    private readonly inv;
+    /** ln(weight) − ½ ln((2π)³ |Σ|) per component; −∞ for an empty one. */
+    private readonly logNorm;
+    /** Fits the components to the pixels `ids` of `rgb`, each in component `comp[id]`. */
+    fit(rgb: Float32Array, ids: ArrayLike<number>, comp: Uint8Array): void;
+    /** ln p(colour | component k), up to the shared constant. */
+    private componentLog;
+    /** −ln p(colour) under the mixture (large for colours the model hasn't seen). */
+    cost(r: number, g: number, b: number): number;
+    /** The component most likely to have produced the colour. */
+    nearest(r: number, g: number, b: number): number;
+}
+export interface ObjectSelectionOptions {
+    /** Smoother, less blocky edges (Auto-Enhance). Default false. */
+    enhanceEdge?: boolean;
+    /** Most rounds of fitting and cutting (default 5; it stops early once the labels settle). */
+    iterations?: number;
+}
+/** What to select: a box around the object, or a point on it (natural pixels). */
+export type ObjectTarget = {
+    rect: CropBox;
+} | {
+    point: ImagePoint;
+};
+/**
+ * Object Selection over `pixels`: the object in `target.rect` (everything outside the box is
+ * background), or the object under `target.point` (searched for in a window around it that grows
+ * while the object reaches its border). Returns a selection of the whole image, empty when
+ * nothing stands out.
+ */
+export declare function selectObjectIn(pixels: PixelBuffer, target: ObjectTarget, options?: ObjectSelectionOptions): SelectionMask;

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

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

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

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

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

@@ -9,25 +9,6 @@
  */
 import type { ImagePoint } from '../../types.cjs';
 import { type PixelBuffer, type SelectionMask } from '../mask.cjs';
-/** The reduced image the segmentations work on (sRGB, 0..255 per channel). */
-export interface WorkImage {
-    /** Natural size of the image it was made from. */
-    sourceWidth: number;
-    sourceHeight: number;
-    width: number;
-    height: number;
-    /** Reduced pixels per natural pixel (≤ 1). */
-    scale: number;
-    /** RGB, 3 values per pixel. */
-    rgb: Float32Array;
-}
-/** Long side of the work image (the issue's 512²). */
-export declare const WORK_SIZE = 512;
-/**
- * `pixels` reduced to at most {@link WORK_SIZE} px on the long side by area averaging (alpha
- * composited over white). Cached per pixel buffer.
- */
-export declare function workImage(pixels: PixelBuffer, maxSide?: number): WorkImage;
 export interface QuickSelectOptions {
     /** Brush diameter in natural pixels (default 30). */
     size?: number;

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

@@ -9,25 +9,6 @@
  */
 import type { ImagePoint } from '../../types.js';
 import { type PixelBuffer, type SelectionMask } from '../mask.js';
-/** The reduced image the segmentations work on (sRGB, 0..255 per channel). */
-export interface WorkImage {
-    /** Natural size of the image it was made from. */
-    sourceWidth: number;
-    sourceHeight: number;
-    width: number;
-    height: number;
-    /** Reduced pixels per natural pixel (≤ 1). */
-    scale: number;
-    /** RGB, 3 values per pixel. */
-    rgb: Float32Array;
-}
-/** Long side of the work image (the issue's 512²). */
-export declare const WORK_SIZE = 512;
-/**
- * `pixels` reduced to at most {@link WORK_SIZE} px on the long side by area averaging (alpha
- * composited over white). Cached per pixel buffer.
- */
-export declare function workImage(pixels: PixelBuffer, maxSide?: number): WorkImage;
 export interface QuickSelectOptions {
     /** Brush diameter in natural pixels (default 30). */
     size?: number;

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

@@ -0,0 +1,54 @@
+/**
+ * The reduced copy of the image the graph segmentations (Quick Selection, Object Selection) work
+ * on, and scaling their result back up to the image with an anti-aliased edge.
+ */
+import { type PixelBuffer, type SelectionMask } from '../mask.cjs';
+/** The reduced image the segmentations work on (sRGB, 0..255 per channel). */
+export interface WorkImage {
+    /** Natural size of the image it was made from. */
+    sourceWidth: number;
+    sourceHeight: number;
+    width: number;
+    height: number;
+    /** Reduced pixels per natural pixel (≤ 1). */
+    scale: number;
+    /** RGB, 3 values per pixel. */
+    rgb: Float32Array;
+}
+/** Long side of the work image (the issue's 512²). */
+export declare const WORK_SIZE = 512;
+/**
+ * `pixels` reduced to at most {@link WORK_SIZE} px on the long side by area averaging (alpha
+ * composited over white). Cached per pixel buffer.
+ */
+export declare function workImage(pixels: PixelBuffer, maxSide?: number): WorkImage;
+/** Edge weight between neighbours: high for similar colours, low across an edge (GrabCut's γ, β). */
+export declare const GAMMA = 50;
+/**
+ * Capacities are whole multiples of 1 / UNITS: in floating point, residuals that should reach
+ * zero are left a hair above it and max-flow then pushes thousands of near-empty paths.
+ */
+export declare const UNITS = 64;
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Capacities of the edges between neighbours in `roi` (to the right and below, indexed by the
+ * pixel in the window): high between similar colours, low across an edge, GrabCut's
+ * γ·exp(−β‖Δc‖²) with β from the window's mean squared difference, in whole {@link UNITS}.
+ */
+export declare function smoothnessWeights(work: WorkImage, roi: Rect): {
+    right: Float64Array;
+    down: Float64Array;
+};
+/** A 3 × 3 box blur of `src` (w × h), `passes` times. */
+export declare function boxBlur(src: Float32Array, w: number, h: number, passes: number): Float32Array;
+/**
+ * The region of the work-image `label` over `roi` at natural size: inside and outside as they
+ * are, and the pixels along the edge anti-aliased by where their colour lies between the region's
+ * colour and the surroundings' just either side.
+ */
+export declare function upscaleRegion(work: WorkImage, pixels: PixelBuffer, roi: Rect, label: Uint8Array, enhance: boolean): SelectionMask;

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

@@ -0,0 +1,54 @@
+/**
+ * The reduced copy of the image the graph segmentations (Quick Selection, Object Selection) work
+ * on, and scaling their result back up to the image with an anti-aliased edge.
+ */
+import { type PixelBuffer, type SelectionMask } from '../mask.js';
+/** The reduced image the segmentations work on (sRGB, 0..255 per channel). */
+export interface WorkImage {
+    /** Natural size of the image it was made from. */
+    sourceWidth: number;
+    sourceHeight: number;
+    width: number;
+    height: number;
+    /** Reduced pixels per natural pixel (≤ 1). */
+    scale: number;
+    /** RGB, 3 values per pixel. */
+    rgb: Float32Array;
+}
+/** Long side of the work image (the issue's 512²). */
+export declare const WORK_SIZE = 512;
+/**
+ * `pixels` reduced to at most {@link WORK_SIZE} px on the long side by area averaging (alpha
+ * composited over white). Cached per pixel buffer.
+ */
+export declare function workImage(pixels: PixelBuffer, maxSide?: number): WorkImage;
+/** Edge weight between neighbours: high for similar colours, low across an edge (GrabCut's γ, β). */
+export declare const GAMMA = 50;
+/**
+ * Capacities are whole multiples of 1 / UNITS: in floating point, residuals that should reach
+ * zero are left a hair above it and max-flow then pushes thousands of near-empty paths.
+ */
+export declare const UNITS = 64;
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Capacities of the edges between neighbours in `roi` (to the right and below, indexed by the
+ * pixel in the window): high between similar colours, low across an edge, GrabCut's
+ * γ·exp(−β‖Δc‖²) with β from the window's mean squared difference, in whole {@link UNITS}.
+ */
+export declare function smoothnessWeights(work: WorkImage, roi: Rect): {
+    right: Float64Array;
+    down: Float64Array;
+};
+/** A 3 × 3 box blur of `src` (w × h), `passes` times. */
+export declare function boxBlur(src: Float32Array, w: number, h: number, passes: number): Float32Array;
+/**
+ * The region of the work-image `label` over `roi` at natural size: inside and outside as they
+ * are, and the pixels along the edge anti-aliased by where their colour lies between the region's
+ * colour and the surroundings' just either side.
+ */
+export declare function upscaleRegion(work: WorkImage, pixels: PixelBuffer, roi: Rect, label: Uint8Array, enhance: boolean): SelectionMask;

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

@@ -2,7 +2,7 @@ import { type SelectionMask, type SelectionMode } from './mask.cjs';
 import type { ColorDistance, ColorRangePreset } from './wand.cjs';
 import type { RefineEdgeParams } from './refine.cjs';
 /** Selection tools of the image editor UI. */
-export type SelectionToolKind = 'wand' | 'rect' | 'ellipse' | 'row' | 'column' | 'lasso' | 'polygon' | 'magnetic' | 'quick' | 'range' | 'type' | 'type-vertical';
+export type SelectionToolKind = 'wand' | 'rect' | 'ellipse' | 'row' | 'column' | 'lasso' | 'polygon' | 'magnetic' | 'quick' | 'object' | 'range' | 'type' | 'type-vertical';
 export declare const SELECTION_TOOLS: readonly {
     id: SelectionToolKind;
     label: string;
@@ -43,6 +43,10 @@ export interface SelectionToolOptions {
     quickSampleAll?: boolean;
     /** Quick Selection: smoother, less blocky edges (Auto-Enhance; default false). */
     quickEnhance?: boolean;
+    /** Object Selection: read every layer (default true) or only the active pixel layer. */
+    objectSampleAll?: boolean;
+    /** Object Selection: smoother, less blocky edges (Auto-Enhance; default false). */
+    objectEnhance?: boolean;
     /** Type Mask: the text to select (default "Type"). A click places its first baseline. */
     typeText?: string;
     /** Type Mask: font size in px (default 72). */

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

@@ -2,7 +2,7 @@ import { type SelectionMask, type SelectionMode } from './mask.js';
 import type { ColorDistance, ColorRangePreset } from './wand.js';
 import type { RefineEdgeParams } from './refine.js';
 /** Selection tools of the image editor UI. */
-export type SelectionToolKind = 'wand' | 'rect' | 'ellipse' | 'row' | 'column' | 'lasso' | 'polygon' | 'magnetic' | 'quick' | 'range' | 'type' | 'type-vertical';
+export type SelectionToolKind = 'wand' | 'rect' | 'ellipse' | 'row' | 'column' | 'lasso' | 'polygon' | 'magnetic' | 'quick' | 'object' | 'range' | 'type' | 'type-vertical';
 export declare const SELECTION_TOOLS: readonly {
     id: SelectionToolKind;
     label: string;
@@ -43,6 +43,10 @@ export interface SelectionToolOptions {
     quickSampleAll?: boolean;
     /** Quick Selection: smoother, less blocky edges (Auto-Enhance; default false). */
     quickEnhance?: boolean;
+    /** Object Selection: read every layer (default true) or only the active pixel layer. */
+    objectSampleAll?: boolean;
+    /** Object Selection: smoother, less blocky edges (Auto-Enhance; default false). */
+    objectEnhance?: boolean;
     /** Type Mask: the text to select (default "Type"). A click places its first baseline. */
     typeText?: string;
     /** Type Mask: font size in px (default 72). */

package/package.json

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

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

@@ -253,6 +253,7 @@ in the source frame at the document's bit depth, colour mode and profile. Read
 | `select_ellipse` | Elliptical marquee inscribed in `x`, `y`, `width`, `height`; same options. A feathered ellipse makes a vignette. Returns the summary. |
 | `select_line` | Single row or column marquee: `orientation` `row` (at y) or `column` (at x), `position` in natural px, `mode`. A 1 px line across the image. Returns the summary. |
 | `quick_select` | Quick Selection: `strokes` (brush paths of `{x, y}`), `size` (diameter, default 30), `mode`, `sampleAllLayers`, `enhanceEdge`. Each stroke grows out to its region's edges; with `replace` the first replaces and the rest add. Paint inside the area, then check and fix with `add` / `subtract` strokes. Returns the summary. |
+| `select_object` | Object Selection (GrabCut): `rect` (a box around the object) or `point` (on it), `mode`, `sampleAllLayers`, `enhanceEdge`. Outside the box is background. Make the box a little larger than the object. Returns the summary. |
 | `select_polygon` | The lasso: `points` (at least 3 `{x, y}` along the outline, closed automatically), `mode`, `feather`, `antiAlias`; `snapToEdges: {width, contrast}` makes it the Magnetic Lasso (points snap to edges, the outline follows them). Trace a subject's contour, not its box. Returns the summary (plus `outlinePoints` when snapped). |
 | `magic_wand` | Select similar colour from `x`, `y`: `tolerance` 0..255 (default 32), `contiguous` (default true), `distance` `rgb` or `perceptual`, `sampleMerged`, `sample` (`composite` or `active-layer`), `mode`, `feather`. For flat backdrops and solid colours. Returns the summary. |
 | `select_color_range` | Color Range, soft: `samples` (`[{color, x?, y?}]`) or a `preset` (reds … magentas, highlights, midtones, shadows, skinTones); `fuzziness` (samples 0..200, default 40; tone presets' falloff, default 20), `localized` px radius around positioned samples, `invert`, `sample`, `mode`, `feather`. Returns the summary. |

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

@@ -96,7 +96,8 @@ This skill is the method. `pixerate-image-editor` has the full tool reference.
 | Subject | Method |
 | --- | --- |
 | Geometric areas: a frame, a screen, a band | `select_rect` / `select_ellipse`, with `feather` for soft transitions |
-| A subject with a clear outline (product, person, animal) | `select_subject` if the host has a model; else `select_polygon` with `snapToEdges` (12–30 points within `width` of the edge), then `refine_selection` |
+| 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` |
 | 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` |
@@ -157,6 +158,10 @@ 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.
+- **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
+  multicoloured object: use a box instead.
 - **Quick Selection spills over a weak edge:** a stroke grows into neighbouring areas of a
   similar colour. Paint smaller strokes further from the edge, then a `subtract` stroke on the
   spill. Strokes near an edge also pull in the other side.
@@ -194,6 +199,7 @@ This skill is the method. `pixerate-image-editor` has the full tool reference.
 - `select_rect`, `select_ellipse`: marquees
 - `select_polygon`: the lasso, along a contour; with `snapToEdges`, the Magnetic Lasso
 - `quick_select`: brush strokes that grow out to the region's edges
+- `select_object`: the object in a box or under a point
 - `select_line`: a single row or column
 - `select_layer_transparency`: a layer's own pixels
 - `grow_selection`, `select_similar`: add similar colour, connected or anywhere