@pixerate/editor 0.196.0 → 0.197.0

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

@@ -27,6 +27,9 @@ export declare function snapTo45(from: ImagePoint, point: ImagePoint): ImagePoin
  *   last anchor to the pointer (snapped to the strongest edge within the width) and places
  *   anchors as it goes (frequency); a click adds one, and closing and the keys are as the
  *   polygonal lasso's. The first click reads the pixels (async).
+ * - 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.
  * - 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,
@@ -48,8 +51,11 @@ export declare class SelectionGesture {
     closeRadius: number;
     /** The last error (e.g. pixels unavailable for the wand), for the UI to show. */
     error: string | null;
+    private pending;
     constructor(controller: ImageEditorController, getOptions: () => SelectionToolOptions);
     get active(): boolean;
+    /** Resolves once a Quick Selection stroke has been applied. */
+    get settled(): Promise<void>;
     /** The anchors of a Magnetic Lasso being drawn (empty otherwise). */
     get magneticAnchors(): ImagePoint[];
     /** The outline of the shape being drawn, or `null`. */

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

@@ -27,6 +27,9 @@ export declare function snapTo45(from: ImagePoint, point: ImagePoint): ImagePoin
  *   last anchor to the pointer (snapped to the strongest edge within the width) and places
  *   anchors as it goes (frequency); a click adds one, and closing and the keys are as the
  *   polygonal lasso's. The first click reads the pixels (async).
+ * - 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.
  * - 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,
@@ -48,8 +51,11 @@ export declare class SelectionGesture {
     closeRadius: number;
     /** The last error (e.g. pixels unavailable for the wand), for the UI to show. */
     error: string | null;
+    private pending;
     constructor(controller: ImageEditorController, getOptions: () => SelectionToolOptions);
     get active(): boolean;
+    /** Resolves once a Quick Selection stroke has been applied. */
+    get settled(): Promise<void>;
     /** The anchors of a Magnetic Lasso being drawn (empty otherwise). */
     get magneticAnchors(): ImagePoint[];
     /** The outline of the shape being drawn, or `null`. */

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,30 @@
+/**
+ * Max-flow / min-cut on a 4-connected pixel grid (Boykov & Kolmogorov, "An Experimental
+ * Comparison of Min-Cut/Max-Flow Algorithms for Energy Minimization in Vision", 2004): two search
+ * trees grown from the source and the sink, reused between augmentations. The graph segmentations
+ * (Quick Selection, Object Selection) label each pixel by the side of the cut it ends up on.
+ */
+/**
+ * A `width × height` grid graph. Each node has an edge to its right, lower, left and upper
+ * neighbour (directions 0..3; the reverse of `d` is `d ^ 2`) and a terminal capacity. Use whole
+ * numbers for capacities: with fractions, rounding leaves residuals a hair above zero and the
+ * search slows to a crawl on near-empty paths.
+ */
+export declare class GridGraph {
+    readonly width: number;
+    readonly height: number;
+    /** Residual capacity of the edge leaving node `p` in direction `d`, at `p * 4 + d`. */
+    readonly cap: Float64Array;
+    /** Net terminal capacity: above 0 to the source, below 0 to the sink. */
+    readonly tr: Float64Array;
+    private readonly tree;
+    constructor(width: number, height: number);
+    /** Sets the capacity of the edge between `p` and its neighbour in direction `d`, both ways. */
+    setEdge(p: number, d: 0 | 1, capacity: number): void;
+    /** Adds `source` (cost of putting `p` on the sink side) and `sink` (the other way) to `p`. */
+    addTerminal(p: number, source: number, sink: number): void;
+    /** Whether `p` is on the source side of the minimum cut (after {@link maxflow}). */
+    inSource(p: number): boolean;
+    /** Runs max-flow and returns the flow (the cut's cost, less the constant terminal parts). */
+    maxflow(): number;
+}

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

@@ -0,0 +1,30 @@
+/**
+ * Max-flow / min-cut on a 4-connected pixel grid (Boykov & Kolmogorov, "An Experimental
+ * Comparison of Min-Cut/Max-Flow Algorithms for Energy Minimization in Vision", 2004): two search
+ * trees grown from the source and the sink, reused between augmentations. The graph segmentations
+ * (Quick Selection, Object Selection) label each pixel by the side of the cut it ends up on.
+ */
+/**
+ * A `width × height` grid graph. Each node has an edge to its right, lower, left and upper
+ * neighbour (directions 0..3; the reverse of `d` is `d ^ 2`) and a terminal capacity. Use whole
+ * numbers for capacities: with fractions, rounding leaves residuals a hair above zero and the
+ * search slows to a crawl on near-empty paths.
+ */
+export declare class GridGraph {
+    readonly width: number;
+    readonly height: number;
+    /** Residual capacity of the edge leaving node `p` in direction `d`, at `p * 4 + d`. */
+    readonly cap: Float64Array;
+    /** Net terminal capacity: above 0 to the source, below 0 to the sink. */
+    readonly tr: Float64Array;
+    private readonly tree;
+    constructor(width: number, height: number);
+    /** Sets the capacity of the edge between `p` and its neighbour in direction `d`, both ways. */
+    setEdge(p: number, d: 0 | 1, capacity: number): void;
+    /** Adds `source` (cost of putting `p` on the sink side) and `sink` (the other way) to `p`. */
+    addTerminal(p: number, source: number, sink: number): void;
+    /** Whether `p` is on the source side of the minimum cut (after {@link maxflow}). */
+    inSource(p: number): boolean;
+    /** Runs max-flow and returns the flow (the cut's cost, less the constant terminal parts). */
+    maxflow(): number;
+}

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

@@ -0,0 +1,47 @@
+/**
+ * Quick Selection: a brush stroke grows into the region it is painted on, out to that region's
+ * edges. Graph cut (Boykov & Jolly, "Interactive Graph Cuts", 2001) on a reduced copy of the
+ * image: the pixels under the brush are fixed to the selection, colour models of the stroke and of
+ * the surroundings pull every other pixel one way or the other, and cutting between dissimilar
+ * neighbours is cheap, so the cut runs along edges. The search starts in a window around the
+ * stroke and widens while the region reaches its border. The result is scaled back up and its
+ * edge pixels anti-aliased at full size from the colours either side of the edge.
+ */
+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;
+    /**
+     * The current selection: with `grow` its pixels near the stroke count as part of what is being
+     * selected (Add), so the new region joins on to it.
+     */
+    selection?: SelectionMask | null;
+    grow?: boolean;
+    /** Smoother, less blocky edges (Photoshop's Auto-Enhance). Default false. */
+    enhanceEdge?: boolean;
+}
+/**
+ * The region one Quick Selection stroke selects over `pixels`, as a selection of the whole image
+ * (not yet combined with the current one). `stroke` is the brush's path in natural pixels.
+ */
+export declare function quickSelectStroke(pixels: PixelBuffer, stroke: readonly ImagePoint[], options?: QuickSelectOptions): SelectionMask;

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

@@ -0,0 +1,47 @@
+/**
+ * Quick Selection: a brush stroke grows into the region it is painted on, out to that region's
+ * edges. Graph cut (Boykov & Jolly, "Interactive Graph Cuts", 2001) on a reduced copy of the
+ * image: the pixels under the brush are fixed to the selection, colour models of the stroke and of
+ * the surroundings pull every other pixel one way or the other, and cutting between dissimilar
+ * neighbours is cheap, so the cut runs along edges. The search starts in a window around the
+ * stroke and widens while the region reaches its border. The result is scaled back up and its
+ * edge pixels anti-aliased at full size from the colours either side of the edge.
+ */
+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;
+    /**
+     * The current selection: with `grow` its pixels near the stroke count as part of what is being
+     * selected (Add), so the new region joins on to it.
+     */
+    selection?: SelectionMask | null;
+    grow?: boolean;
+    /** Smoother, less blocky edges (Photoshop's Auto-Enhance). Default false. */
+    enhanceEdge?: boolean;
+}
+/**
+ * The region one Quick Selection stroke selects over `pixels`, as a selection of the whole image
+ * (not yet combined with the current one). `stroke` is the brush's path in natural pixels.
+ */
+export declare function quickSelectStroke(pixels: PixelBuffer, stroke: readonly ImagePoint[], options?: QuickSelectOptions): 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' | 'range' | 'type' | 'type-vertical';
+export type SelectionToolKind = 'wand' | 'rect' | 'ellipse' | 'row' | 'column' | 'lasso' | 'polygon' | 'magnetic' | 'quick' | 'range' | 'type' | 'type-vertical';
 export declare const SELECTION_TOOLS: readonly {
     id: SelectionToolKind;
     label: string;
@@ -37,6 +37,12 @@ export interface SelectionToolOptions {
     magneticContrast?: number;
     /** Magnetic Lasso: how often anchors are placed as the pointer moves (0..100, default 57). */
     magneticFrequency?: number;
+    /** Quick Selection: brush diameter in natural pixels (default 30). */
+    quickSize?: number;
+    /** Quick Selection: read every layer (default true) or only the active pixel layer. */
+    quickSampleAll?: boolean;
+    /** Quick Selection: smoother, less blocky edges (Auto-Enhance; default false). */
+    quickEnhance?: 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' | 'range' | 'type' | 'type-vertical';
+export type SelectionToolKind = 'wand' | 'rect' | 'ellipse' | 'row' | 'column' | 'lasso' | 'polygon' | 'magnetic' | 'quick' | 'range' | 'type' | 'type-vertical';
 export declare const SELECTION_TOOLS: readonly {
     id: SelectionToolKind;
     label: string;
@@ -37,6 +37,12 @@ export interface SelectionToolOptions {
     magneticContrast?: number;
     /** Magnetic Lasso: how often anchors are placed as the pointer moves (0..100, default 57). */
     magneticFrequency?: number;
+    /** Quick Selection: brush diameter in natural pixels (default 30). */
+    quickSize?: number;
+    /** Quick Selection: read every layer (default true) or only the active pixel layer. */
+    quickSampleAll?: boolean;
+    /** Quick Selection: smoother, less blocky edges (Auto-Enhance; default false). */
+    quickEnhance?: 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.196.0",
+  "version": "0.197.0",
   "description": "UI-agnostic rich text and media editing core library",
   "author": "Pixerate",
   "license": "MIT",