@pixerate/editor 0.197.0 → 0.199.0

package/dist/image-editor/controller.d.cts

@@ -1,6 +1,7 @@
 import { AdjustmentKind, AdjustmentLayer, AdjustmentParamsMap, Annotation, CreateAnnotationPayload, AspectRatio, CropBox, DepthMaskOptions, ExportOptions, ImageAdjustments, ImageDimensions, ImageEditorFit, ImageEditorOptions, ImageEditorState, ImageEditorTool, ImageTransform, ImagePoint, SerializedImageEditorState } from './types.cjs';
 import { type PathToSelectionOptions, type SelectionToPathOptions } from './selection/path.cjs';
 import { type MagneticEdgeOptions } from './selection/magnetic.cjs';
+import { type ObjectTarget } from './selection/segment/grabcut.cjs';
 import { RenderOptions } from './renderer.cjs';
 import { type BlendMode } from './blend.cjs';
 import type { ImageHistogram } from './histogram.cjs';
@@ -151,6 +152,15 @@ export interface QuickSelectCommandOptions {
     /** Smoother, less blocky edges (Photoshop's Auto-Enhance). Default false. */
     enhanceEdge?: boolean;
 }
+/** Options of {@link ImageEditorController.selectObject}. */
+export interface SelectObjectCommandOptions {
+    /** How the object combines with the selection (default `replace`). */
+    mode?: SelectionMode;
+    /** Sample every layer (default true) or only the active pixel layer. */
+    sampleAllLayers?: boolean;
+    /** Smoother, less blocky edges (Auto-Enhance). Default false. */
+    enhanceEdge?: boolean;
+}
 /** A new adjustment layer: its kind plus optional initial values and position. */
 export interface AdjustmentLayerInit<K extends AdjustmentKind = AdjustmentKind> extends AdjustmentLayerUpdate<K> {
     kind: K;
@@ -664,7 +674,7 @@ export declare class ImageEditorController {
      * or those drawn while a result was rendering, once it is in. A cache refresh: no undo step.
      */
     private refreshEffectSurfaces;
-    /** 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(): SegmentationProvider | null;
     /** Registers (or with `null` removes) the segmentation provider. Not an edit: no undo step. */
     setSegmentationProvider(provider: SegmentationProvider | null): void;
@@ -1523,6 +1533,13 @@ export declare class ImageEditorController {
      * one undo step. Resolves to the resulting selection.
      */
     quickSelect(strokes: ImagePoint[][], options?: QuickSelectCommandOptions): Promise<SelectionMask | null>;
+    /**
+     * Object Selection: the object inside `target.rect` (natural pixels; what is outside the box is
+     * background) or under `target.point`, found by GrabCut (colour models of object and background
+     * plus a graph cut along edges), combined with the selection by `mode` as one undo step.
+     * Resolves to the resulting selection.
+     */
+    selectObject(target: ObjectTarget, options?: SelectObjectCommandOptions): Promise<SelectionMask | null>;
     /**
      * Supplies the pixels the selection tools sample (natural size RGBA), e.g. decoded in a worker
      * or in a test; `null` goes back to reading the source image. Without a canvas (Node, workers)
@@ -1596,19 +1613,25 @@ export declare class ImageEditorController {
      * 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.
      */
-    selectSubject(target: string, options?: SelectionCommandOptions & {
+    selectSubject(target?: string, options?: SelectionCommandOptions & {
         maxSegments?: number;
         signal?: AbortSignal;
         /** Called with the outlines found (image pixels; a mask-only result's bounds) before the selection changes, e.g. to trace them with an agent's cursor. */
         beforeApply?: (outlines: ImagePoint[][]) => void | Promise<void>;
+        /** Without a model: smoother, less blocky edges (Auto-Enhance). */
+        enhanceEdge?: boolean;
     }): Promise<{
         segments: {
             label: string;
             bounds: CropBox | null;
             score?: number;
         }[];
+        method: 'model' | 'saliency';
+        note?: string;
     }>;
     /** Quick Mask view (tints the unselected area). View state: no undo step. */
     setQuickMask(on: boolean): void;

package/dist/image-editor/controller.d.ts

@@ -1,6 +1,7 @@
 import { AdjustmentKind, AdjustmentLayer, AdjustmentParamsMap, Annotation, CreateAnnotationPayload, AspectRatio, CropBox, DepthMaskOptions, ExportOptions, ImageAdjustments, ImageDimensions, ImageEditorFit, ImageEditorOptions, ImageEditorState, ImageEditorTool, ImageTransform, ImagePoint, SerializedImageEditorState } from './types.js';
 import { type PathToSelectionOptions, type SelectionToPathOptions } from './selection/path.js';
 import { type MagneticEdgeOptions } from './selection/magnetic.js';
+import { type ObjectTarget } from './selection/segment/grabcut.js';
 import { RenderOptions } from './renderer.js';
 import { type BlendMode } from './blend.js';
 import type { ImageHistogram } from './histogram.js';
@@ -151,6 +152,15 @@ export interface QuickSelectCommandOptions {
     /** Smoother, less blocky edges (Photoshop's Auto-Enhance). Default false. */
     enhanceEdge?: boolean;
 }
+/** Options of {@link ImageEditorController.selectObject}. */
+export interface SelectObjectCommandOptions {
+    /** How the object combines with the selection (default `replace`). */
+    mode?: SelectionMode;
+    /** Sample every layer (default true) or only the active pixel layer. */
+    sampleAllLayers?: boolean;
+    /** Smoother, less blocky edges (Auto-Enhance). Default false. */
+    enhanceEdge?: boolean;
+}
 /** A new adjustment layer: its kind plus optional initial values and position. */
 export interface AdjustmentLayerInit<K extends AdjustmentKind = AdjustmentKind> extends AdjustmentLayerUpdate<K> {
     kind: K;
@@ -664,7 +674,7 @@ export declare class ImageEditorController {
      * or those drawn while a result was rendering, once it is in. A cache refresh: no undo step.
      */
     private refreshEffectSurfaces;
-    /** 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(): SegmentationProvider | null;
     /** Registers (or with `null` removes) the segmentation provider. Not an edit: no undo step. */
     setSegmentationProvider(provider: SegmentationProvider | null): void;
@@ -1523,6 +1533,13 @@ export declare class ImageEditorController {
      * one undo step. Resolves to the resulting selection.
      */
     quickSelect(strokes: ImagePoint[][], options?: QuickSelectCommandOptions): Promise<SelectionMask | null>;
+    /**
+     * Object Selection: the object inside `target.rect` (natural pixels; what is outside the box is
+     * background) or under `target.point`, found by GrabCut (colour models of object and background
+     * plus a graph cut along edges), combined with the selection by `mode` as one undo step.
+     * Resolves to the resulting selection.
+     */
+    selectObject(target: ObjectTarget, options?: SelectObjectCommandOptions): Promise<SelectionMask | null>;
     /**
      * Supplies the pixels the selection tools sample (natural size RGBA), e.g. decoded in a worker
      * or in a test; `null` goes back to reading the source image. Without a canvas (Node, workers)
@@ -1596,19 +1613,25 @@ export declare class ImageEditorController {
      * 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.
      */
-    selectSubject(target: string, options?: SelectionCommandOptions & {
+    selectSubject(target?: string, options?: SelectionCommandOptions & {
         maxSegments?: number;
         signal?: AbortSignal;
         /** Called with the outlines found (image pixels; a mask-only result's bounds) before the selection changes, e.g. to trace them with an agent's cursor. */
         beforeApply?: (outlines: ImagePoint[][]) => void | Promise<void>;
+        /** Without a model: smoother, less blocky edges (Auto-Enhance). */
+        enhanceEdge?: boolean;
     }): Promise<{
         segments: {
             label: string;
             bounds: CropBox | null;
             score?: number;
         }[];
+        method: 'model' | 'saliency';
+        note?: string;
     }>;
     /** Quick Mask view (tints the unselected area). View state: no undo step. */
     setQuickMask(on: boolean): void;