pixel-data-js 0.1.0 → 0.3.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pixel-data-js",
   "type": "module",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "packageManager": "pnpm@10.30.0",
   "description": "JS Pixel and ImageData operations",
   "author": {
@@ -53,14 +53,13 @@
     "@stryker-mutator/typescript-checker": "^9.5.1",
     "@stryker-mutator/vitest-runner": "^9.5.1",
     "@types/node": "^25.2.3",
-    "@vitest/coverage-v8": "^4.0.18",
+    "@vitest/coverage-v8": "3.2.4",
     "esbuild": "^0.27.3",
-    "happy-dom": "^20.6.1",
     "tsup": "^8.5.1",
     "tsx": "^4.21.0",
     "typedoc": "^0.28.17",
     "typescript": "^5.9.3",
-    "vitest": "4.0.18"
+    "vitest": "3.2.4"
   },
   "repository": {
     "type": "git",

package/src/ImageData/copyImageData.ts

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

package/src/ImageData/extractImageData.ts

@@ -0,0 +1,54 @@
+import type { ImageDataLike, Rect } from '../_types'
+
+export function extractImageData(
+  imageData: ImageDataLike,
+  rect: Rect,
+): Uint8ClampedArray
+export function extractImageData(
+  imageData: ImageDataLike,
+  x: number,
+  y: number,
+  w: number,
+  h: number,
+): Uint8ClampedArray
+export function extractImageData(
+  imageData: ImageDataLike,
+  _x: Rect | number,
+  _y?: number,
+  _w?: number,
+  _h?: number,
+): Uint8ClampedArray {
+  const { x, y, w, h } = typeof _x === 'object'
+    ? _x
+    : { x: _x, y: _y!, w: _w!, h: _h! }
+
+  const { width: srcW, height: srcH, data: src } = imageData
+  // Safety check for invalid dimensions
+  if (w <= 0 || h <= 0) return new Uint8ClampedArray(0)
+  const out = new Uint8ClampedArray(w * h * 4)
+
+  const x0 = Math.max(0, x)
+  const y0 = Math.max(0, y)
+  const x1 = Math.min(srcW, x + w)
+  const y1 = Math.min(srcH, y + h)
+
+  // If no intersection, return the empty
+  if (x1 <= x0 || y1 <= y0) return out
+
+  for (let row = 0; row < (y1 - y0); row++) {
+    // Where to read from the source canvas
+    const srcRow = y0 + row
+    const srcStart = (srcRow * srcW + x0) * 4
+    const rowLen = (x1 - x0) * 4
+
+    // Where to write into the 'out' patch
+    const dstRow = (y0 - y) + row
+    const dstCol = (x0 - x)
+    const dstStart = (dstRow * w + dstCol) * 4
+
+    // Perform the high-speed bulk copy
+    out.set(src.subarray(srcStart, srcStart + rowLen), dstStart)
+  }
+
+  return out
+}

package/src/ImageData/serialization.ts

@@ -5,7 +5,7 @@ export function base64EncodeArrayBuffer(buffer: ArrayBufferLike): Base64EncodedU
   return btoa(binary) as Base64EncodedUInt8Array
 }
 
