pixel-data-js 0.11.1 → 0.12.0

package/dist/index.prod.d.ts

@@ -653,34 +653,69 @@ declare function writeImageDataPixels(imageData: ImageData, data: Uint8ClampedAr
 declare function writeImageDataPixels(imageData: ImageData, data: Uint8ClampedArray, x: number, y: number, w: number, h: number): void;
 
 /**
- * Compressed data format for image processing optimization.
- * Representing an image as a grid of palette indices rather than raw RGBA values
- * significantly reduces memory overhead and optimizes pattern matching logic.
+ * Writes image data from a source to a target with support for clipping and alpha masking.
+ *
+ * @param target - The destination ImageData to write to.
+ * @param source - The source ImageData to read from.
+ * @param x - The x-coordinate in the target where drawing starts.
+ * @param y - The y-coordinate in the target where drawing starts.
+ * @param sx - The x-coordinate in the source to start copying from.
+ * @param sy - The y-coordinate in the source to start copying from.
+ * @param sw - The width of the rectangle to copy.
+ * @param sh - The height of the rectangle to copy.
+ * @param mask - An optional Uint8Array mask (0-255). 0 is transparent, 255 is opaque.
+ * @param maskType - type of mask
+ */
+declare function writeImageData(target: ImageData, source: ImageData, x: number, y: number, sx?: number, sy?: number, sw?: number, sh?: number, mask?: Uint8Array | null, maskType?: MaskType): void;
+
+/**
+ * Represents an image using a palette-based indexing system.
+ * Instead of storing 4 bytes (RGBA) per pixel, this class stores a single index
+ * into a color palette. This format is optimized for memory efficiency and
+ * high-speed pattern matching or recoloring operations.
  */
-type IndexedImage = {
+declare class IndexedImage {
     /** The width of the image in pixels. */
-    width: number;
+    readonly width: number;
     /** The height of the image in pixels. */
-    height: number;
+    readonly height: number;
+    /** Flat array of palette indices. Index = x + (y * width). */
+    readonly data: Int32Array;
+    /** The palette of unique 32-bit colors (ABGR/RGBA packed) found in the image. */
+    readonly palette: Uint32Array;
+    /** The specific index in the palette reserved for fully transparent pixels. */
+    readonly transparentPalletIndex: number;
     /**
-     * A flat array of indices where each value points to a color in the palette.
-     * Accessible via the formula: `index = x + (y * width)`.
+     * @param width - Image width.
+     * @param height - Image height.
+     * @param data - The indexed pixel data.
+     * @param palette - The array of packed colors.
+     * @param transparentPalletIndex - The index representing alpha 0.
      */
-    data: Int32Array;
+    constructor(width: number, height: number, data: Int32Array, palette: Uint32Array, transparentPalletIndex: number);
     /**
-     * A palette of packed 32-bit colors (ABGR).
+     * Creates an IndexedImage from standard browser ImageData.
+     * @param imageData - The source ImageData to convert.
+     * @returns A new IndexedImage instance.
      */
-    palette: Uint32Array;
+    static fromImageData(imageData: ImageData): IndexedImage;
     /**
-     * The specific index in the palette that represents a fully transparent pixel.
+     * Creates an IndexedImage from a raw byte buffer and dimensions.
+     * Any pixel with an alpha channel of 0 is normalized to the transparent palette index.
+     * @param data - Raw RGBA byte data.
+     * @param width - Image width.
+     * @param height - Image height.
+     * @returns A new IndexedImage instance.
      */
-    transparentPalletIndex: number;
-};
-/**
- * Converts standard ImageData into an IndexedImage format.
- */
-declare function makeIndexedImage(imageData: ImageData): IndexedImage;
-declare function makeIndexedImage(data: Uint8ClampedArray, width: number, height: number): IndexedImage;
+    static fromRaw(data: Uint8ClampedArray, width: number, height: number): IndexedImage;
+    /**
+     * Retrieves the 32-bit packed color value at the given coordinates.
+     * @param x - X coordinate.
+     * @param y - Y coordinate.
+     * @returns The packed color from the palette.
+     */
+    getColorAt(x: number, y: number): Color32;
+}
 
 /**
  * Calculates the frequency of each palette index based on the image data.
@@ -710,6 +745,11 @@ declare function indexedImageToAverageColor(indexedImage: IndexedImage, includeT
  */
 declare function resampleIndexedImage(source: IndexedImage, factor: number): IndexedImage;
 
+/**
+ * Converts an IndexedImage back into standard ImageData.
+ */
+declare function indexedImageToImageData(indexedImage: IndexedImage): ImageData;
+
 /**
  * A convenience wrapper that extracts the first {@link File} from an
  * {@link HTMLInputElement} change event and converts it into {@link ImageData}.
@@ -937,4 +977,4 @@ declare function rotatePixelData(pixelData: PixelData): void;
  */
 declare function trimRectBounds<T extends Rect | SelectionRect>(target: T, bounds: Rect): void;
 
-export { type AlphaMask, type AnyMask, type ApplyMaskOptions, type Base64EncodedUInt8Array, type BinaryMask, type BlendColor32, BlendMode, type BlendModeIndex, type BlendToIndexGetter, type Color32, type ColorBlendOptions, FAST_BLENDER_REGISTRY, FAST_BLEND_MODES, FAST_BLEND_MODE_BY_NAME, FAST_BLEND_TO_INDEX, type FastBlendModes, type FloodFillImageDataOptions, type FloodFillResult, INDEX_TO_FAST_BLEND, INDEX_TO_PERFECT_BLEND, type ImageDataLike, type IndexToBlendGetter, type IndexedImage, MaskType, PERFECT_BLENDER_REGISTRY, PERFECT_BLEND_MODES, PERFECT_BLEND_MODE_BY_NAME, PERFECT_BLEND_TO_INDEX, type PerfectBlendModes, type PixelBlendOptions, type PixelCanvas, PixelData, type PixelOptions, type Point, type RGBA, type Rect, type RegisteredFastBlender, type RegisteredPerfectBlender, type ReusableCanvas, type SelectionRect, type SerializedImageData, UnsupportedFormatError, applyMaskToPixelData, base64DecodeArrayBuffer, base64EncodeArrayBuffer, blendColorPixelData, blendPixelData, clearPixelData, color32ToCssRGBA, color32ToHex, colorBurnFast, colorBurnPerfect, colorDistance, colorDodgeFast, colorDodgePerfect, copyImageData, copyImageDataLike, copyMask, darkenFast, darkenPerfect, darkerFast, darkerPerfect, deserializeImageData, deserializeNullableImageData, deserializeRawImageData, differenceFast, differencePerfect, divideFast, dividePerfect, exclusionFast, exclusionPerfect, extractImageDataPixels, extractMask, fileInputChangeToImageData, fileToImageData, fillPixelData, floodFillSelection, getImageDataFromClipboard, getIndexedImageColorCounts, getSupportedPixelFormats, hardLightFast, hardLightPerfect, hardMixFast, hardMixPerfect, imageDataToAlphaMask, imageDataToDataUrl, imageDataToImgBlob, imgBlobToImageData, indexedImageToAverageColor, invertAlphaMask, invertBinaryMask, invertImageData, invertPixelData, lerpColor32, lerpColor32Fast, lightenFast, lightenPerfect, lighterFast, lighterPerfect, linearBurnFast, linearBurnPerfect, linearDodgeFast, linearDodgePerfect, linearLightFast, linearLightPerfect, makeIndexedImage, makePixelCanvas, makeReusableCanvas, mergeMasks, multiplyFast, multiplyPerfect, overlayFast, overlayPerfect, overwriteFast, overwritePerfect, packColor, packRGBA, pinLightFast, pinLightPerfect, pixelDataToAlphaMask, reflectPixelDataHorizontal, reflectPixelDataVertical, resampleImageData, resampleIndexedImage, resamplePixelData, resizeImageData, rotatePixelData, screenFast, screenPerfect, serializeImageData, serializeNullableImageData, softLightFast, softLightPerfect, sourceOverFast, sourceOverPerfect, subtractFast, subtractPerfect, trimRectBounds, unpackAlpha, unpackBlue, unpackColor, unpackColorTo, unpackGreen, unpackRed, vividLightFast, vividLightPerfect, writeImageDataPixels, writeImageDataToClipboard, writeImgBlobToClipboard };
+export { type AlphaMask, type AnyMask, type ApplyMaskOptions, type Base64EncodedUInt8Array, type BinaryMask, type BlendColor32, BlendMode, type BlendModeIndex, type BlendToIndexGetter, type Color32, type ColorBlendOptions, FAST_BLENDER_REGISTRY, FAST_BLEND_MODES, FAST_BLEND_MODE_BY_NAME, FAST_BLEND_TO_INDEX, type FastBlendModes, type FloodFillImageDataOptions, type FloodFillResult, INDEX_TO_FAST_BLEND, INDEX_TO_PERFECT_BLEND, type ImageDataLike, type IndexToBlendGetter, IndexedImage, MaskType, PERFECT_BLENDER_REGISTRY, PERFECT_BLEND_MODES, PERFECT_BLEND_MODE_BY_NAME, PERFECT_BLEND_TO_INDEX, type PerfectBlendModes, type PixelBlendOptions, type PixelCanvas, PixelData, type PixelOptions, type Point, type RGBA, type Rect, type RegisteredFastBlender, type RegisteredPerfectBlender, type ReusableCanvas, type SelectionRect, type SerializedImageData, UnsupportedFormatError, applyMaskToPixelData, base64DecodeArrayBuffer, base64EncodeArrayBuffer, blendColorPixelData, blendPixelData, clearPixelData, color32ToCssRGBA, color32ToHex, colorBurnFast, colorBurnPerfect, colorDistance, colorDodgeFast, colorDodgePerfect, copyImageData, copyImageDataLike, copyMask, darkenFast, darkenPerfect, darkerFast, darkerPerfect, deserializeImageData, deserializeNullableImageData, deserializeRawImageData, differenceFast, differencePerfect, divideFast, dividePerfect, exclusionFast, exclusionPerfect, extractImageDataPixels, extractMask, fileInputChangeToImageData, fileToImageData, fillPixelData, floodFillSelection, getImageDataFromClipboard, getIndexedImageColorCounts, getSupportedPixelFormats, hardLightFast, hardLightPerfect, hardMixFast, hardMixPerfect, imageDataToAlphaMask, imageDataToDataUrl, imageDataToImgBlob, imgBlobToImageData, indexedImageToAverageColor, indexedImageToImageData, invertAlphaMask, invertBinaryMask, invertImageData, invertPixelData, lerpColor32, lerpColor32Fast, lightenFast, lightenPerfect, lighterFast, lighterPerfect, linearBurnFast, linearBurnPerfect, linearDodgeFast, linearDodgePerfect, linearLightFast, linearLightPerfect, makePixelCanvas, makeReusableCanvas, mergeMasks, multiplyFast, multiplyPerfect, overlayFast, overlayPerfect, overwriteFast, overwritePerfect, packColor, packRGBA, pinLightFast, pinLightPerfect, pixelDataToAlphaMask, reflectPixelDataHorizontal, reflectPixelDataVertical, resampleImageData, resampleIndexedImage, resamplePixelData, resizeImageData, rotatePixelData, screenFast, screenPerfect, serializeImageData, serializeNullableImageData, softLightFast, softLightPerfect, sourceOverFast, sourceOverPerfect, subtractFast, subtractPerfect, trimRectBounds, unpackAlpha, unpackBlue, unpackColor, unpackColorTo, unpackGreen, unpackRed, vividLightFast, vividLightPerfect, writeImageData, writeImageDataPixels, writeImageDataToClipboard, writeImgBlobToClipboard };

package/dist/index.prod.js

@@ -1625,40 +1625,144 @@ function writeImageDataPixels(imageData, data, _x, _y, _w, _h) {
   }
 }
 
