pixel-data-js 0.18.0 → 0.19.1

package/src/ImageData/extractImageDataBuffer.ts

@@ -1,4 +1,7 @@
 import type { ImageDataLike, Rect } from '../_types'
+import { makeClippedBlit, resolveBlitClipping } from '../Internal/resolveClipping'
+
+const SCRATCH_BLIT = makeClippedBlit()
 
 /**
  * Extracts a specific rectangular region of pixels from a larger {@link ImageDataLike}
@@ -45,24 +48,28 @@ export function extractImageDataBuffer(
   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)
+  const clip = resolveBlitClipping(
+    0,
+    0,
+    x,
+    y,
+    w,
+    h,
+    w,
+    h,
+    srcW,
+    srcH,
+    SCRATCH_BLIT,
+  )
 
-  // If no intersection, return the empty
-  if (x1 <= x0 || y1 <= y0) return out
+  if (!clip.inBounds) 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
+  const { x: dstX, y: dstY, sx: srcX, sy: srcY, w: copyW, h: copyH } = clip
+  const rowLen = copyW * 4
 
-    // Where to write into the 'out' patch
-    const dstRow = (y0 - y) + row
-    const dstCol = (x0 - x)
-    const dstStart = (dstRow * w + dstCol) * 4
+  for (let row = 0; row < copyH; row++) {
+    const srcStart = ((srcY + row) * srcW + srcX) * 4
+    const dstStart = ((dstY + row) * w + dstX) * 4
 
     // Perform the high-speed bulk copy
     out.set(src.subarray(srcStart, srcStart + rowLen), dstStart)

package/src/ImageData/serialization.ts

@@ -1,11 +1,11 @@
 import type { Base64EncodedUInt8Array, ImageDataLike, SerializedImageData } from '../_types'
 
 export function base64EncodeArrayBuffer(buffer: ArrayBufferLike): Base64EncodedUInt8Array {
-  const uint8 = new Uint8Array(buffer);
-  const decoder = new TextDecoder('latin1');
-  const binary = decoder.decode(uint8);
+  const uint8 = new Uint8Array(buffer)
+  const decoder = new TextDecoder('latin1')
+  const binary = decoder.decode(uint8)
 
-  return btoa(binary) as Base64EncodedUInt8Array;
+  return btoa(binary) as Base64EncodedUInt8Array
 }
 
 export function base64DecodeArrayBuffer(encoded: Base64EncodedUInt8Array): Uint8ClampedArray<ArrayBuffer> {

package/src/ImageData/uInt32ArrayToImageData.ts

@@ -0,0 +1,29 @@
+import type { ImageDataLike } from '../_types'
+
+export function uInt32ArrayToImageData(
+  data: Uint32Array,
+  width: number,
+  height: number,
+): ImageData {
+  const buffer = data.buffer as ArrayBuffer
+  const byteOffset = data.byteOffset
+  const byteLength = data.byteLength
+  const clampedArray = new Uint8ClampedArray(buffer, byteOffset, byteLength)
+  return new ImageData(clampedArray, width, height)
+}
+
+export function uInt32ArrayToImageDataLike(
+  data: Uint32Array,
+  width: number,
+  height: number,
+): ImageDataLike {
+  const buffer = data.buffer
+  const byteOffset = data.byteOffset
+  const byteLength = data.byteLength
+  const clampedArray = new Uint8ClampedArray(buffer, byteOffset, byteLength)
+  return {
+    width,
+    height,
+    data: clampedArray,
+  }
+}

package/src/ImageData/writeImageData.ts

@@ -1,4 +1,7 @@
 import { MaskType } from '../_types'
+import { makeClippedBlit, resolveBlitClipping } from '../Internal/resolveClipping'
+
+const SCRATCH_BLIT = makeClippedBlit()
 
 /**
  * Writes image data from a source to a target with support for clipping and alpha masking.
@@ -32,30 +35,35 @@ export function writeImageData(
   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)
+  const clip = resolveBlitClipping(
+    x, y, sx, sy, sw, sh,
+    dstW, dstH, srcW, source.height,
+    SCRATCH_BLIT,
+  )
 
-  if (x1 <= x0 || y1 <= y0) {
-    return
-  }
+  if (!clip.inBounds) return
+
+  const {
+    x: dstX,
+    y: dstY,
+    sx: srcX,
+    sy: srcY,
+    w: copyW,
+    h: copyH,
+  } = clip
 
   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)
+  for (let row = 0; row < copyH; row++) {
+    const currentDstY = dstY + row
+    const currentSrcY = srcY + row
 
-    const dstStart = (dstY * dstW + x0) * 4
-    const srcStart = (srcY * srcW + srcXBase) * 4
+    const dstStart = (currentDstY * dstW + dstX) * 4
+    const srcStart = (currentSrcY * srcW + srcX) * 4
 
     if (useMask && mask) {
-      for (let ix = 0; ix < rowLenPixels; ix++) {
-        const mi = srcY * srcW + (srcXBase + ix)
+      for (let ix = 0; ix < copyW; ix++) {
+        const mi = currentSrcY * srcW + (srcX + ix)
         const alpha = mask[mi]
 
         if (alpha === 0) {
@@ -81,7 +89,7 @@ export function writeImageData(
         }
       }
     } else {
-      const byteLen = rowLenPixels * 4
+      const byteLen = copyW * 4
       const sub = srcData.subarray(srcStart, srcStart + byteLen)
       dstData.set(sub, dstStart)
     }

package/src/ImageData/writeImageDataBuffer.ts

@@ -1,4 +1,7 @@
 import type { Rect } from '../_types'
+import { makeClippedBlit, resolveBlitClipping } from '../Internal/resolveClipping'
+
+const SCRATCH_BLIT = makeClippedBlit()
 
 /**
  * Copies a pixel buffer into a specific region of an {@link ImageData} object.
@@ -46,28 +49,37 @@ export function writeImageDataBuffer(
 
   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)
+  const clip = resolveBlitClipping(
+    x,
+    y,
+    0,
+    0,
+    w,
+    h,
+    dstW,
+    dstH,
+    w,
+    h,
+    SCRATCH_BLIT,
+  )
 
-  // If the intersection is empty, do nothing
-  if (x1 <= x0 || y1 <= y0) return
+  if (!clip.inBounds) return
 
-  const rowLen = (x1 - x0) * 4
-  const srcCol = x0 - x
-  const srcYOffset = y0 - y
-  const actualH = y1 - y0
+  const {
+    x: dstX,
+    y: dstY,
+    sx: srcX,
+    sy: srcY,
+    w: copyW,
+    h: copyH,
+  } = clip
 
-  for (let row = 0; row < actualH; row++) {
-    // Target index
-    const dstStart = ((y0 + row) * dstW + x0) * 4
+  const rowLen = copyW * 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
+  for (let row = 0; row < copyH; row++) {
+    const dstStart = ((dstY + row) * dstW + dstX) * 4
+    const srcStart = ((srcY + row) * w + srcX) * 4
 
-    dst.set(data.subarray(o, o + rowLen), dstStart)
+    dst.set(data.subarray(srcStart, srcStart + rowLen), dstStart)
   }
 }

package/src/IndexedImage/indexedImageToAverageColor.ts

@@ -39,7 +39,7 @@ export function indexedImageToAverageColor(
       continue
     }
 
-    const color = palette[id]! >>> 0;
+    const color = palette[id]! >>> 0
 
     const r = color & 0xFF
     const g = (color >> 8) & 0xFF

package/src/Internal/resolveClipping.ts

@@ -0,0 +1,140 @@
+export type ClippedRect = {
+  x: number
+  y: number
+  w: number
+  h: number
+  inBounds: boolean
+}
+
+export type ClippedBlit = {
+  x: number
+  y: number
+  sx: number
+  sy: number
+  w: number
+  h: number
+  inBounds: boolean
+}
+
+// use factory functions when creating reusable objects ensure property order for JIT perf
+export const makeClippedRect = (): ClippedRect => ({
+  x: 0,
+  y: 0,
+  w: 0,
+  h: 0,
+  inBounds: false,
+})
+
+export const makeClippedBlit = (): ClippedBlit => ({
+  x: 0,
+  y: 0,
+  sx: 0,
+  sy: 0,
+  w: 0,
+  h: 0,
+  inBounds: false,
+})
+
+/**
+ * Calculates the intersection of a target rectangle and a bounding box (usually 0,0 -> width,height).
+ * Handles negative offsets by shrinking dimensions.
+ */
+export function resolveRectClipping(
+  x: number,
+  y: number,
+  w: number,
+  h: number,
+  boundaryW: number,
+  boundaryH: number,
+  out: ClippedRect,
+): ClippedRect {
+  // Destination Clipping (Top/Left)
+  if (x < 0) {
+    w += x
+    x = 0
+  }
+  if (y < 0) {
+    h += y
+    y = 0
+  }
+
+  // Destination Clipping (Bottom/Right)
+  const actualW = Math.min(w, boundaryW - x)
+  const actualH = Math.min(h, boundaryH - y)
+
+  if (actualW <= 0 || actualH <= 0) {
+    out.inBounds = false
+    return out
+  }
+
+  out.x = x
+  out.y = y
+  out.w = actualW
+  out.h = actualH
+  out.inBounds = true
+
+  return out
+}
+
+/**
+ * Calculates the clipping for transferring data from a Source to a Destination.
+ * Handles cases where the source is out of bounds (shifting the destination target)
+ * AND cases where the destination is out of bounds (shifting the source target).
+ */
+export function resolveBlitClipping(
+  x: number,
+  y: number,
+  sx: number,
+  sy: number,
+  w: number,
+  h: number,
+  dstW: number,
+  dstH: number,
+  srcW: number,
+  srcH: number,
+  out: ClippedBlit,
+): ClippedBlit {
+  // 1. Source Clipping: If reading from negative source, shift target right and shrink
+  if (sx < 0) {
+    x -= sx
+    w += sx
+    sx = 0
+  }
+  if (sy < 0) {
+    y -= sy
+    h += sy
+    sy = 0
+  }
+  w = Math.min(w, srcW - sx)
+  h = Math.min(h, srcH - sy)
+
+  // 2. Destination Clipping: If writing to negative dest, shift source right and shrink
+  if (x < 0) {
+    sx -= x
+    w += x
+    x = 0
+  }
+  if (y < 0) {
+    sy -= y
+    h += y
+    y = 0
+  }
+
+  const actualW = Math.min(w, dstW - x)
+  const actualH = Math.min(h, dstH - y)
+
+  if (actualW <= 0 || actualH <= 0) {
+    out.inBounds = false
+    return out
+  }
+
+  out.x = x
+  out.y = y
+  out.sx = sx
+  out.sy = sy
+  out.w = actualW
+  out.h = actualH
+  out.inBounds = true
+
+  return out
+}

