@pixerate/editor 0.209.0 → 0.211.0

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

@@ -2,6 +2,7 @@ import { AdjustmentKind, AdjustmentLayer, AdjustmentParamsMap, Annotation, Creat
 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 { type DocumentPath } from './paths.cjs';
 import { type SelectionJob, type SelectionJobResult, type SelectionWorkerFactory } from './selection/worker.cjs';
 import type { SelectionProgress } from './selection/segment/work.cjs';
 import type { FocusAreaOptions } from './selection/segment/focus.cjs';
@@ -488,6 +489,31 @@ export interface ContentAwareFillOptions {
     sampleRadius?: number;
     /** Random seed: the same seed gives the same fill (default 0). */
     seed?: number;
+    /**
+     * Where the fill may copy from (natural pixels), instead of the automatic ring around the
+     * selection: a mask (the Content-Aware Fill workspace's painted area), an alpha channel, or
+     * rectangles. `excludeRects` are never copied from, whichever way the area is given.
+     */
+    samplingArea?: SelectionMask | null;
+    samplingChannelId?: string;
+    sampleRects?: CropBox[];
+    excludeRects?: CropBox[];
+}
+/** What a Content-Aware Fill works on: the selection's window of a pixel layer (see `prepareContentAwareFill`). */
+export interface ContentAwareFillPlan {
+    layerId: string;
+    /** The window it fills and samples in (document pixels). */
+    window: CropBox;
+    /** The selection's bounds. */
+    bounds: CropBox;
+    /** The layer's pixels in the window, RGBA. */
+    before: Uint8ClampedArray;
+    /** 1 where the selection covers (the hole), per window pixel. */
+    hole: Uint8Array;
+    /** The selection's coverage 0..255 per window pixel. */
+    coverage: Uint8Array;
+    /** 1 where the fill may not copy from, per window pixel (null: everywhere outside the hole). */
+    exclude: Uint8Array | null;
 }
 /** Pixels on the editor's clipboard: RGBA, and where they were copied from (document pixels). */
 export interface ClipboardImage extends PixelBuffer {
@@ -1062,6 +1088,50 @@ export declare class ImageEditorController {
     pathToSelection(path: VectorMaskPathInput, options?: PathToSelectionOptions & {
         mode?: SelectionMode;
     }): boolean;
+    /** The document's paths: saved paths and the Work Path, in panel order. */
+    getPaths(): readonly DocumentPath[];
+    getPath(id: string): DocumentPath | null;
+    private requirePath;
+    /** Selects a path in the Paths panel (or none). View state: no undo step. */
+    setActivePath(id: string | null): void;
+    private commitPaths;
+    /**
+     * Paths › Make Work Path: the selection's outline, traced, becomes the Work Path (replacing the
+     * last one, unless it was saved). One undo step. Returns the path.
+     */
+    makeWorkPath(options?: SelectionToPathOptions): DocumentPath;
+    /** A new saved path from geometry (`shape`, `subpaths` or `components`). One undo step. */
+    addPath(input: VectorMaskPathInput & {
+        name?: string;
+    }): DocumentPath;
+    /** Replaces a path's geometry (its name is kept). One undo step. */
+    setPathGeometry(id: string, input: VectorMaskPathInput): DocumentPath;
+    /** Renames a path; renaming the Work Path saves it (Photoshop's Save Path). One undo step. */
+    renamePath(id: string, name: string): DocumentPath;
+    /** Duplicates a path as a saved path. One undo step. */
+    duplicatePath(id: string, name?: string): DocumentPath;
+    /** Deletes a path. One undo step. */
+    deletePath(id: string): void;
+    /** The area a path fills over the image, as a selection mask. */
+    private pathArea;
+    /** Paths › Make Selection: loads a path as the selection, combined by `mode`. One undo step. */
+    loadPathAsSelection(id: string, options?: PathToSelectionOptions & {
+        mode?: SelectionMode;
+    }): boolean;
+    /**
+     * Paths › Fill Path: fills the path's area on a pixel layer (default the active one) with a
+     * colour (default the foreground). The selection is not changed. One undo step.
+     */
+    fillPath(id: string, options?: Omit<FillOptions, 'useSelection'>): PaintStrokeResult;
+    /**
+     * Paths › Stroke Path: strokes along the path's outline on a pixel layer (default the active
+     * one), `width` px wide and centred on it. The selection is not changed. One undo step.
+     */
+    strokePath(id: string, options: Omit<StrokeSelectionOptions, 'location'>): PaintStrokeResult;
+    /** Paths › Add Vector Mask: masks a layer (default the active one) with a document path. One undo step. */
+    addVectorMaskFromPath(pathId: string, layerId?: string): VectorMask;
+    /** Runs `fn` with `mask` as the selection, then puts the selection back, all as one undo step. */
+    private withSelection;
     /** Replaces a vector mask's path (its properties are kept). One undo step. Returns the vector mask. */
     setVectorMaskPath(id: string, path: VectorMaskPathInput): VectorMask;
     /** Changes a vector mask's enabled, linked, inverted, density or feather (the path is kept). One undo step. */
@@ -1452,13 +1522,47 @@ export declare class ImageEditorController {
      * (PatchMatch, as the Spot Healing Brush's content-aware mode), blended by the selection's
      * coverage. `output` `current` paints into the layer; `new-layer` puts the fill on a new layer
      * above it. Samples within `sampleRadius` px of the selection (default its larger side, at
-     * least 32). Deterministic for a `seed`. One undo step. 8-bit documents only for now.
+     * least 32), or from the given sampling area. Deterministic for a `seed`. One undo step.
+     * 8-bit documents only for now. Runs here; see `contentAwareFillAsync` for the worker.
      */
     contentAwareFill(options?: ContentAwareFillOptions): {
         layerId: string;
         bounds: CropBox;
         output: 'current' | 'new-layer';
     };
+    /**
+     * `contentAwareFill` with the synthesis in the selection worker when there is one, with
+     * `signal` and `onProgress`. The layer is checked again before the result lands.
+     */
+    contentAwareFillAsync(options?: ContentAwareFillOptions & {
+        signal?: AbortSignal;
+        onProgress?: SelectionProgress;
+    }): Promise<{
+        layerId: string;
+        bounds: CropBox;
+        output: 'current' | 'new-layer';
+    }>;
+    /**
+     * The fill without changing anything: the window, its pixels before and after (RGBA, the fill
+     * blended by the selection's coverage) and the sampling area used, for a preview.
+     */
+    previewContentAwareFill(options?: ContentAwareFillOptions & {
+        signal?: AbortSignal;
+        onProgress?: SelectionProgress;
+    }): Promise<{
+        plan: ContentAwareFillPlan;
+        after: Uint8ClampedArray;
+    }>;
+    private synthesiseFill;
+    /**
+     * Checks and gathers what a Content-Aware Fill needs: the selection, the 8-bit pixel layer, the
+     * window around the selection (and the sampling area), and which pixels it may copy from.
+     */
+    prepareContentAwareFill(options?: ContentAwareFillOptions): ContentAwareFillPlan;
+    /** The window's pixels with `filled` blended in by the coverage (`current`), or the fill alone, its alpha by the coverage (`new-layer`). */
+    private blendFill;
+    /** Puts a computed fill into the document as one undo step. */
+    private applyContentAwareFill;
     /** The pixel clipboard (Copy / Cut), or null. */
     private clipboard;
     /** What Copy or Cut last put on the editor's clipboard, or null. */
@@ -1568,6 +1672,12 @@ export declare class ImageEditorController {
      * Returns false when nothing changed.
      */
     setSelection(mask: SelectionMask | null, mode?: SelectionMode): boolean;
+    /**
+     * Shows `mask` in place of the selection while a gesture runs (Quick Selection as the brush
+     * moves; `null` shows nothing selected), or with `undefined` stops. View state only: no undo
+     * step, not saved.
+     */
+    setSelectionPreview(mask: SelectionMask | null | undefined): void;
     /** Select › All. */
     selectAll(): boolean;
     /** Select › Deselect. */

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

@@ -2,6 +2,7 @@ import { AdjustmentKind, AdjustmentLayer, AdjustmentParamsMap, Annotation, Creat
 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 { type DocumentPath } from './paths.js';
 import { type SelectionJob, type SelectionJobResult, type SelectionWorkerFactory } from './selection/worker.js';
 import type { SelectionProgress } from './selection/segment/work.js';
 import type { FocusAreaOptions } from './selection/segment/focus.js';
@@ -488,6 +489,31 @@ export interface ContentAwareFillOptions {
     sampleRadius?: number;
     /** Random seed: the same seed gives the same fill (default 0). */
     seed?: number;
+    /**
+     * Where the fill may copy from (natural pixels), instead of the automatic ring around the
+     * selection: a mask (the Content-Aware Fill workspace's painted area), an alpha channel, or
+     * rectangles. `excludeRects` are never copied from, whichever way the area is given.
+     */
+    samplingArea?: SelectionMask | null;
+    samplingChannelId?: string;
+    sampleRects?: CropBox[];
+    excludeRects?: CropBox[];
+}
+/** What a Content-Aware Fill works on: the selection's window of a pixel layer (see `prepareContentAwareFill`). */
+export interface ContentAwareFillPlan {
+    layerId: string;
+    /** The window it fills and samples in (document pixels). */
+    window: CropBox;
+    /** The selection's bounds. */
+    bounds: CropBox;
+    /** The layer's pixels in the window, RGBA. */
+    before: Uint8ClampedArray;
+    /** 1 where the selection covers (the hole), per window pixel. */
+    hole: Uint8Array;
+    /** The selection's coverage 0..255 per window pixel. */
+    coverage: Uint8Array;
+    /** 1 where the fill may not copy from, per window pixel (null: everywhere outside the hole). */
+    exclude: Uint8Array | null;
 }
 /** Pixels on the editor's clipboard: RGBA, and where they were copied from (document pixels). */
 export interface ClipboardImage extends PixelBuffer {
@@ -1062,6 +1088,50 @@ export declare class ImageEditorController {
     pathToSelection(path: VectorMaskPathInput, options?: PathToSelectionOptions & {
         mode?: SelectionMode;
     }): boolean;
+    /** The document's paths: saved paths and the Work Path, in panel order. */
+    getPaths(): readonly DocumentPath[];
+    getPath(id: string): DocumentPath | null;
+    private requirePath;
+    /** Selects a path in the Paths panel (or none). View state: no undo step. */
+    setActivePath(id: string | null): void;
+    private commitPaths;
+    /**
+     * Paths › Make Work Path: the selection's outline, traced, becomes the Work Path (replacing the
+     * last one, unless it was saved). One undo step. Returns the path.
+     */
+    makeWorkPath(options?: SelectionToPathOptions): DocumentPath;
+    /** A new saved path from geometry (`shape`, `subpaths` or `components`). One undo step. */
+    addPath(input: VectorMaskPathInput & {
+        name?: string;
+    }): DocumentPath;
+    /** Replaces a path's geometry (its name is kept). One undo step. */
+    setPathGeometry(id: string, input: VectorMaskPathInput): DocumentPath;
+    /** Renames a path; renaming the Work Path saves it (Photoshop's Save Path). One undo step. */
+    renamePath(id: string, name: string): DocumentPath;
+    /** Duplicates a path as a saved path. One undo step. */
+    duplicatePath(id: string, name?: string): DocumentPath;
+    /** Deletes a path. One undo step. */
+    deletePath(id: string): void;
+    /** The area a path fills over the image, as a selection mask. */
+    private pathArea;
+    /** Paths › Make Selection: loads a path as the selection, combined by `mode`. One undo step. */
+    loadPathAsSelection(id: string, options?: PathToSelectionOptions & {
+        mode?: SelectionMode;
+    }): boolean;
+    /**
+     * Paths › Fill Path: fills the path's area on a pixel layer (default the active one) with a
+     * colour (default the foreground). The selection is not changed. One undo step.
+     */
+    fillPath(id: string, options?: Omit<FillOptions, 'useSelection'>): PaintStrokeResult;
+    /**
+     * Paths › Stroke Path: strokes along the path's outline on a pixel layer (default the active
+     * one), `width` px wide and centred on it. The selection is not changed. One undo step.
+     */
+    strokePath(id: string, options: Omit<StrokeSelectionOptions, 'location'>): PaintStrokeResult;
+    /** Paths › Add Vector Mask: masks a layer (default the active one) with a document path. One undo step. */
+    addVectorMaskFromPath(pathId: string, layerId?: string): VectorMask;
+    /** Runs `fn` with `mask` as the selection, then puts the selection back, all as one undo step. */
+    private withSelection;
     /** Replaces a vector mask's path (its properties are kept). One undo step. Returns the vector mask. */
     setVectorMaskPath(id: string, path: VectorMaskPathInput): VectorMask;
     /** Changes a vector mask's enabled, linked, inverted, density or feather (the path is kept). One undo step. */
@@ -1452,13 +1522,47 @@ export declare class ImageEditorController {
      * (PatchMatch, as the Spot Healing Brush's content-aware mode), blended by the selection's
      * coverage. `output` `current` paints into the layer; `new-layer` puts the fill on a new layer
      * above it. Samples within `sampleRadius` px of the selection (default its larger side, at
-     * least 32). Deterministic for a `seed`. One undo step. 8-bit documents only for now.
+     * least 32), or from the given sampling area. Deterministic for a `seed`. One undo step.
+     * 8-bit documents only for now. Runs here; see `contentAwareFillAsync` for the worker.
      */
     contentAwareFill(options?: ContentAwareFillOptions): {
         layerId: string;
         bounds: CropBox;
         output: 'current' | 'new-layer';
     };
+    /**
+     * `contentAwareFill` with the synthesis in the selection worker when there is one, with
+     * `signal` and `onProgress`. The layer is checked again before the result lands.
+     */
+    contentAwareFillAsync(options?: ContentAwareFillOptions & {
+        signal?: AbortSignal;
+        onProgress?: SelectionProgress;
+    }): Promise<{
+        layerId: string;
+        bounds: CropBox;
+        output: 'current' | 'new-layer';
+    }>;
+    /**
+     * The fill without changing anything: the window, its pixels before and after (RGBA, the fill
+     * blended by the selection's coverage) and the sampling area used, for a preview.
+     */
+    previewContentAwareFill(options?: ContentAwareFillOptions & {
+        signal?: AbortSignal;
+        onProgress?: SelectionProgress;
+    }): Promise<{
+        plan: ContentAwareFillPlan;
+        after: Uint8ClampedArray;
+    }>;
+    private synthesiseFill;
+    /**
+     * Checks and gathers what a Content-Aware Fill needs: the selection, the 8-bit pixel layer, the
+     * window around the selection (and the sampling area), and which pixels it may copy from.
+     */
+    prepareContentAwareFill(options?: ContentAwareFillOptions): ContentAwareFillPlan;
+    /** The window's pixels with `filled` blended in by the coverage (`current`), or the fill alone, its alpha by the coverage (`new-layer`). */
+    private blendFill;
+    /** Puts a computed fill into the document as one undo step. */
+    private applyContentAwareFill;
     /** The pixel clipboard (Copy / Cut), or null. */
     private clipboard;
     /** What Copy or Cut last put on the editor's clipboard, or null. */
@@ -1568,6 +1672,12 @@ export declare class ImageEditorController {
      * Returns false when nothing changed.
      */
     setSelection(mask: SelectionMask | null, mode?: SelectionMode): boolean;
+    /**
+     * Shows `mask` in place of the selection while a gesture runs (Quick Selection as the brush
+     * moves; `null` shows nothing selected), or with `undefined` stops. View state only: no undo
+     * step, not saved.
+     */
+    setSelectionPreview(mask: SelectionMask | null | undefined): void;
     /** Select › All. */
     selectAll(): boolean;
     /** Select › Deselect. */