pixel-data-js 0.20.0 → 0.22.2

package/src/Mask/extractMaskBuffer.ts

@@ -0,0 +1,87 @@
+import type { Rect } from '../_types'
+
+/**
+ * Extracts a rectangular region from a 1D {@link Uint8Array} mask.
+ * This utility calculates the necessary offsets based on the `maskWidth` to
+ * slice out a specific area.
+ *
+ * @param maskBuffer - The source 1D array representing the full 2D mask.
+ * @param maskWidth - The width of the original source mask (stride).
+ * @param rect - A {@link Rect} object defining the region to extract.
+ * @returns A new {@link Uint8Array} containing the extracted region.
+ */
+export function extractMaskBuffer(
+  maskBuffer: Uint8Array,
+  maskWidth: number,
+  rect: Rect,
+): Uint8Array
+
+/**
+ * @param maskBuffer - The source 1D array representing the full 2D mask.
+ * @param maskWidth - The width of the original source mask (stride).
+ * @param x - The starting horizontal coordinate.
+ * @param y - The starting vertical coordinate.
+ * @param w - The width of the region to extract.
+ * @param h - The height of the region to extract.
+ * @returns A new {@link Uint8Array} containing the extracted region.
+ */
+export function extractMaskBuffer(
+  maskBuffer: Uint8Array,
+  maskWidth: number,
+  x: number,
+  y: number,
+  w: number,
+  h: number,
+): Uint8Array
+export function extractMaskBuffer(
+  maskBuffer: Uint8Array,
+  maskWidth: number,
+  xOrRect: number | Rect,
+  y?: number,
+  w?: number,
+  h?: number,
+): Uint8Array {
+  let finalX: number
+  let finalY: number
+  let finalW: number
+  let finalH: number
+
+  if (typeof xOrRect === 'object') {
+    finalX = xOrRect.x
+    finalY = xOrRect.y
+    finalW = xOrRect.w
+    finalH = xOrRect.h
+  } else {
+    finalX = xOrRect
+    finalY = y!
+    finalW = w!
+    finalH = h!
+  }
+
+  const out = new Uint8Array(finalW * finalH)
+  const srcH = maskBuffer.length / maskWidth
+
+  for (let row = 0; row < finalH; row++) {
+    const currentSrcY = finalY + row
+
+    if (currentSrcY < 0 || currentSrcY >= srcH) {
+      continue
+    }
+
+    const start = Math.max(0, finalX)
+    const end = Math.min(maskWidth, finalX + finalW)
+
+    if (start < end) {
+      const srcOffset = currentSrcY * maskWidth + start
+      const dstOffset = (row * finalW) + (start - finalX)
+      const count = end - start
+
+      out.set(
+        maskBuffer.subarray(srcOffset, srcOffset + count),
+        dstOffset,
+      )
+    }
+  }
+
+  return out
+}

package/src/Mask/invertMask.ts

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

package/src/Mask/mergeAlphaMasks.ts