package/src/Mask/applyBinaryMaskToAlphaMask.ts

@@ -0,0 +1,89 @@
+import type { AlphaMask, ApplyMaskToPixelDataOptions, BinaryMask } from '../_types'
+
+export function applyBinaryMaskToAlphaMask(
+  alphaMaskDst: AlphaMask,
+  dstWidth: number,
+  binaryMaskSrc: BinaryMask,
+  srcWidth: number,
+  opts: ApplyMaskToPixelDataOptions = {},
+): void {
+  const {
+    x: targetX = 0,
+    y: targetY = 0,
+    w: reqWidth = 0,
+    h: reqHeight = 0,
+    mx = 0,
+    my = 0,
+    invertMask = false,
+  } = opts
+
+  if (dstWidth <= 0) return
+  if (binaryMaskSrc.length === 0) return
+  if (srcWidth <= 0) return
+
+  const dstHeight = (alphaMaskDst.length / dstWidth) | 0
+  const srcHeight = (binaryMaskSrc.length / srcWidth) | 0
+
+  if (dstHeight <= 0) return
+  if (srcHeight <= 0) return
+
+  const dstX0 = Math.max(0, targetX)
+  const dstY0 = Math.max(0, targetY)
+  const dstX1 = reqWidth > 0 ? Math.min(dstWidth, targetX + reqWidth) : dstWidth
+  const dstY1 = reqHeight > 0 ? Math.min(dstHeight, targetY + reqHeight) : dstHeight
+
+  if (dstX0 >= dstX1) return
+  if (dstY0 >= dstY1) return
+
+  const srcX0 = mx + (dstX0 - targetX)
+  const srcY0 = my + (dstY0 - targetY)
+
+  if (srcX0 >= srcWidth) return
+  if (srcY0 >= srcHeight) return
+  if (srcX0 + (dstX1 - dstX0) <= 0) return
+  if (srcY0 + (dstY1 - dstY0) <= 0) return
+
+  const iterW = Math.min(dstX1 - dstX0, srcWidth - srcX0)
+  const iterH = Math.min(dstY1 - dstY0, srcHeight - srcY0)
+
+  let dstIdx = dstY0 * dstWidth + dstX0
+  let srcIdx = srcY0 * srcWidth + srcX0
+
+  if (invertMask) {
+    for (let row = 0; row < iterH; row++) {
+      const dstEnd = dstIdx + iterW
+      let d = dstIdx
+      let s = srcIdx
+
+      while (d < dstEnd) {
+        // inverted
+        if (binaryMaskSrc[s] !== 0) {
+          alphaMaskDst[d] = 0
+        }
+        d++
+        s++
+      }
+
+      dstIdx += dstWidth
+      srcIdx += srcWidth
+    }
+  } else {
+    for (let row = 0; row < iterH; row++) {
+      const dstEnd = dstIdx + iterW
+      let d = dstIdx
+      let s = srcIdx
+
+      while (d < dstEnd) {
+        // If binary mask is empty, clear the alpha pixel.
+        if (binaryMaskSrc[s] === 0) {
+          alphaMaskDst[d] = 0
+        }
+        d++
+        s++
+      }
+
+      dstIdx += dstWidth
+      srcIdx += srcWidth
+    }
+  }
+}

