@pixerate/editor 0.11.0 → 0.13.0

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

@@ -0,0 +1,372 @@
+interface ImageDimensions {
+    width: number;
+    height: number;
+}
+interface ImagePoint {
+    x: number;
+    y: number;
+}
+interface CropBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+type AspectRatio = number | null;
+interface ImageTransform {
+    rotate: number;
+    flipH: boolean;
+    flipV: boolean;
+}
+interface ImageAdjustments {
+    brightness: number;
+    contrast: number;
+    saturation: number;
+    exposure: number;
+    temperature: number;
+    blur: number;
+    opacity: number;
+}
+interface DepthMaskOptions {
+    enabled: boolean;
+    maskSource: string | null;
+    mode: 'threshold' | 'brightness';
+    depthRange: [number, number];
+    softness: number;
+    invert: boolean;
+}
+type AnnotationType = 'pen' | 'rect' | 'circle' | 'arrow' | 'line' | 'text' | 'image';
+interface BaseAnnotation {
+    id: string;
+    type: AnnotationType;
+    x: number;
+    y: number;
+    rotation?: number;
+    opacity?: number;
+}
+interface PenAnnotation extends BaseAnnotation {
+    type: 'pen';
+    points: ImagePoint[];
+    strokeColor: string;
+    strokeWidth: number;
+}
+interface RectAnnotation extends BaseAnnotation {
+    type: 'rect';
+    width: number;
+    height: number;
+    strokeColor: string;
+    strokeWidth: number;
+    fillColor?: string;
+    cornerRadius?: number;
+}
+interface CircleAnnotation extends BaseAnnotation {
+    type: 'circle';
+    radiusX: number;
+    radiusY: number;
+    strokeColor: string;
+    strokeWidth: number;
+    fillColor?: string;
+}
+interface ArrowAnnotation extends BaseAnnotation {
+    type: 'arrow';
+    endX: number;
+    endY: number;
+    strokeColor: string;
+    strokeWidth: number;
+}
+interface LineAnnotation extends BaseAnnotation {
+    type: 'line';
+    endX: number;
+    endY: number;
+    strokeColor: string;
+    strokeWidth: number;
+}
+interface TextAnnotation extends BaseAnnotation {
+    type: 'text';
+    text: string;
+    fontSize: number;
+    fontFamily?: string;
+    color: string;
+    fontWeight?: string | number;
+}
+interface ImageAnnotation extends BaseAnnotation {
+    type: 'image';
+    src: string;
+    width: number;
+    height: number;
+}
+type Annotation = PenAnnotation | RectAnnotation | CircleAnnotation | ArrowAnnotation | LineAnnotation | TextAnnotation | ImageAnnotation;
+type CreateAnnotationPayload = Omit<PenAnnotation, 'id'> | Omit<RectAnnotation, 'id'> | Omit<CircleAnnotation, 'id'> | Omit<ArrowAnnotation, 'id'> | Omit<LineAnnotation, 'id'> | Omit<TextAnnotation, 'id'> | Omit<ImageAnnotation, 'id'>;
+type ImageEditorTool = 'select' | 'crop' | 'pen' | 'rect' | 'circle' | 'arrow' | 'line' | 'text' | 'watermark';
+interface ImageEditorState {
+    sourceUrl: string | null;
+    imageDimensions: ImageDimensions;
+    crop: CropBox | null;
+    transform: ImageTransform;
+    adjustments: ImageAdjustments;
+    depthMask: DepthMaskOptions;
+    annotations: Annotation[];
+    selectedAnnotationId: string | null;
+    activeTool: ImageEditorTool;
+    zoom: number;
+    pan: ImagePoint;
+    isOriginalCompared: boolean;
+}
+interface SerializedImageEditorState {
+    version: 1;
+    crop: CropBox | null;
+    transform: ImageTransform;
+    adjustments: ImageAdjustments;
+    depthMask: DepthMaskOptions;
+    annotations: Annotation[];
+}
+interface ExportOptions {
+    format?: 'image/png' | 'image/jpeg' | 'image/webp';
+    quality?: number;
+    width?: number;
+    height?: number;
+    includeAnnotations?: boolean;
+}
+interface ImageEditorOptions {
+    image?: string | HTMLImageElement;
+    initialState?: Partial<SerializedImageEditorState>;
+    onStateChange?: (state: ImageEditorState) => void;
+    maxHistoryDepth?: number;
+}
+interface InpaintOptions {
+    prompt: string;
+    imageDataUrl: string;
+    maskDataUrl?: string;
+    cropBox?: CropBox | null;
+}
+interface RemoveBackgroundOptions {
+    imageDataUrl: string;
+}
+type InpaintHook = (options: InpaintOptions) => Promise<string | void> | string | void;
+type RemoveBackgroundHook = (options: RemoveBackgroundOptions) => Promise<string | void> | string | void;
+interface ImageEditorAIHooks {
+    onInpaint?: InpaintHook;
+    onRemoveBackground?: RemoveBackgroundHook;
+}
+
+/**
+ * Applies color and tone adjustments (brightness, contrast, saturation, exposure, temperature, opacity, blur)
+ * directly to the pixel data of an ImageData buffer.
+ */
+declare function applyAdjustments(imageData: ImageData, adjustments: ImageAdjustments): void;
+/**
+ * Blends a depth/alpha mask into the main image data based on Gleamforge depth masking.
+ * Supports threshold range with softness gradation, brightness mode, and optional inversion.
+ */
+declare function applyDepthMask(mainImageData: ImageData, maskImageData: ImageData, options: DepthMaskOptions): void;
+/**
+ * Removes alpha channel by setting all alpha bytes to 255 (completely opaque).
+ * From Gleamforge image-filters.ts.
+ */
+declare function removeAlpha(imageData: ImageData): void;
+
+interface RenderOptions {
+    viewportWidth?: number;
+    viewportHeight?: number;
+    showCropOverlay?: boolean;
+    showSelectionOverlay?: boolean;
+    interactive?: boolean;
+    draftAnnotation?: Annotation | null;
+    draftCrop?: CropBox | null;
+}
+/**
+ * Image Cache to avoid refetching HTMLImageElement objects repeatedly during re-renders.
+ */
+declare class ImageCache {
+    private cache;
+    get(src: string): Promise<HTMLImageElement>;
+    set(src: string, img: HTMLImageElement): void;
+    clear(): void;
+}
+declare const globalImageCache: ImageCache;
+/**
+ * Renders an image with all its transformations, filters, depth masks, and annotations
+ * to a target HTMLCanvasElement.
+ */
+declare class ImageEditorRenderer {
+    imageCache: ImageCache;
+    private cachedBaseCanvas;
+    private cachedBaseKey;
+    /**
+     * Helper to create a canvas element safely in browser/JSDOM.
+     */
+    createCanvas(width: number, height: number): HTMLCanvasElement;
+    /**
+     * Renders the editor state onto a canvas (viewport or preview).
+     */
+    renderToCanvas(targetCanvas: HTMLCanvasElement, imageSource: CanvasImageSource | string, state: ImageEditorState, options?: RenderOptions): Promise<void>;
+    /**
+     * Draws an individual annotation onto the canvas.
+     */
+    drawAnnotation(ctx: CanvasRenderingContext2D, ann: Annotation): Promise<void>;
+    /**
+     * Draws selection box around active annotation.
+     */
+    private drawAnnotationSelection;
+    getAnnotationBounds(ann: Annotation): {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /**
+     * Draws a rule-of-thirds crop grid overlay.
+     */
+    private drawCropOverlay;
+    private drawFittedImage;
+    /**
+     * Performs an export render at exact pixel dimensions without zoom/pan viewport offsets.
+     */
+    renderExport(imageSource: CanvasImageSource | string, state: ImageEditorState, options?: ExportOptions): Promise<HTMLCanvasElement>;
+    /**
+     * Generates a binary mask canvas (white for mask/selected area, black for unmasked).
+     * Useful for AI inpainting and selective generative fill.
+     */
+    renderMask(state: ImageEditorState, options?: {
+        useAnnotations?: boolean;
+        useCrop?: boolean;
+    }): Promise<HTMLCanvasElement>;
+}
+
+declare const DEFAULT_ADJUSTMENTS: ImageAdjustments;
+declare const DEFAULT_TRANSFORM: ImageTransform;
+declare const DEFAULT_DEPTH_MASK: DepthMaskOptions;
+/**
+ * ImageEditorController manages the complete lifecycle, canvas rendering pipeline,
+ * tool interaction states, undo/redo history, serialization, and image export.
+ */
+declare class ImageEditorController {
+    private state;
+    private renderer;
+    private imageElement;
+    private listeners;
+    private onStateChange?;
+    private undoStack;
+    private redoStack;
+    private maxHistoryDepth;
+    private isApplyingHistory;
+    private initialSnapshot;
+    constructor(options?: ImageEditorOptions);
+    loadImage(src: string | HTMLImageElement): Promise<void>;
+    getImageElement(): CanvasImageSource | null;
+    getState(): ImageEditorState;
+    subscribe(listener: (state: ImageEditorState) => void): () => void;
+    private notify;
+    private recordHistory;
+    get canUndo(): boolean;
+    get canRedo(): boolean;
+    undo(): boolean;
+    redo(): boolean;
+    reset(): void;
+    setTool(tool: ImageEditorTool): void;
+    setCrop(crop: CropBox | null, addToHistory?: boolean): void;
+    applyCropPreset(ratio: AspectRatio): void;
+    resetCrop(): void;
+    rotate(degrees: number): void;
+    setRotation(degrees: number): void;
+    flipHorizontal(): void;
+    flipVertical(): void;
+    setAdjustments(partial: Partial<ImageAdjustments>, commitToHistory?: boolean): void;
+    resetAdjustments(): void;
+    setDepthMask(partial: Partial<DepthMaskOptions>): void;
+    resetDepthMask(): void;
+    addAnnotation(annotation: CreateAnnotationPayload): string;
+    updateAnnotation(id: string, partial: Partial<Annotation>, commitToHistory?: boolean): void;
+    removeAnnotation(id: string): void;
+    clearAnnotations(): void;
+    selectAnnotation(id: string | null): void;
+    setZoom(zoom: number): void;
+    zoomIn(factor?: number): void;
+    zoomOut(factor?: number): void;
+    resetZoom(): void;
+    setPan(pan: ImagePoint): void;
+    setComparing(comparing: boolean): void;
+    render(targetCanvas: HTMLCanvasElement, options?: RenderOptions): Promise<void>;
+    renderExport(options?: ExportOptions): Promise<HTMLCanvasElement>;
+    toDataURL(options?: ExportOptions): Promise<string>;
+    toBlob(options?: ExportOptions): Promise<Blob>;
+    renderMask(options?: {
+        useAnnotations?: boolean;
+        useCrop?: boolean;
+    }): Promise<HTMLCanvasElement>;
+    toMaskDataURL(options?: {
+        useAnnotations?: boolean;
+        useCrop?: boolean;
+    }): Promise<string>;
+    applyInpaintedImage(newDataUrl: string): Promise<void>;
+    applyBackgroundRemovedImage(newDataUrl: string): Promise<void>;
+    toJSON(): SerializedImageEditorState;
+    loadJSON(data: SerializedImageEditorState): void;
+    private serializeState;
+    private applySerializedState;
+}
+
+type CropHandle = 'nw' | 'ne' | 'se' | 'sw' | 'n' | 's' | 'e' | 'w' | 'inside' | null;
+interface ViewportMetrics {
+    vpWidth: number;
+    vpHeight: number;
+    centerX: number;
+    centerY: number;
+    baseW: number;
+    baseH: number;
+    fitScale: number;
+    renderW: number;
+    renderH: number;
+    totalScale: number;
+    imageRect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    cropRect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null;
+}
+/**
+ * Calculates current viewport projection metrics for canvas <-> image coordinate mapping.
+ */
+declare function getViewportMetrics(state: ImageEditorState, vpWidth: number, vpHeight: number, isActivelyCropping?: boolean, cropOverride?: CropBox | null): ViewportMetrics;
+/**
+ * Converts a point on the canvas (in internal canvas pixel space) to image/annotation pixel space.
+ */
+declare function canvasToImagePoint(canvasPt: ImagePoint, state: ImageEditorState, vpWidth: number, vpHeight: number, isActivelyCropping?: boolean): ImagePoint;
+/**
+ * Converts a point in image/annotation pixel space to internal canvas pixel space.
+ */
+declare function imageToCanvasPoint(imgPt: ImagePoint, state: ImageEditorState, vpWidth: number, vpHeight: number, isActivelyCropping?: boolean): ImagePoint;
+/**
+ * Hit-tests the crop box and its corner/edge handles given a canvas point.
+ */
+declare function hitTestCrop(canvasPt: ImagePoint, state: ImageEditorState, vpWidth: number, vpHeight: number, handleThreshold?: number, cropOverride?: CropBox | null): CropHandle;
+/**
+ * Returns CSS cursor style corresponding to a crop handle.
+ */
+declare function getCropCursor(handle: CropHandle): string;
+/**
+ * Calculates updated crop rectangle given a drag interaction.
+ */
+declare function calculateCropDrag(startCrop: CropBox, handle: CropHandle, startImgPt: ImagePoint, currentImgPt: ImagePoint, imgWidth: number, imgHeight: number, aspectRatio?: number | null): CropBox;
+/**
+ * Calculates bounding box of an annotation.
+ */
+declare function getAnnotationBounds(ann: Annotation): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/**
+ * Hit tests if a point in image space is within an annotation's bounds.
+ */
+declare function hitTestAnnotation(imgPt: ImagePoint, ann: Annotation, padding?: number): boolean;
+
+export { type Annotation, type AnnotationType, type ArrowAnnotation, type AspectRatio, type BaseAnnotation, type CircleAnnotation, type CreateAnnotationPayload, type CropBox, type CropHandle, DEFAULT_ADJUSTMENTS, DEFAULT_DEPTH_MASK, DEFAULT_TRANSFORM, type DepthMaskOptions, type ExportOptions, type ImageAdjustments, type ImageAnnotation, type ImageDimensions, type ImageEditorAIHooks, ImageEditorController, type ImageEditorOptions, ImageEditorRenderer, type ImageEditorState, type ImageEditorTool, type ImagePoint, type ImageTransform, type InpaintHook, type InpaintOptions, type LineAnnotation, type PenAnnotation, type RectAnnotation, type RemoveBackgroundHook, type RemoveBackgroundOptions, type RenderOptions, type SerializedImageEditorState, type TextAnnotation, type ViewportMetrics, applyAdjustments, applyDepthMask, calculateCropDrag, canvasToImagePoint, getAnnotationBounds, getCropCursor, getViewportMetrics, globalImageCache, hitTestAnnotation, hitTestCrop, imageToCanvasPoint, removeAlpha };