@pixerate/editor 0.208.0 → 0.210.0

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

@@ -1,4 +1,4 @@
-import { AdjustmentKind, AdjustmentLayer, AdjustmentParamsMap, Annotation, CreateAnnotationPayload, AspectRatio, CropBox, DepthMaskOptions, ExportOptions, ImageAdjustments, ImageDimensions, ImageEditorFit, ImageEditorOptions, ImageEditorState, ImageEditorTool, ImageTransform, ImagePoint, SerializedImageEditorState } from './types.cjs';
+import { AdjustmentKind, AdjustmentLayer, AdjustmentParamsMap, Annotation, CreateAnnotationPayload, AspectRatio, CropBox, DepthMaskOptions, ExportOptions, ImageAdjustments, ImageDimensions, ImageEditorFit, ImageEditorOptions, ImageEditorState, ImageEditorTool, ImageTransform, ImagePoint, SerializedImageEditorState, DocumentOpener } 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';
@@ -168,7 +168,7 @@ export interface FocusAreaCommandOptions extends FocusAreaOptions {
     sampleAllLayers?: boolean;
 }
 /** Where Select and Mask puts its result (Photoshop's Output To). */
-export type RefineOutput = 'selection' | 'layer-mask' | 'new-layer' | 'new-layer-with-mask';
+export type RefineOutput = 'selection' | 'layer-mask' | 'new-layer' | 'new-layer-with-mask' | 'new-document' | 'new-document-with-mask';
 /** What {@link ImageEditorController.refineSelectionTo} made. */
 export interface RefineOutputResult {
     output: RefineOutput;
@@ -176,6 +176,8 @@ export interface RefineOutputResult {
     layerId?: string;
     /** The layer it made (`new-layer`, `new-layer-with-mask`). */
     newLayerId?: string;
+    /** The id the host's document opener returned (`new-document`, `new-document-with-mask`). */
+    documentId?: string;
     /** How the edge was refined: by colour, or with the segmentation model (object aware). */
     refineMode: 'color' | 'object';
 }
@@ -486,6 +488,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 {
@@ -691,6 +718,7 @@ export declare class ImageEditorController {
     /** The segmentation provider behind `selectSubject` (see `setSegmentationProvider`). */
     private segmentation;
     private selectionWorker;
+    private documentOpener;
     /** The effects provider slot (see `setEffectsProvider`). */
     readonly effects: EffectsSlot;
     /** Renders provider effects: effect smart filter results and effect layers. */
@@ -726,6 +754,24 @@ export declare class ImageEditorController {
      * A worker that is cancelled or fails is replaced by a fresh one on the next job.
      */
     setSelectionWorker(factory: SelectionWorkerFactory | null): void;
+    /** Sets (or with `null` removes) how new documents are opened (see `DocumentOpener`). Not an edit. */
+    setDocumentOpener(opener: DocumentOpener | null): void;
+    /** Whether the host can open new documents (the New Document outputs are available). */
+    get canOpenDocuments(): boolean;
+    /**
+     * A new one-layer document from the selection (or `options.selection`) on a pixel layer
+     * (`layerId`, default the active one), the size of this image: the selected pixels on
+     * transparency, or with `withMask` the whole layer masked by the selection. This document is
+     * not changed. `decontaminate` (0..100) cleans the soft edge's colours as the new-layer
+     * outputs do.
+     */
+    documentFromSelection(options?: {
+        layerId?: string;
+        withMask?: boolean;
+        selection?: SelectionMask | null;
+        decontaminate?: number;
+        radius?: number;
+    }): SerializedLayeredImageEditorState;
     /** Whether the long selections run in a worker. */
     get hasSelectionWorker(): boolean;
     /**
@@ -1431,13 +1477,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. */
@@ -1696,6 +1776,8 @@ export declare class ImageEditorController {
      * its alpha.
      */
     private decontaminateLayer;
+    /** `layer`'s surface with Decontaminate Colors applied along `coverage`'s soft edge, colours read from `source`. */
+    private decontaminatedSurface;
     /**
      * Loads a selection from a mask image (an AI segmentation, a saved mask): a data URL / URL or
      * RGBA pixels, by luminance (white = selected) or a channel. Any size; it is resampled.

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

@@ -1,4 +1,4 @@
-import { AdjustmentKind, AdjustmentLayer, AdjustmentParamsMap, Annotation, CreateAnnotationPayload, AspectRatio, CropBox, DepthMaskOptions, ExportOptions, ImageAdjustments, ImageDimensions, ImageEditorFit, ImageEditorOptions, ImageEditorState, ImageEditorTool, ImageTransform, ImagePoint, SerializedImageEditorState } from './types.js';
+import { AdjustmentKind, AdjustmentLayer, AdjustmentParamsMap, Annotation, CreateAnnotationPayload, AspectRatio, CropBox, DepthMaskOptions, ExportOptions, ImageAdjustments, ImageDimensions, ImageEditorFit, ImageEditorOptions, ImageEditorState, ImageEditorTool, ImageTransform, ImagePoint, SerializedImageEditorState, DocumentOpener } 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';
@@ -168,7 +168,7 @@ export interface FocusAreaCommandOptions extends FocusAreaOptions {
     sampleAllLayers?: boolean;
 }
 /** Where Select and Mask puts its result (Photoshop's Output To). */
-export type RefineOutput = 'selection' | 'layer-mask' | 'new-layer' | 'new-layer-with-mask';
+export type RefineOutput = 'selection' | 'layer-mask' | 'new-layer' | 'new-layer-with-mask' | 'new-document' | 'new-document-with-mask';
 /** What {@link ImageEditorController.refineSelectionTo} made. */
 export interface RefineOutputResult {
     output: RefineOutput;
@@ -176,6 +176,8 @@ export interface RefineOutputResult {
     layerId?: string;
     /** The layer it made (`new-layer`, `new-layer-with-mask`). */
     newLayerId?: string;
+    /** The id the host's document opener returned (`new-document`, `new-document-with-mask`). */
+    documentId?: string;
     /** How the edge was refined: by colour, or with the segmentation model (object aware). */
     refineMode: 'color' | 'object';
 }
@@ -486,6 +488,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 {
@@ -691,6 +718,7 @@ export declare class ImageEditorController {
     /** The segmentation provider behind `selectSubject` (see `setSegmentationProvider`). */
     private segmentation;
     private selectionWorker;
+    private documentOpener;
     /** The effects provider slot (see `setEffectsProvider`). */
     readonly effects: EffectsSlot;
     /** Renders provider effects: effect smart filter results and effect layers. */
@@ -726,6 +754,24 @@ export declare class ImageEditorController {
      * A worker that is cancelled or fails is replaced by a fresh one on the next job.
      */
     setSelectionWorker(factory: SelectionWorkerFactory | null): void;
+    /** Sets (or with `null` removes) how new documents are opened (see `DocumentOpener`). Not an edit. */
+    setDocumentOpener(opener: DocumentOpener | null): void;
+    /** Whether the host can open new documents (the New Document outputs are available). */
+    get canOpenDocuments(): boolean;
+    /**
+     * A new one-layer document from the selection (or `options.selection`) on a pixel layer
+     * (`layerId`, default the active one), the size of this image: the selected pixels on
+     * transparency, or with `withMask` the whole layer masked by the selection. This document is
+     * not changed. `decontaminate` (0..100) cleans the soft edge's colours as the new-layer
+     * outputs do.
+     */
+    documentFromSelection(options?: {
+        layerId?: string;
+        withMask?: boolean;
+        selection?: SelectionMask | null;
+        decontaminate?: number;
+        radius?: number;
+    }): SerializedLayeredImageEditorState;
     /** Whether the long selections run in a worker. */
     get hasSelectionWorker(): boolean;
     /**
@@ -1431,13 +1477,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. */
@@ -1696,6 +1776,8 @@ export declare class ImageEditorController {
      * its alpha.
      */
     private decontaminateLayer;
+    /** `layer`'s surface with Decontaminate Colors applied along `coverage`'s soft edge, colours read from `source`. */
+    private decontaminatedSurface;
     /**
      * Loads a selection from a mask image (an AI segmentation, a saved mask): a data URL / URL or
      * RGBA pixels, by luminance (white = selected) or a channel. Any size; it is resampled.