pixel-data-js 0.27.0 → 0.28.0

package/src/ImageData/ImageDataLike.ts

@@ -1,4 +1,4 @@
-import type { ImageDataLike } from '../_types'
+import type { ImageDataLike } from './_ImageData-types'
 
 export function makeImageDataLike(width: number, height: number, data?: Buffer): ImageDataLike {
   const size = width * height * 4

package/src/ImageData/_ImageData-types.ts

@@ -0,0 +1,13 @@
+export interface ImageDataLike {
+  width: number
+  height: number
+  data: Uint8ClampedArray<ArrayBufferLike>
+}
+
+export type SerializedImageData = {
+  width: number
+  height: number
+  data: string
+}
+
+export type Base64EncodedUInt8Array = string & { readonly __brandBase64UInt8Array: unique symbol }

package/src/ImageData/copyImageData.ts

@@ -1,4 +1,4 @@
-import type { ImageDataLike } from '../_types'
+import type { ImageDataLike } from './_ImageData-types'
 
 export function copyImageData({ data, width, height }: ImageDataLike): ImageData {
   return new ImageData(data.slice(), width, height)

package/src/ImageData/extractImageDataBuffer.ts

@@ -1,5 +1,6 @@
-import type { ImageDataLike, Rect } from '../_types'
-import { makeClippedBlit, resolveBlitClipping } from '../Internal/resolveClipping'
+import type { Rect } from '../Rect/_rect-types'
+import { makeClippedBlit, resolveBlitClipping } from '../Rect/resolveClipping'
+import type { ImageDataLike } from './_ImageData-types'
 
 const SCRATCH_BLIT = makeClippedBlit()
 

package/src/ImageData/imageDataToUint32Array.ts

@@ -0,0 +1,18 @@
+import type { ImageDataLike } from './_ImageData-types'
+
+/**
+ * converts {@link ImageData} to a faster Uint32Array
+ */
+export function imageDataToUint32Array(imageData: ImageDataLike): Uint32Array {
+  return _macro_imageDataToUint32Array(imageData)
+}
+
+// @__INLINE_MACRO__
+export function _macro_imageDataToUint32Array(imageData: ImageDataLike): Uint32Array {
+  return new Uint32Array(
+    imageData.data.buffer,
+    imageData.data.byteOffset,
+    // Shift right by 2 is a fast bitwise division by 4.
+    imageData.data.byteLength >> 2,
+  )
+}

package/src/ImageData/resampleImageData.ts

@@ -2,7 +2,7 @@
  * Resamples ImageData by a specific factor.
  * Factor > 1 upscales, Factor < 1 downscales.
  */
-import { resample32 } from '../Internal/resample32'
+import { resampleUint32Array } from '../Algorithm/resampleUint32Array'
 
 /**
  * Resamples ImageData by a specific factor.
@@ -10,8 +10,8 @@ import { resample32 } from '../Internal/resample32'
  */
 export function resampleImageData(source: ImageData, factor: number): ImageData {
   const src32 = new Uint32Array(source.data.buffer)
-  const { data, width, height } = resample32(src32, source.width, source.height, factor)
+  const { data, w, h } = resampleUint32Array(src32, source.width, source.height, factor)
 
   const uint8ClampedArray = new Uint8ClampedArray(data.buffer) as Uint8ClampedArray<ArrayBuffer>
-  return new ImageData(uint8ClampedArray, width, height)
+  return new ImageData(uint8ClampedArray, w, h)
 }

package/src/ImageData/resizeImageData.ts

@@ -1,4 +1,4 @@
-import type { ImageDataLike } from '../_types'
+import type { ImageDataLike } from './_ImageData-types'
 
 /**
  * Non destructively resizes the {@link ImageData} buffer to new dimensions, optionally

package/src/ImageData/serialization.ts

@@ -1,4 +1,4 @@
-import type { Base64EncodedUInt8Array, ImageDataLike, SerializedImageData } from '../_types'
+import type { Base64EncodedUInt8Array, ImageDataLike, SerializedImageData } from './_ImageData-types'
 
 export function base64EncodeArrayBuffer(buffer: ArrayBufferLike): Base64EncodedUInt8Array {
   const uint8 = new Uint8Array(buffer)

package/src/ImageData/uInt32ArrayToImageData.ts

@@ -1,4 +1,4 @@
-import type { ImageDataLike } from '../_types'
+import type { ImageDataLike } from './_ImageData-types'
 
 export function uInt32ArrayToImageData(
   data: Uint32Array,

package/src/ImageData/writeImageData.ts

@@ -1,5 +1,5 @@
-import { MaskType } from '../_types'
-import { makeClippedBlit, resolveBlitClipping } from '../Internal/resolveClipping'
+import { MaskType } from '../Mask/_mask-types'
+import { makeClippedBlit, resolveBlitClipping } from '../Rect/resolveClipping'
 
 const SCRATCH_BLIT = makeClippedBlit()
 

package/src/ImageData/writeImageDataBuffer.ts

@@ -1,5 +1,5 @@
-import type { Rect } from '../_types'
-import { makeClippedBlit, resolveBlitClipping } from '../Internal/resolveClipping'
+import type { Rect } from '../Rect/_rect-types'
+import { makeClippedBlit, resolveBlitClipping } from '../Rect/resolveClipping'
 
 const SCRATCH_BLIT = makeClippedBlit()
 

package/src/IndexedImage/IndexedImage.ts

@@ -1,113 +1,71 @@
 import type { Color32 } from '../_types'
+import type { IndexedImage } from './_indexedImage-types'
 
-/**
- * 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 class IndexedImage {
-  /** The width of the image in pixels. */
-  public readonly width: number
-  /** The height of the image in pixels. */
-  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
-
-  /**
-   * @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: number,
-    height: number,
-    data: Int32Array,
-    palette: Uint32Array,
-    transparentPalletIndex: number,
-  ) {
-    this.width = width
-    this.height = height
-    this.data = data
-    this.palette = palette
-    this.transparentPalletIndex = transparentPalletIndex
+export function makeIndexedImage(
+  width: number,
+  height: number,
+  data: Uint32Array,
+  palette: Uint32Array,
+  transparentPalletIndex: number,
+): IndexedImage {
+  return {
+    w: width,
+    h: height,
+    data,
+    palette,
+    transparentPalletIndex,
   }
+}
 
-  /**
-   * Creates an IndexedImage from standard browser ImageData.
-   * @param imageData - The source ImageData to convert.
-   * @returns A new IndexedImage instance.
-   */
-  static fromImageData(imageData: ImageData): IndexedImage {
-    return IndexedImage.fromRaw(imageData.data, imageData.width, imageData.height)
-  }
+export function makeIndexedImageFromImageDataRaw(
+  data: Uint8ClampedArray,
+  width: number,
+  height: number,
+): IndexedImage {
+  const buffer = data.buffer
+  const rawData = new Uint32Array(buffer)
+  const indexedData = new Uint32Array(rawData.length)
+  const colorMap = new Map<number, number>()
+  const transparentColor = 0
+  const transparentPalletIndex = 0
 
-  /**
-   * 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: 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] as number
+    const alpha = (pixel >>> 24) & 0xFF
+    const isTransparent = alpha === 0
+    const colorKey = isTransparent ? transparentColor : (pixel >>> 0)
 
-    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)
+    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())
 
-    const palette = Uint32Array.from(colorMap.keys())
+  return makeIndexedImage(
+    width,
+    height,
+    indexedData,
+    palette,
+    transparentPalletIndex,
+  )
+}
 
-    return new IndexedImage(
-      width,
-      height,
-      indexedData,
-      palette,
-      transparentPalletIndex,
-    )
-  }
+export function makeIndexedImageFromImageData(imageData: ImageData): IndexedImage {
+  return makeIndexedImageFromImageDataRaw(imageData.data, imageData.width, imageData.height)
+}
 
-  /**
-   * 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]
+export function getIndexedImageColor(target: IndexedImage, x: number, y: number): Color32 {
+  const index = x + y * target.w
+  const paletteIndex = target.data[index]
 
-    return this.palette[paletteIndex] as Color32
-  }
+  return target.palette[paletteIndex] as Color32
 }

package/src/IndexedImage/_indexedImage-types.ts

@@ -0,0 +1,18 @@
+/**
+ * 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 interface IndexedImage {
+  /** The width of the image in pixels. */
+  readonly w: number
+  /** The height of the image in pixels. */
+  readonly h: number
+  /** Flat array of palette indices. Index = x + (y * width). */
+  readonly data: Uint32Array
+  /** 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
+}

package/src/IndexedImage/getIndexedImageColorCounts.ts

@@ -1,4 +1,4 @@
-import type { IndexedImage } from './IndexedImage.ts'
+import type { IndexedImage } from './_indexedImage-types'
 
 /**
  * Calculates the frequency of each palette index based on the image data.
@@ -6,10 +6,10 @@ import type { IndexedImage } from './IndexedImage.ts'
  * @param indexedImage - The source image containing data and palette definitions.
  * @returns A typed array where each entry represents the total count of that palette index.
  */
-export function getIndexedImageColorCounts(indexedImage: IndexedImage): Int32Array {
+export function getIndexedImageColorCounts(indexedImage: IndexedImage): Uint32Array {
   const data = indexedImage.data
   const palette = indexedImage.palette
-  const frequencies = new Int32Array(palette.length)
+  const frequencies = new Uint32Array(palette.length)
 
   for (let i = 0; i < data.length; i++) {
     const colorIndex = data[i]!

package/src/IndexedImage/indexedImageToAverageColor.ts

@@ -1,6 +1,6 @@
 import type { Color32 } from '../_types'
 import { packColor } from '../color'
-import type { IndexedImage } from './IndexedImage'
+import type { IndexedImage } from './_indexedImage-types'
 
 /**
  * Calculates the area-weighted average color of an IndexedImage.

package/src/IndexedImage/indexedImageToImageData.ts

@@ -1,18 +1,16 @@
-import type { IndexedImage } from './IndexedImage'
+import type { IndexedImage } from './_indexedImage-types'
 
 /**
  * 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 { w, h, data, palette } = indexedImage
+  const result = new ImageData(w, h)
   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
+    data32[i] = palette[paletteIndex]
   }
 
   return result

package/src/IndexedImage/resampleIndexedImage.ts

@@ -2,8 +2,8 @@
  * Resamples an IndexedImage by a specific factor using nearest neighbor
  * Factor > 1 upscales, Factor < 1 downscales.
  */
-import { IndexedImage } from '../index'
-import { resample32 } from '../Internal/resample32'
+import { resampleUint32Array } from '../Algorithm/resampleUint32Array'
+import { type IndexedImage } from '../index'
 
 /**
  * Resamples an IndexedImage by a specific factor using nearest neighbor
@@ -14,18 +14,10 @@ export function resampleIndexedImage(
   factor: number,
 ): IndexedImage {
 
-  const { data, width, height } = resample32(
-    source.data,
-    source.width,
-    source.height,
-    factor,
-  )
+  const output = {
+    palette: source.palette,
+    transparentPalletIndex: source.transparentPalletIndex,
+  } as IndexedImage
 
-  return new IndexedImage(
-    width,
-    height,
-    data,
-    source.palette,
-    source.transparentPalletIndex,
-  )
+  return resampleUint32Array(source.data, source.w, source.h, factor, output) as IndexedImage
 }

package/src/Input/fileToImageData.ts

@@ -1,4 +1,4 @@
-import { OFFSCREEN_CANVAS_CTX_FAILED } from '../../support/error-strings'
+import { OFFSCREEN_CANVAS_CTX_FAILED } from '../Internal/_errors'
 
 /**
  * Thrown when the user provides a file that isn't an image.

package/src/Internal/_errors.ts

@@ -0,0 +1,2 @@
+export const OFFSCREEN_CANVAS_CTX_FAILED = 'Failed to create OffscreenCanvas context'
+export const CANVAS_CTX_FAILED = 'Failed to create Canvas context'

package/src/Internal/macros.ts

@@ -0,0 +1,14 @@
+// @__INLINE_MACRO__
+export const _macro_halfAndFloor = (value: number) => value >> 1
+
+// @__INLINE_MACRO__
+export const _macro_paintRectCenterOffset = (size: number) => -((size - 1) >> 1)
+
+// @__INLINE_MACRO__
+export const _macro_paintCircleCenterOffset = (radius: number) => -Math.ceil(radius - 0.5)
+
+// for reference only
+// const _inline_multiplyAlpha = (a: number, b: number) => {
+//   const t = a * b + 128
+//   return (t + (t >> 8)) >> 8
+// }

package/src/Mask/AlphaMask.ts

@@ -1,4 +1,4 @@
-import { type AlphaMask, MaskType } from '../_types'
+import { type AlphaMask, MaskType } from './_mask-types'
 
 /**
  * Creates an Alpha Mask

package/src/Mask/BinaryMask/makeBinaryMaskFromAlphaMask.ts

@@ -0,0 +1,23 @@
+import { type AlphaMask, type BinaryMask, MaskType, type MutableBinaryMask } from '../_mask-types'
+
+export function makeBinaryMaskFromAlphaMask(mask: AlphaMask, threshold: number, out?: MutableBinaryMask): BinaryMask {
+  const w = mask.w
+  const h = mask.h
+  const alphaData = mask.data
+  const area = w * h
+
+  const binaryData = new Uint8Array(area)
+
+  for (let i = 0; i < area; i++) {
+    if (alphaData[i] >= threshold) {
+      binaryData[i] = 1
+    }
+  }
+
+  out = out ?? { type: MaskType.BINARY } as MutableBinaryMask
+  out.data = binaryData
+  out.w = w
+  out.h = h
+
+  return out
+}

package/src/Mask/BinaryMask/makeBinaryMaskOutline.ts

@@ -0,0 +1,88 @@
+import { type BinaryMask, MaskType } from '../_mask-types'
+
+export function makeBinaryMaskOutline(
+  mask: BinaryMask,
+  scale = 1,
+): BinaryMask {
+  const w = mask.w
+  const h = mask.h
+  const maskData = mask.data
+
+  const size = w * scale + 2
+  const outData = new Uint8Array(size * size)
+
+  for (let iy = 0; iy < h; iy++) {
+    for (let ix = 0; ix < w; ix++) {
+      const i = iy * w + ix
+      if (maskData[i] === 0) continue
+
+      const lx = ix * scale + 1
+      const ly = iy * scale + 1
+
+      const top = iy === 0 || maskData[i - w] === 0
+      const bottom = iy === h - 1 || maskData[i + w] === 0
+      const left = ix === 0 || maskData[i - 1] === 0
+      const right = ix === w - 1 || maskData[i + 1] === 0
+
+      const topLeft = iy === 0 || ix === 0 || maskData[i - w - 1] === 0
+      const topRight = iy === 0 || ix === w - 1 || maskData[i - w + 1] === 0
+      const bottomLeft = iy === h - 1 || ix === 0 || maskData[i + w - 1] === 0
+      const bottomRight = iy === h - 1 || ix === w - 1 || maskData[i + w + 1] === 0
+
+      if (top) {
+        for (let sx = 0; sx < scale; sx++) {
+          const outIdx = (ly - 1) * size + (lx + sx)
+          outData[outIdx] = 1
+        }
+      }
+
+      if (bottom) {
+        for (let sx = 0; sx < scale; sx++) {
+          const outIdx = (ly + scale) * size + (lx + sx)
+          outData[outIdx] = 1
+        }
+      }
+
+      if (left) {
+        for (let sy = 0; sy < scale; sy++) {
+          const outIdx = (ly + sy) * size + (lx - 1)
+          outData[outIdx] = 1
+        }
+      }
+
+      if (right) {
+        for (let sy = 0; sy < scale; sy++) {
+          const outIdx = (ly + sy) * size + (lx + scale)
+          outData[outIdx] = 1
+        }
+      }
+
+      if (topLeft) {
+        const outIdx = (ly - 1) * size + (lx - 1)
+        outData[outIdx] = 1
+      }
+
+      if (topRight) {
+        const outIdx = (ly - 1) * size + (lx + scale)
+        outData[outIdx] = 1
+      }
+
+      if (bottomLeft) {
+        const outIdx = (ly + scale) * size + (lx - 1)
+        outData[outIdx] = 1
+      }
+
+      if (bottomRight) {
+        const outIdx = (ly + scale) * size + (lx + scale)
+        outData[outIdx] = 1
+      }
+    }
+  }
+
+  return {
+    type: MaskType.BINARY,
+    w: size,
+    h: size,
+    data: outData,
+  }
+}

package/src/Mask/BinaryMask/makeCircleBinaryMaskOutline.ts

@@ -0,0 +1,104 @@
+import { type BinaryMask, MaskType } from '../_mask-types'
+
+export function makeCircleBinaryMaskOutline(size: number, scale: number): BinaryMask {
+  const outSize = size * scale + 2
+  const outArea = outSize * outSize
+  const data = new Uint8Array(outArea)
+
+  const radius = size / 2
+  const r2 = radius * radius
+
+  let prevMinX = -1
+  let prevMaxX = -1
+
+  let currMinX = -1
+  let currMaxX = -1
+
+  const initialDy = 0 - radius + 0.5
+  const initialDy2 = initialDy * initialDy
+
+  if (initialDy2 <= r2) {
+    const dx = Math.sqrt(r2 - initialDy2)
+    currMinX = Math.ceil(radius - 0.5 - dx)
+    currMaxX = Math.floor(radius - 0.5 + dx)
+  }
+
+  for (let iy = 0; iy < size; iy++) {
+    let nextMinX = -1
+    let nextMaxX = -1
+
+    if (iy + 1 < size) {
+      const ny = (iy + 1) - radius + 0.5
+      const ny2 = ny * ny
+
+      if (ny2 <= r2) {
+        const dx = Math.sqrt(r2 - ny2)
+        nextMinX = Math.ceil(radius - 0.5 - dx)
+        nextMaxX = Math.floor(radius - 0.5 + dx)
+      }
+    }
+
+    if (currMinX !== -1) {
+      for (let ix = currMinX; ix <= currMaxX; ix++) {
+        // Offset by 1 to leave room for the top/left outline edges
+        const sx = ix * scale + 1
+        const sy = iy * scale + 1
+
+        const isTop = prevMinX === -1 || ix < prevMinX || ix > prevMaxX
+        const isBottom = nextMinX === -1 || ix < nextMinX || ix > nextMaxX
+        const isLeft = ix === currMinX
+        const isRight = ix === currMaxX
+
+        if (isTop) {
+          const leftOut = prevMinX === -1 || (ix - 1) < prevMinX || (ix - 1) > prevMaxX
+          const rightOut = prevMinX === -1 || (ix + 1) < prevMinX || (ix + 1) > prevMaxX
+          const startX = leftOut ? sx - 1 : sx
+          const endX = rightOut ? sx + scale : sx + scale - 1
+
+          for (let x = startX; x <= endX; x++) {
+            const index = (sy - 1) * outSize + x
+            data[index] = 1
+          }
+        }
+
+        if (isBottom) {
+          const leftOut = nextMinX === -1 || (ix - 1) < nextMinX || (ix - 1) > nextMaxX
+          const rightOut = nextMinX === -1 || (ix + 1) < nextMinX || (ix + 1) > nextMaxX
+          const startX = leftOut ? sx - 1 : sx
+          const endX = rightOut ? sx + scale : sx + scale - 1
+
+          for (let x = startX; x <= endX; x++) {
+            const index = (sy + scale) * outSize + x
+            data[index] = 1
+          }
+        }
+
+        if (isLeft) {
+          for (let y = sy; y < sy + scale; y++) {
+            const index = y * outSize + (sx - 1)
+            data[index] = 1
+          }
+        }
+
+        if (isRight) {
+          for (let y = sy; y < sy + scale; y++) {
+            const index = y * outSize + (sx + scale)
+            data[index] = 1
+          }
+        }
+      }
+    }
+
+    prevMinX = currMinX
+    prevMaxX = currMaxX
+    currMinX = nextMinX
+    currMaxX = nextMaxX
+  }
+
+  return {
+    type: MaskType.BINARY,
+    w: outSize,
+    h: outSize,
+    data,
+  }
+}