-// src/IndexedImage/IndexedImage.ts
-function makeIndexedImage(imageOrData, width, height) {
-  const isImageData = "width" in imageOrData;
-  const actualWidth = isImageData ? imageOrData.width : width;
-  const actualHeight = isImageData ? imageOrData.height : height;
-  const buffer = isImageData ? imageOrData.data.buffer : imageOrData.buffer;
-  const rawData = new Uint32Array(buffer);
-  const indexedData = new Int32Array(rawData.length);
-  const colorMap = /* @__PURE__ */ new Map();
-  const transparentColor = 0;
-  const transparentPalletIndex = 0;
-  colorMap.set(transparentColor, transparentPalletIndex);
-  for (let i = 0; i < rawData.length; i++) {
-    const pixel = rawData[i];
-    const alpha = pixel >>> 24 & 255;
-    const isTransparent = alpha === 0;
-    const colorKey = isTransparent ? transparentColor : pixel >>> 0;
-    let id = colorMap.get(colorKey);
-    if (id === void 0) {
-      id = colorMap.size;
-      colorMap.set(colorKey, id);
+// src/ImageData/writeImageData.ts
+function writeImageData(target, source, x, y, sx = 0, sy = 0, sw = source.width, sh = source.height, mask = null, maskType = 1 /* BINARY */) {
+  const dstW = target.width;
+  const dstH = target.height;
+  const dstData = target.data;
+  const srcW = source.width;
+  const srcData = source.data;
+  const x0 = Math.max(0, x);
+  const y0 = Math.max(0, y);
+  const x1 = Math.min(dstW, x + sw);
+  const y1 = Math.min(dstH, y + sh);
+  if (x1 <= x0 || y1 <= y0) {
+    return;
+  }
+  const useMask = !!mask;
+  const rowCount = y1 - y0;
+  const rowLenPixels = x1 - x0;
+  for (let row = 0; row < rowCount; row++) {
+    const dstY = y0 + row;
+    const srcY = sy + (dstY - y);
+    const srcXBase = sx + (x0 - x);
+    const dstStart = (dstY * dstW + x0) * 4;
+    const srcStart = (srcY * srcW + srcXBase) * 4;
+    if (useMask && mask) {
+      for (let ix = 0; ix < rowLenPixels; ix++) {
+        const mi = srcY * srcW + (srcXBase + ix);
+        const alpha = mask[mi];
+        if (alpha === 0) {
+          continue;
+        }
+        const di = dstStart + ix * 4;
+        const si = srcStart + ix * 4;
+        if (maskType === 1 /* BINARY */ || alpha === 255) {
+          dstData[di] = srcData[si];
+          dstData[di + 1] = srcData[si + 1];
+          dstData[di + 2] = srcData[si + 2];
+          dstData[di + 3] = srcData[si + 3];
+        } else {
+          const a = alpha / 255;
+          const invA = 1 - a;
+          dstData[di] = srcData[si] * a + dstData[di] * invA;
+          dstData[di + 1] = srcData[si + 1] * a + dstData[di + 1] * invA;
+          dstData[di + 2] = srcData[si + 2] * a + dstData[di + 2] * invA;
+          dstData[di + 3] = srcData[si + 3] * a + dstData[di + 3] * invA;
+        }
+      }
+    } else {
+      const byteLen = rowLenPixels * 4;
+      const sub = srcData.subarray(srcStart, srcStart + byteLen);
+      dstData.set(sub, dstStart);
     }
-    indexedData[i] = id;
   }
-  const palette = Uint32Array.from(colorMap.keys());
-  return {
-    width: actualWidth,
-    height: actualHeight,
-    data: indexedData,
-    transparentPalletIndex,
-    palette
-  };
 }
 
+// src/IndexedImage/IndexedImage.ts
+var IndexedImage = class _IndexedImage {
+  /** The width of the image in pixels. */
+  width;
+  /** The height of the image in pixels. */
+  height;
+  /** Flat array of palette indices. Index = x + (y * width). */
+  data;
+  /** The palette of unique 32-bit colors (ABGR/RGBA packed) found in the image. */
+  palette;
+  /** The specific index in the palette reserved for fully transparent pixels. */
+  transparentPalletIndex;
+  /**
+   * @param width - Image width.
+   * @param height - Image height.
+   * @param data - The indexed pixel data.
+   * @param palette - The array of packed colors.
+   * @param transparentPalletIndex - The index representing alpha 0.
+   */
+  constructor(width, height, data, palette, transparentPalletIndex) {
+    this.width = width;
+    this.height = height;
+    this.data = data;
+    this.palette = palette;
+    this.transparentPalletIndex = transparentPalletIndex;
+  }
+  /**
+   * Creates an IndexedImage from standard browser ImageData.
+   * @param imageData - The source ImageData to convert.
+   * @returns A new IndexedImage instance.
+   */
+  static fromImageData(imageData) {
+    return _IndexedImage.fromRaw(imageData.data, imageData.width, imageData.height);
+  }
+  /**
+   * Creates an IndexedImage from a raw byte buffer and dimensions.
+   * Any pixel with an alpha channel of 0 is normalized to the transparent palette index.
+   * @param data - Raw RGBA byte data.
+   * @param width - Image width.
+   * @param height - Image height.
+   * @returns A new IndexedImage instance.
+   */
+  static fromRaw(data, width, height) {
+    const buffer = data.buffer;
+    const rawData = new Uint32Array(buffer);
+    const indexedData = new Int32Array(rawData.length);
+    const colorMap = /* @__PURE__ */ new Map();
+    const transparentColor = 0;
+    const transparentPalletIndex = 0;
+    colorMap.set(transparentColor, transparentPalletIndex);
+    for (let i = 0; i < rawData.length; i++) {
+      const pixel = rawData[i];
+      const alpha = pixel >>> 24 & 255;
+      const isTransparent = alpha === 0;
+      const colorKey = isTransparent ? transparentColor : pixel >>> 0;
+      let id = colorMap.get(colorKey);
+      if (id === void 0) {
+        id = colorMap.size;
+        colorMap.set(colorKey, id);
+      }
+      indexedData[i] = id;
+    }
+    const palette = Uint32Array.from(colorMap.keys());
+    return new _IndexedImage(
+      width,
+      height,
+      indexedData,
+      palette,
+      transparentPalletIndex
+    );
+  }
+  /**
+   * Retrieves the 32-bit packed color value at the given coordinates.
+   * @param x - X coordinate.
+   * @param y - Y coordinate.
+   * @returns The packed color from the palette.
+   */
+  getColorAt(x, y) {
+    const index = x + y * this.width;
+    const paletteIndex = this.data[index];
+    return this.palette[paletteIndex];
+  }
+};
+
 // src/IndexedImage/getIndexedImageColorCounts.ts
 function getIndexedImageColorCounts(indexedImage) {
   const data = indexedImage.data;
@@ -1721,13 +1825,26 @@ function resampleIndexedImage(source, factor) {
     source.height,
     factor
   );
-  return {
+  return new IndexedImage(
     width,
     height,
     data,
-    palette: source.palette,
-    transparentPalletIndex: source.transparentPalletIndex
-  };
+    source.palette,
+    source.transparentPalletIndex
+  );
+}
+
+// src/IndexedImage/indexedImageToImageData.ts
+function indexedImageToImageData(indexedImage) {
+  const { width, height, data, palette } = indexedImage;
+  const result = new ImageData(width, height);
+  const data32 = new Uint32Array(result.data.buffer);
+  for (let i = 0; i < data.length; i++) {
+    const paletteIndex = data[i];
+    const color = palette[paletteIndex];
+    data32[i] = color;
+  }
+  return result;
 }
 
 // src/Input/fileInputChangeToImageData.ts
@@ -2414,6 +2531,7 @@ export {
   FAST_BLEND_TO_INDEX,
   INDEX_TO_FAST_BLEND,
   INDEX_TO_PERFECT_BLEND,
+  IndexedImage,
   MaskType,
   PERFECT_BLENDER_REGISTRY,
   PERFECT_BLEND_MODES,
@@ -2468,6 +2586,7 @@ export {
   imageDataToImgBlob,
   imgBlobToImageData,
   indexedImageToAverageColor,
+  indexedImageToImageData,
   invertAlphaMask,
   invertBinaryMask,
   invertImageData,
@@ -2484,7 +2603,6 @@ export {
   linearDodgePerfect,
   linearLightFast,
   linearLightPerfect,
-  makeIndexedImage,
   makePixelCanvas,
   makeReusableCanvas,
   mergeMasks,
@@ -2525,6 +2643,7 @@ export {
   unpackRed,
   vividLightFast,
   vividLightPerfect,
+  writeImageData,
   writeImageDataPixels,
   writeImageDataToClipboard,
   writeImgBlobToClipboard