pixel-data-js 0.11.1 → 0.12.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pixel-data-js",
   "type": "module",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "packageManager": "pnpm@10.30.0",
   "description": "JS Pixel and ImageData operations",
   "author": {

package/src/ImageData/writeImageData.ts

@@ -0,0 +1,89 @@
+import { MaskType } from '../_types'
+
+/**
+ * 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
+ */
+export function writeImageData(
+  target: ImageData,
+  source: ImageData,
+  x: number,
+  y: number,
+  sx: number = 0,
+  sy: number = 0,
+  sw: number = source.width,
+  sh: number = source.height,
+  mask: Uint8Array | null = null,
+  maskType: MaskType = MaskType.BINARY,
+): void {
+  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 === MaskType.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)
+    }
+  }
+}

package/src/IndexedImage/IndexedImage.ts

@@ -1,83 +1,113 @@
+import type { Color32 } from '../_types'
+
 /**
- * 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.
+ * 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.
  */
-export type IndexedImage = {
+export class IndexedImage {
   /** The width of the image in pixels. */
-  width: number;
+  public readonly width: number
   /** The height of the image in pixels. */
-  height: number;
+  public readonly height: number
+  /** Flat array of palette indices. Index = x + (y * width). */
+  public readonly data: Int32Array
+  /** The palette of unique 32-bit colors (ABGR/RGBA packed) found in the image. */
+  public readonly palette: Uint32Array
+  /** The specific index in the palette reserved for fully transparent pixels. */
+  public 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,
+  ) {
+    this.width = width
+    this.height = height
+    this.data = data
+    this.palette = palette
+    this.transparentPalletIndex = transparentPalletIndex
+  }
+
   /**
-   * 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 {
+    return IndexedImage.fromRaw(imageData.data, imageData.width, imageData.height)
+  }
+
   /**
-   * 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.
- */
-export function makeIndexedImage(imageData: ImageData): IndexedImage;
-export function makeIndexedImage(
-  data: Uint8ClampedArray,
-  width: number,
-  height: number,
-): IndexedImage;
-export function makeIndexedImage(
-  imageOrData: ImageData | Uint8ClampedArray,
-  width?: number,
-  height?: number,
-): IndexedImage {
-  const isImageData = 'width' in imageOrData
-  const actualWidth = isImageData ? imageOrData.width : (width as number)
-  const actualHeight = isImageData ? imageOrData.height : (height as number)
-  const buffer = isImageData ? imageOrData.data.buffer : imageOrData.buffer
-
-  // Use a 32-bit view to read pixels as packed integers (unsigned)
-  const rawData = new Uint32Array(buffer)
-  const indexedData = new Int32Array(rawData.length)
-  const colorMap = new Map<number, number>()
-
-  const transparentColor = 0
-  const transparentPalletIndex = 0
+  static fromRaw(
+    data: Uint8ClampedArray,
+    width: number,
+    height: number,
+  ): IndexedImage {
+    const buffer = data.buffer
+    const rawData = new Uint32Array(buffer)
+    const indexedData = new Int32Array(rawData.length)
+    const colorMap = new Map<number, number>()
+    const transparentColor = 0
+    const transparentPalletIndex = 0
 
-  // Initialize palette with normalized transparent color
-  colorMap.set(transparentColor, transparentPalletIndex)
+    // Initialize palette with normalized transparent color
+    colorMap.set(transparentColor, transparentPalletIndex)
 
-  for (let i = 0; i < rawData.length; i++) {
-    const pixel = rawData[i]!
+    for (let i = 0; i < rawData.length; i++) {
+      const pixel = rawData[i] as number
+      const alpha = (pixel >>> 24) & 0xFF
+      const isTransparent = alpha === 0
+      const colorKey = isTransparent ? transparentColor : (pixel >>> 0)
 
-    // Check if the pixel is fully transparent (Alpha channel is highest byte)
-    const alpha = (pixel >>> 24) & 0xFF
-    const isTransparent = alpha === 0
-    const colorKey = isTransparent ? transparentColor : (pixel >>> 0)
+      let id = colorMap.get(colorKey)
 
-    let id = colorMap.get(colorKey)
+      if (id === undefined) {
+        id = colorMap.size
+        colorMap.set(colorKey, id)
+      }
 
-    if (id === undefined) {
-      id = colorMap.size
-      colorMap.set(colorKey, id)
+      indexedData[i] = id
     }
 
-    indexedData[i] = id
+    const palette = Uint32Array.from(colorMap.keys())
+
+    return new IndexedImage(
+      width,
+      height,
+      indexedData,
+      palette,
+      transparentPalletIndex,
+    )
   }
 
-  const palette = Uint32Array.from(colorMap.keys())
+  /**
+   * 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.
+   */
+  public getColorAt(x: number, y: number): Color32 {
+    const index = x + y * this.width
+    const paletteIndex = this.data[index]
 
-  return {
-    width: actualWidth,
-    height: actualHeight,
-    data: indexedData,
-    transparentPalletIndex,
-    palette,
+    return this.palette[paletteIndex] as Color32
   }
 }

package/src/IndexedImage/indexedImageToImageData.ts

@@ -0,0 +1,19 @@
+import type { IndexedImage } from './IndexedImage'
+
+/**
+ * Converts an IndexedImage back into standard ImageData.
+ */
+export function indexedImageToImageData(indexedImage: IndexedImage): ImageData {
+  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
+}

package/src/IndexedImage/resampleIndexedImage.ts

@@ -2,7 +2,7 @@
  * Resamples an IndexedImage by a specific factor using nearest neighbor
  * Factor > 1 upscales, Factor < 1 downscales.
  */
-import type { IndexedImage } from '../index'
+import { IndexedImage } from '../index'
 import { resample32 } from '../Internal/resample32'
 
 /**
@@ -21,11 +21,11 @@ export function resampleIndexedImage(
     factor,
   )
 
-  return {
+  return new IndexedImage(
     width,
     height,
     data,
-    palette: source.palette,
-    transparentPalletIndex: source.transparentPalletIndex,
-  }
+    source.palette,
+    source.transparentPalletIndex,
+  )
 }

package/src/Internal/resample32.ts

@@ -4,8 +4,14 @@ const resample32Scratch = {
   height: 0,
 }
 
+/**
+ *  @internal
+ */
 type Resample32Result = { data: Int32Array; width: number; height: number }
 
+/**
+ *  @internal
+ */
 export function resample32(
   srcData32: Uint32Array | Int32Array,
   srcW: number,

package/src/index.ts

@@ -33,11 +33,13 @@ export * from './ImageData/resampleImageData'
 export * from './ImageData/resizeImageData'
 export * from './ImageData/serialization'
 export * from './ImageData/writeImageDataPixels'
+export * from './ImageData/writeImageData'
 
 export * from './IndexedImage/IndexedImage'
 export * from './IndexedImage/getIndexedImageColorCounts'
 export * from './IndexedImage/indexedImageToAverageColor'
 export * from './IndexedImage/resampleIndexedImage'
+export * from './IndexedImage/indexedImageToImageData'
 
 export * from './Input/fileInputChangeToImageData'
 export * from './Input/fileToImageData'