-export function base64DecodeArrayBuffer(encoded: Base64EncodedUInt8Array): Uint8ClampedArray {
+export function base64DecodeArrayBuffer(encoded: Base64EncodedUInt8Array): Uint8ClampedArray<ArrayBuffer> {
   const binary = atob(encoded)
   const bytes = new Uint8ClampedArray(binary.length)
   for (let i = 0; i < binary.length; i++) {

package/src/ImageData/writeImageData.ts

@@ -0,0 +1,54 @@
+import type { Rect } from '../_types'
+
+export function writeImageData(
+  imageData: ImageData,
+  data: Uint8ClampedArray,
+  rect: Rect,
+): void
+export function writeImageData(
+  imageData: ImageData,
+  data: Uint8ClampedArray,
+  x: number,
+  y: number,
+  w: number,
+  h: number,
+): void
+export function writeImageData(
+  imageData: ImageData,
+  data: Uint8ClampedArray,
+  _x: Rect | number,
+  _y?: number,
+  _w?: number,
+  _h?: number,
+): void {
+  const { x, y, w, h } = typeof _x === 'object'
+    ? _x
+    : { x: _x, y: _y!, w: _w!, h: _h! }
+
+  const { width: dstW, height: dstH, data: dst } = imageData
+
+  // 1. Calculate the intersection of the patch and the canvas
+  const x0 = Math.max(0, x)
+  const y0 = Math.max(0, y)
+  const x1 = Math.min(dstW, x + w)
+  const y1 = Math.min(dstH, y + h)
+
+  // If the intersection is empty, do nothing
+  if (x1 <= x0 || y1 <= y0) return
+
+  const rowLen = (x1 - x0) * 4
+  const srcCol = x0 - x
+  const srcYOffset = y0 - y
+  const actualH = y1 - y0
+
+  for (let row = 0; row < actualH; row++) {
+    // Target index
+    const dstStart = ((y0 + row) * dstW + x0) * 4
+
+    // Source data index (must account for the offset if the rect was partially OOB)
+    const srcRow = srcYOffset + row
+    const o = (srcRow * w + srcCol) * 4
+
+    dst.set(data.subarray(o, o + rowLen), dstStart)
+  }
+}

package/src/Mask/copyMask.ts

@@ -0,0 +1,10 @@
+import type { AnyMask } from '../index'
+
+/**
+ * Creates a new copy of a mask.
+ * Uses the underlying buffer's slice method for high-performance memory copying.
+ */
+export function copyMask<T extends AnyMask>(src: T): T {
+  // Uint8Array.slice() is highly optimized at the engine level
+  return src.slice() as T
+}

package/src/Mask/invertMask.ts

@@ -0,0 +1,25 @@
+import type { AlphaMask, BinaryMask } from '../index'
+
+/**
+ * Inverts a BinaryMask in-place.
+ */
+export function invertBinaryMask(dst: BinaryMask): void {
+  const len = dst.length
+
+  for (let i = 0; i < len; i++) {
+    dst[i] = dst[i] === 0
+      ? 1
+      : 0
+  }
+}
+
+/**
+ * Inverts an AlphaMask in-place.
+ */
+export function invertAlphaMask(dst: AlphaMask): void {
+  const len = dst.length
+
+  for (let i = 0; i < len; i++) {
+    dst[i] = 255 - dst[i]
+  }
+}

package/src/Mask/mergeMasks.ts

@@ -0,0 +1,105 @@
+import {
+  type AnyMask,
+  type AlphaMask,
+  type ApplyMaskOptions,
+  MaskType,
+} from '../_types'
+
+/**
+ * Merges a source mask into a destination AlphaMask.
+ */
+export function mergeMasks(
+  dst: AlphaMask,
+  dstWidth: number,
+  src: AnyMask,
+  opts: ApplyMaskOptions,
+): void {
+  const {
+    x: targetX = 0,
+    y: targetY = 0,
+    w: width = 0,
+    h: height = 0,
+    alpha: globalAlpha = 255,
+    maskType = MaskType.ALPHA,
+    mw,
+    mx = 0,
+    my = 0,
+    invertMask = false,
+  } = opts
+
+  if (width <= 0 || height <= 0 || globalAlpha === 0) {
+    return
+  }
+
+  const sPitch = mw ?? width
+  const isAlpha = maskType === MaskType.ALPHA
+
+  for (let iy = 0; iy < height; iy++) {
+    const dy = targetY + iy
+    const sy = my + iy
+
+    if (dy < 0 || sy < 0) {
+      continue
+    }
+
+    for (let ix = 0; ix < width; ix++) {
+      const dx = targetX + ix
+      const sx = mx + ix
+
+      if (dx < 0 || dx >= dstWidth || sx < 0 || sx >= sPitch) {
+        continue
+      }
+
+      const dIdx = dy * dstWidth + dx
+      const sIdx = sy * sPitch + sx
+      const mVal = src[sIdx]
+      let weight = globalAlpha
+
+      if (isAlpha) {
+        const effectiveM = invertMask
+          ? 255 - mVal
+          : mVal
+
+        if (effectiveM === 0) {
+          dst[dIdx] = 0
+          continue
+        }
+
+        weight = globalAlpha === 255
+          ? effectiveM
+          : (effectiveM * globalAlpha + 128) >> 8
+      } else {
+        // Strict Binary 1/0 Logic
+        const isHit = invertMask
+          ? mVal === 0
+          : mVal === 1
+
+        if (!isHit) {
+          dst[dIdx] = 0
+          continue
+        }
+
+        // If binary hit, weight is just the global alpha
+        weight = globalAlpha
+      }
+
+      if (weight === 0) {
+        dst[dIdx] = 0
+        continue
+      }
+
+      const da = dst[dIdx]
+
+      if (da === 0) {
+        // Already transparent
+      } else if (weight === 255) {
+        // Identity: keep da
+      } else if (da === 255) {
+        // Identity: result is weight
+        dst[dIdx] = weight
+      } else {
+        dst[dIdx] = (da * weight + 128) >> 8
+      }
+    }
+  }
+}

package/src/PixelData/applyMaskToPixelData.ts

@@ -0,0 +1,129 @@
+import { type AnyMask, type ApplyMaskOptions, MaskType } from '../_types'
+import type { PixelData } from '../PixelData'
+
+/**
+ * Directly applies a mask to a region of PixelData,
+ * modifying the destination's alpha channel in-place.
+ */
+export function applyMaskToPixelData(
+  dst: PixelData,
+  mask: AnyMask,
+  opts: ApplyMaskOptions,
+): void {
+  const {
+    x: targetX = 0,
+    y: targetY = 0,
+    w: width = dst.width,
+    h: height = dst.height,
+    alpha: globalAlpha = 255,
+    maskType = MaskType.ALPHA,
+    mw,
+    mx = 0,
+    my = 0,
+    invertMask = false,
+  } = opts
+
+  let x = targetX
+  let y = targetY
+  let w = width
+  let h = height
+
+  // Clipping Logic
+  if (x < 0) {
+    w += x
+    x = 0
+  }
+
+  if (y < 0) {
+    h += y
+    y = 0
+  }
+
+  const actualW = Math.min(w, dst.width - x)
+  const actualH = Math.min(h, dst.height - y)
+
+  if (actualW <= 0 || actualH <= 0 || globalAlpha === 0) {
+    return
+  }
+
+  const dst32 = dst.data32
+  const dw = dst.width
+  const mPitch = mw ?? width
+  const isAlpha = maskType === MaskType.ALPHA
+  const dx = x - targetX
+  const dy = y - targetY
+
+  let dIdx = y * dw + x
+  let mIdx = (my + dy) * mPitch + (mx + dx)
+
+  const dStride = dw - actualW
+  const mStride = mPitch - actualW
+
+  for (let iy = 0; iy < actualH; iy++) {
+    for (let ix = 0; ix < actualW; ix++) {
+      const mVal = mask[mIdx]
+      let weight = globalAlpha
+
+      if (isAlpha) {
+        const effectiveM = invertMask
+          ? 255 - mVal
+          : mVal
+
+        // Short-circuit: if source is 0, destination alpha becomes 0
+        if (effectiveM === 0) {
+          dst32[dIdx] = (dst32[dIdx] & 0x00ffffff) >>> 0
+          dIdx++
+          mIdx++
+          continue
+        }
+
+        weight = globalAlpha === 255
+          ? effectiveM
+          : (effectiveM * globalAlpha + 128) >> 8
+      } else {
+        // Strict Binary 1/0 Logic
+        const isHit = invertMask
+          ? mVal === 0
+          : mVal === 1
+
+        if (!isHit) {
+          dst32[dIdx] = (dst32[dIdx] & 0x00ffffff) >>> 0
+          dIdx++
+          mIdx++
+          continue
+        }
+
+        weight = globalAlpha
+      }
+
+      // If calculated weight is 0, clear alpha
+      if (weight === 0) {
+        dst32[dIdx] = (dst32[dIdx] & 0x00ffffff) >>> 0
+      } else {
+        const d = dst32[dIdx]
+        const da = (d >>> 24)
+
+        let finalAlpha = da
+
+        if (da === 0) {
+          // Already transparent
+        } else if (weight === 255) {
+          // Identity: keep original da
+        } else if (da === 255) {
+          // Identity: result is just the weight
+          finalAlpha = weight
+        } else {
+          finalAlpha = (da * weight + 128) >> 8
+        }
+
+        dst32[dIdx] = ((d & 0x00ffffff) | (finalAlpha << 24)) >>> 0
+      }
+
+      dIdx++
+      mIdx++
+    }
+
+    dIdx += dStride
+    mIdx += mStride
+  }
+}

package/src/PixelData/blendColorPixelData.ts

@@ -0,0 +1,157 @@
+import { type Color32, type ColorBlendOptions, MaskType } from '../_types'
+import { sourceOverColor32 } from '../blend-modes'
+import type { PixelData } from '../PixelData'
+
+/**
+ * Fills a rectangle in the destination PixelData with a single color,
+ * supporting blend modes, global alpha, and masking.
+ */
+export function blendColorPixelData(
+  dst: PixelData,
+  color: Color32,
+  opts: ColorBlendOptions,
+): void {
+  const {
+    x: targetX = 0,
+    y: targetY = 0,
+    w: width = dst.width,
+    h: height = dst.height,
+    alpha: globalAlpha = 255,
+    blendFn = sourceOverColor32,
+    mask,
+    maskType = MaskType.ALPHA,
+    mw,
+    mx = 0,
+    my = 0,
+    invertMask = false,
+  } = opts
+
+  if (globalAlpha === 0) return
+
+  let x = targetX
+  let y = targetY
+  let w = width
+  let h = height
+
+  // 1. Destination Clipping
+  if (x < 0) {
+    w += x
+    x = 0
+  }
+  if (y < 0) {
+    h += y
+    y = 0
+  }
+
+  const actualW = Math.min(w, dst.width - x)
+  const actualH = Math.min(h, dst.height - y)
+
+  if (actualW <= 0 || actualH <= 0) return
+
+  const dst32 = dst.data32
+  const dw = dst.width
+  const mPitch = mw ?? width
+  const isAlphaMask = maskType === MaskType.ALPHA
+
+  const dx = x - targetX
+  const dy = y - targetY
+
+  let dIdx = y * dw + x
+  let mIdx = (my + dy) * mPitch + (mx + dx)
+
+  const dStride = dw - actualW
+  const mStride = mPitch - actualW
+
+  // Pre-calculate the source color with global alpha
+  const baseSrcColor = color
+  const baseSrcAlpha = (baseSrcColor >>> 24)
+
+  for (let iy = 0; iy < actualH; iy++) {
+    for (let ix = 0; ix < actualW; ix++) {
+
+      // Early exit if source pixel is already transparent
+      if (baseSrcAlpha === 0) {
+        dIdx++
+        mIdx++
+        continue
+      }
+
+      let weight = globalAlpha
+
+      if (mask) {
+        const mVal = mask[mIdx]
+
+        if (isAlphaMask) {
+        const effectiveM = invertMask
+          ? 255 - mVal
+          : mVal
+
+        // If mask is transparent, skip
+        if (effectiveM === 0) {
+          dIdx++
+          mIdx++
+          continue
+        }
+
+          // globalAlpha is not a factor
+          if (globalAlpha === 255) {
+            weight = effectiveM
+            // mask is not a factor
+          } else if (effectiveM === 255) {
+            weight = globalAlpha
+          } else {
+            // use rounding-corrected multiplication
+            weight = (effectiveM * globalAlpha + 128) >> 8
+          }
+        } else {
+          const isHit = invertMask
+            ? mVal === 0
+            : mVal === 1
+
+          if (!isHit) {
+            dIdx++
+            mIdx++
+            continue
+          }
+
+          weight = globalAlpha
+        }
+
+        // Final safety check for weight (can be 0 if globalAlpha or alphaMask rounds down)
+        if (weight === 0) {
+          dIdx++
+          mIdx++
+          continue
+        }
+      }
+
+      // Apply Weight to Source Alpha
+      let currentSrcAlpha = baseSrcAlpha
+      let currentSrcColor = baseSrcColor
+
+      if (weight < 255) {
+        if (baseSrcAlpha === 255) {
+          currentSrcAlpha = weight
+        } else {
+          currentSrcAlpha = (baseSrcAlpha * weight + 128) >> 8
+        }
+
+        if (currentSrcAlpha === 0) {
+          dIdx++
+          mIdx++
+          continue
+        }
+
+        currentSrcColor = ((baseSrcColor & 0x00ffffff) | (currentSrcAlpha << 24)) >>> 0 as Color32
+      }
+
+      dst32[dIdx] = blendFn(currentSrcColor, dst32[dIdx] as Color32)
+
+      dIdx++
+      mIdx++
+    }
+
+    dIdx += dStride
+    mIdx += mStride
+  }
+}