@@ -5,9 +5,7 @@ import { type AlphaMask, type MergeAlphaMasksOptions } from '../_types'
  */
 export function mergeAlphaMasks(
   dst: AlphaMask,
-  dstWidth: number,
   src: AlphaMask,
-  srcWidth: number,
   opts: MergeAlphaMasksOptions,
 ): void {
   const {
@@ -20,18 +18,21 @@ export function mergeAlphaMasks(
     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 dstData = dst.data
+  const srcData = src.data
+  const srcWidth = src.w
+  const dstWidth = dst.w
+
   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)
+  const endY = Math.min(height, dst.h - targetY, src.h - my)
 
   if (startX >= endX) return
   if (startY >= endY) return
@@ -44,7 +45,7 @@ export function mergeAlphaMasks(
     let sIdx = sy * srcWidth + mx + startX
 
     for (let ix = startX; ix < endX; ix++) {
-      const rawM = src[sIdx]
+      const rawM = srcData[sIdx]
       // Unified logic branch inside the hot path
       const effectiveM = invertMask ? 255 - rawM : rawM
 
@@ -62,14 +63,14 @@ export function mergeAlphaMasks(
 
       if (weight !== 255) {
         if (weight === 0) {
-          dst[dIdx] = 0
+          dstData[dIdx] = 0
         } else {
-          const da = dst[dIdx]
+          const da = dstData[dIdx]
 
           if (da === 255) {
-            dst[dIdx] = weight
+            dstData[dIdx] = weight
           } else if (da !== 0) {
-            dst[dIdx] = (da * weight + 128) >> 8
+            dstData[dIdx] = (da * weight + 128) >> 8
           }
         }
       }

package/src/Mask/mergeBinaryMasks.ts

@@ -2,9 +2,7 @@ import type { BinaryMask, MergeAlphaMasksOptions } from '../_types'
 
 export function mergeBinaryMasks(
   dst: BinaryMask,
-  dstWidth: number,
   src: BinaryMask,
-  srcWidth: number,
   opts: MergeAlphaMasksOptions,
 ): void {
   const {
@@ -16,12 +14,15 @@ export function mergeBinaryMasks(
     my = 0,
     invertMask = false,
   } = opts
+
+  const dstData = dst.data
+  const srcData = src.data
+  const srcWidth = src.w
+  const dstWidth = dst.w
+
   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
@@ -39,7 +40,7 @@ export function mergeBinaryMasks(
   }
 
   w = Math.min(w, dstWidth - x)
-  h = Math.min(h, dstHeight - y)
+  h = Math.min(h, dst.h - y)
 
   if (w <= 0) return
   if (h <= 0) return
@@ -51,7 +52,7 @@ export function mergeBinaryMasks(
   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 sY1 = Math.min(src.h, startY + h)
 
   const finalW = sX1 - sX0
   const finalH = sY1 - sY0
@@ -71,12 +72,12 @@ export function mergeBinaryMasks(
 
   for (let iy = 0; iy < finalH; iy++) {
     for (let ix = 0; ix < finalW; ix++) {
-      const mVal = src[sIdx]
+      const mVal = srcData[sIdx]
       // Determine if the source pixel effectively "clears" the destination
       const isMaskedOut = invertMask ? mVal !== 0 : mVal === 0
 
       if (isMaskedOut) {
-        dst[dIdx] = 0
+        dstData[dIdx] = 0
       }
 
       dIdx++

package/src/Mask/setMaskData.ts

@@ -0,0 +1,7 @@
+import type { Mask } from '../_types'
+
+export function setMaskData(mask: Mask, width: number, height: number, data: Uint8Array): void {
+  ;(mask as any).w = width
+  ;(mask as any).h = height
+  ;(mask as any).data = data
+}

package/src/MaskRect/merge2BinaryMaskRects.ts

@@ -0,0 +1,81 @@
+import { MaskType, type NullableBinaryMaskRect } from '../_types'
+import { getRectsBounds } from '../Rect/getRectsBounds'
+
+export function merge2BinaryMaskRects(
+  a: NullableBinaryMaskRect,
+  b: NullableBinaryMaskRect,
+): NullableBinaryMaskRect {
+  const bounds = getRectsBounds([a, b])
+
+  // If both are fully selected, check if they form a perfect, gapless rectangle
+  if (
+    (a.data === null || a.data === undefined)
+    && (b.data === null || b.data === undefined)
+  ) {
+    const ix = Math.max(a.x, b.x)
+    const iy = Math.max(a.y, b.y)
+    const ir = Math.min(a.x + a.w, b.x + b.w)
+    const ib = Math.min(a.y + a.h, b.y + b.h)
+
+    const iw = Math.max(0, ir - ix)
+    const ih = Math.max(0, ib - iy)
+
+    const intersectionArea = iw * ih
+    const areaA = a.w * a.h
+    const areaB = b.w * b.h
+    const boundsArea = bounds.w * bounds.h
+
+    if (boundsArea === areaA + areaB - intersectionArea) {
+      return {
+        ...bounds,
+        data: null,
+        type: null,
+      }
+    }
+  }
+
+ const maskData =  new Uint8Array(bounds.w * bounds.h)
+
+  // --- Write A's contribution ---
+  const aOffY = a.y - bounds.y
+  const aOffX = a.x - bounds.x
+
+  if (a.data === undefined || a.data === null) {
+    for (let ay = 0; ay < a.h; ay++) {
+      const destRow = (aOffY + ay) * bounds.w + aOffX
+      maskData.fill(1, destRow, destRow + a.w)
+    }
+  } else {
+    for (let ay = 0; ay < a.h; ay++) {
+      const srcRow = ay * a.w
+      const destRow = (aOffY + ay) * bounds.w + aOffX
+      maskData.set(a.data.subarray(srcRow, srcRow + a.w), destRow)
+    }
+  }
+
+  // --- OR B's contribution ---
+  const bOffY = b.y - bounds.y
+  const bOffX = b.x - bounds.x
+
+  if (b.data === undefined || b.data === null) {
+    for (let by = 0; by < b.h; by++) {
+      const destRow = (bOffY + by) * bounds.w + bOffX
+      maskData.fill(1, destRow, destRow + b.w)
+    }
+  } else {
+    for (let by = 0; by < b.h; by++) {
+      const srcRow = by * b.w
+      const destRow = (bOffY + by) * bounds.w + bOffX
+
+      for (let bx = 0; bx < b.w; bx++) {
+        maskData[destRow + bx] |= b.data[srcRow + bx]
+      }
+    }
+  }
+
+  return {
+    ...bounds,
+    data: maskData,
+    type: MaskType.BINARY,
+  }
+}

package/src/MaskRect/mergeBinaryMaskRects.ts

@@ -0,0 +1,39 @@
+import type { NullableBinaryMaskRect } from '../_types'
+import { merge2BinaryMaskRects } from './merge2BinaryMaskRects'
+
+export function mergeBinaryMaskRects(current: NullableBinaryMaskRect[], adding: NullableBinaryMaskRect[]): NullableBinaryMaskRect[] {
+  const rects = [...current, ...adding]
+
+  let changed = true
+  while (changed) {
+    changed = false
+    const next: NullableBinaryMaskRect[] = []
+
+    for (const r of rects) {
+      let merged = false
+
+      for (let i = 0; i < next.length; i++) {
+        const n = next[i]
+
+        const overlap =
+          r.x <= n.x + n.w &&
+          r.x + r.w >= n.x &&
+          r.y <= n.y + n.h &&
+          r.y + r.h >= n.y
+
+        if (overlap) {
+          next[i] = merge2BinaryMaskRects(n, r)
+          merged = true
+          changed = true
+          break
+        }
+      }
+
+      if (!merged) next.push(r)
+    }
+
+    rects.splice(0, rects.length, ...next)
+  }
+
+  return rects
+}

package/src/MaskRect/subtractBinaryMaskRects.ts

@@ -0,0 +1,80 @@
+import { MaskType, type NullableBinaryMaskRect } from '../_types'
+
+export function subtractBinaryMaskRects(
+  current: NullableBinaryMaskRect[],
+  subtracting: NullableBinaryMaskRect[],
+): NullableBinaryMaskRect[] {
+  let result = [...current]
+
+  for (const sub of subtracting) {
+    const next: NullableBinaryMaskRect[] = []
+
+    for (const r of result) {
+      const ix = Math.max(r.x, sub.x)
+      const iy = Math.max(r.y, sub.y)
+      const ix2 = Math.min(r.x + r.w, sub.x + sub.w)
+      const iy2 = Math.min(r.y + r.h, sub.y + sub.h)
+
+      if (ix >= ix2 || iy >= iy2) {
+        next.push(r)
+        continue
+      }
+
+      // Split r into up to 4 pieces around the intersection.
+      // Extract directly from r.mask — no intermediate copy, no mutation.
+      //
+      //   ┌──────────────┐
+      //   │     TOP      │  r.y .. iy      (full width)
+      //   ├────┬─────┬───┤
+      //   │LEFT│ sub │RGT│  iy .. iy2      (side strips)
+      //   ├────┴─────┴───┤
+      //   │    BOTTOM    │  iy2 .. r.y+r.h (full width)
+      //   └──────────────┘
+
+      if (r.y < iy) pushPiece(next, r, r.x, r.y, r.w, iy - r.y)
+      if (iy2 < r.y + r.h) pushPiece(next, r, r.x, iy2, r.w, r.y + r.h - iy2)
+      if (r.x < ix) pushPiece(next, r, r.x, iy, ix - r.x, iy2 - iy)
+      if (ix2 < r.x + r.w) pushPiece(next, r, ix2, iy, r.x + r.w - ix2, iy2 - iy)
+    }
+
+    result = next
+  }
+
+  return result
+}
+
+/**
+ * Extract sub-region (x, y, w, h) in global coords from r's mask and push
+ * onto dest. If r.mask is null (fully selected) the piece is also null —
+ * zero allocations on the happy path.
+ */
+function pushPiece(
+  dest: NullableBinaryMaskRect[],
+  r: NullableBinaryMaskRect,
+  x: number,
+  y: number,
+  w: number,
+  h: number,
+): void {
+  if (r.data === null || r.data === undefined) {
+    dest.push({ x, y, w, h, data: null, type: null })
+    return
+  }
+
+  // Coords local to r.mask
+  const lx = x - r.x
+  const ly = y - r.y
+
+  const data = new Uint8Array(w * h)
+  for (let row = 0; row < h; row++) {
+    data.set(
+      r.data.subarray(
+        (ly + row) * r.w + lx,
+        (ly + row) * r.w + lx + w,
+      ),
+      row * w,
+    )
+  }
+
+  dest.push({ x, y, w, h, data, type: MaskType.BINARY })
+}

package/src/PixelData/applyAlphaMaskToPixelData.ts

@@ -1,5 +1,9 @@
 import { type AlphaMask, type ApplyMaskToPixelDataOptions, type IPixelData } from '../_types'
 
+/**
+ * Directly applies a mask to a region of PixelData,
+ * modifying the destination's alpha channel in-place.
+ */
 export function applyAlphaMaskToPixelData(
   dst: IPixelData,
   mask: AlphaMask,
@@ -11,7 +15,6 @@ export function applyAlphaMaskToPixelData(
     w: width = dst.width,
     h: height = dst.height,
     alpha: globalAlpha = 255,
-    mw,
     mx = 0,
     my = 0,
     invertMask = false,
@@ -42,9 +45,8 @@ export function applyAlphaMaskToPixelData(
   if (h <= 0) return
 
   // 2. Determine Source Dimensions
-  const mPitch = mw ?? width
+  const mPitch = mask.w
   if (mPitch <= 0) return
-  const maskHeight = (mask.length / mPitch) | 0
 
   // 3. Source Bounds Clipping
   // Calculate where we would start reading in the mask
@@ -55,7 +57,7 @@ export function applyAlphaMaskToPixelData(
   const sX0 = Math.max(0, startX)
   const sY0 = Math.max(0, startY)
   const sX1 = Math.min(mPitch, startX + w)
-  const sY1 = Math.min(maskHeight, startY + h)
+  const sY1 = Math.min(mask.h, startY + h)
 
   const finalW = sX1 - sX0
   const finalH = sY1 - sY0
@@ -73,13 +75,14 @@ export function applyAlphaMaskToPixelData(
   const dw = dst.width
   const dStride = dw - finalW
   const mStride = mPitch - finalW
+  const maskData = mask.data
 
   let dIdx = (y + yShift) * dw + (x + xShift)
   let mIdx = sY0 * mPitch + sX0
 
   for (let iy = 0; iy < h; iy++) {
     for (let ix = 0; ix < w; ix++) {
-      const mVal = mask[mIdx]
+      const mVal = maskData[mIdx]
       // Unified logic branch inside the hot path
       const effectiveM = invertMask ? 255 - mVal : mVal
 

package/src/PixelData/applyBinaryMaskToPixelData.ts

@@ -14,14 +14,13 @@ export function applyBinaryMaskToPixelData(
     y: targetY = 0,
     w: width = dst.width,
     h: height = dst.height,
-    alpha = 255,
-    mw,
+    alpha: globalAlpha = 255,
     mx = 0,
     my = 0,
     invertMask = false,
   } = opts
 
-  if (alpha === 0) return
+  if (globalAlpha === 0) return
 
   // 1. Initial Destination Clipping
   let x = targetX
@@ -46,9 +45,8 @@ export function applyBinaryMaskToPixelData(
   if (h <= 0) return
 
   // 2. Determine Source Dimensions
-  const mPitch = mw ?? width
+  const mPitch = mask.w
   if (mPitch <= 0) return
-  const maskHeight = (mask.length / mPitch) | 0
 
   // 3. Source Bounds Clipping
   // Calculate where we would start reading in the mask
@@ -59,7 +57,7 @@ export function applyBinaryMaskToPixelData(
   const sX0 = Math.max(0, startX)
   const sY0 = Math.max(0, startY)
   const sX1 = Math.min(mPitch, startX + w)
-  const sY1 = Math.min(maskHeight, startY + h)
+  const sY1 = Math.min(mask.h, startY + h)
 
   const finalW = sX1 - sX0
   const finalH = sY1 - sY0
@@ -77,26 +75,27 @@ export function applyBinaryMaskToPixelData(
   const dw = dst.width
   const dStride = dw - finalW
   const mStride = mPitch - finalW
+  const maskData = mask.data
 
   let dIdx = (y + yShift) * dw + (x + xShift)
   let mIdx = sY0 * mPitch + sX0
 
   for (let iy = 0; iy < h; iy++) {
     for (let ix = 0; ix < w; ix++) {
-      const mVal = mask[mIdx]
+      const mVal = maskData[mIdx]
       // Consistently determines if this pixel should be "masked out" (cleared)
       const isMaskedOut = invertMask ? mVal !== 0 : mVal === 0
 
       if (isMaskedOut) {
         // Clear alpha channel only (keep RGB)
         dst32[dIdx] = (dst32[dIdx] & 0x00ffffff) >>> 0
-      } else if (alpha !== 255) {
+      } else if (globalAlpha !== 255) {
         const d = dst32[dIdx]
         const da = d >>> 24
 
         // If pixel isn't already fully transparent, apply global alpha
         if (da !== 0) {
-          const finalAlpha = da === 255 ? alpha : (da * alpha + 128) >> 8
+          const finalAlpha = da === 255 ? globalAlpha : (da * globalAlpha + 128) >> 8
           dst32[dIdx] = ((d & 0x00ffffff) | (finalAlpha << 24)) >>> 0
         }
       }