package/src/Mask/copyMask.ts

@@ -1,10 +1,8 @@
-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 {
+export function copyMask<T extends Uint8Array>(src: T): T {
   // Uint8Array.slice() is highly optimized at the engine level
   return src.slice() as T
 }

package/src/Mask/mergeAlphaMasks.ts

@@ -0,0 +1,81 @@
+import { type AlphaMask, type MergeAlphaMasksOptions } from '../_types'
+
+/**
+ * Merges 2 alpha masks values are 0-255
+ */
+export function mergeAlphaMasks(
+  dst: AlphaMask,
+  dstWidth: number,
+  src: AlphaMask,
+  srcWidth: number,
+  opts: MergeAlphaMasksOptions,
+): void {
+  const {
+    x: targetX = 0,
+    y: targetY = 0,
+    w: width = 0,
+    h: height = 0,
+    alpha: globalAlpha = 255,
+    mx = 0,
+    my = 0,
+    invertMask = false,
+  } = opts
+  const dstHeight = (dst.length / dstWidth) | 0
+  const srcHeight = (src.length / srcWidth) | 0
+
+  if (width <= 0) return
+  if (height <= 0) return
+  if (globalAlpha === 0) return
+
+  const startX = Math.max(0, -targetX, -mx)
+  const startY = Math.max(0, -targetY, -my)
+
+  const endX = Math.min(width, dstWidth - targetX, srcWidth - mx)
+  const endY = Math.min(height, dstHeight - targetY, srcHeight - my)
+
+  if (startX >= endX) return
+  if (startY >= endY) return
+
+  for (let iy = startY; iy < endY; iy++) {
+    const dy = targetY + iy
+    const sy = my + iy
+
+    let dIdx = dy * dstWidth + targetX + startX
+    let sIdx = sy * srcWidth + mx + startX
+
+    for (let ix = startX; ix < endX; ix++) {
+      const rawM = src[sIdx]
+      // Unified logic branch inside the hot path
+      const effectiveM = invertMask ? 255 - rawM : rawM
+
+      let weight = 0
+
+      if (effectiveM === 0) {
+        weight = 0
+      } else if (effectiveM === 255) {
+        weight = globalAlpha
+      } else if (globalAlpha === 255) {
+        weight = effectiveM
+      } else {
+        weight = (effectiveM * globalAlpha + 128) >> 8
+      }
+
+      if (weight !== 255) {
+        if (weight === 0) {
+          dst[dIdx] = 0
+        } else {
+          const da = dst[dIdx]
+
+          if (da === 255) {
+            dst[dIdx] = weight
+          } else if (da !== 0) {
+            dst[dIdx] = (da * weight + 128) >> 8
+          }
+        }
+      }
+
+      sIdx++
+      dIdx++
+    }
+  }
+}

package/src/Mask/mergeBinaryMasks.ts

@@ -0,0 +1,89 @@
+import type { BinaryMask, MergeAlphaMasksOptions } from '../_types'
+
+export function mergeBinaryMasks(
+  dst: BinaryMask,
+  dstWidth: number,
+  src: BinaryMask,
+  srcWidth: number,
+  opts: MergeAlphaMasksOptions,
+): void {
+  const {
+    x: targetX = 0,
+    y: targetY = 0,
+    w: width = 0,
+    h: height = 0,
+    mx = 0,
+    my = 0,
+    invertMask = false,
+  } = opts
+  if (dstWidth <= 0) return
+  if (srcWidth <= 0) return
+
+  const dstHeight = (dst.length / dstWidth) | 0
+  const srcHeight = (src.length / srcWidth) | 0
+
+  // 1. Destination Clipping
+  let x = targetX
+  let y = targetY
+  let w = width
+  let h = height
+
+  if (x < 0) {
+    w += x
+    x = 0
+  }
+
+  if (y < 0) {
+    h += y
+    y = 0
+  }
+
+  w = Math.min(w, dstWidth - x)
+  h = Math.min(h, dstHeight - y)
+
+  if (w <= 0) return
+  if (h <= 0) return
+
+  // 2. Source Bounds Clipping (Double Clipping)
+  const startX = mx + (x - targetX)
+  const startY = my + (y - targetY)
+
+  const sX0 = Math.max(0, startX)
+  const sY0 = Math.max(0, startY)
+  const sX1 = Math.min(srcWidth, startX + w)
+  const sY1 = Math.min(srcHeight, startY + h)
+
+  const finalW = sX1 - sX0
+  const finalH = sY1 - sY0
+
+  if (finalW <= 0) return
+  if (finalH <= 0) return
+
+  // 3. Coordinate Alignment
+  const xShift = sX0 - startX
+  const yShift = sY0 - startY
+
+  const dStride = dstWidth - finalW
+  const sStride = srcWidth - finalW
+
+  let dIdx = (y + yShift) * dstWidth + (x + xShift)
+  let sIdx = sY0 * srcWidth + sX0
+
+  for (let iy = 0; iy < finalH; iy++) {
+    for (let ix = 0; ix < finalW; ix++) {
+      const mVal = src[sIdx]
+      // Determine if the source pixel effectively "clears" the destination
+      const isMaskedOut = invertMask ? mVal !== 0 : mVal === 0
+
+      if (isMaskedOut) {
+        dst[dIdx] = 0
+      }
+
+      dIdx++
+      sIdx++
+    }
+
+    dIdx += dStride
+    sIdx += sStride
+  }
+}

package/src/PixelData/PixelBuffer32.ts

@@ -0,0 +1,28 @@
+import type { IPixelData } from '../_types'
+
+export class PixelBuffer32 implements IPixelData {
+  readonly data32: Uint32Array
+
+  constructor(
+    readonly width: number,
+    readonly height: number,
+    data32?: Uint32Array,
+  ) {
+    this.data32 = data32 ?? new Uint32Array(width * height)
+  }
+
+  set(width: number, height: number, data32?: Uint32Array): void {
+    ;(this as any).data32 = data32 ?? new Uint32Array(width * height)
+    ;(this as any).width = width
+    ;(this as any).height = height
+  }
+
+  copy(): PixelBuffer32 {
+    const newData32 = new Uint32Array(this.data32)
+    return new PixelBuffer32(
+      this.width,
+      this.height,
+      newData32,
+    )
+  }
+}