pixel-data-js 0.20.0 → 0.22.2

package/src/History/PixelMutator/mutatorApplyRectBrushStroke.ts

@@ -3,7 +3,7 @@ import {
   type BlendColor32,
   type Color32,
   type ColorBlendOptions,
-  type HistoryMutator,
+  type HistoryMutator, MaskType,
   type Rect,
 } from '../../_types'
 import { forEachLinePoint } from '../../Algorithm/forEachLinePoint'
@@ -22,6 +22,9 @@ const defaults = {
 
 type Deps = Partial<typeof defaults>
 
+/**
+ * @param deps - @hidden
+ */
 export const mutatorApplyRectBrushStroke = ((writer: PixelWriter<any>, deps: Deps = defaults) => {
   const {
     forEachLinePoint = defaults.forEachLinePoint,
@@ -53,6 +56,13 @@ export const mutatorApplyRectBrushStroke = ((writer: PixelWriter<any>, deps: Dep
     h: 0,
   }
 
+  const mask = {
+    type: MaskType.ALPHA,
+    data: null as unknown as Uint8Array,
+    w: 0,
+    h: 0,
+  }
+
   return {
     applyRectBrushStroke(
       color: Color32,
@@ -83,8 +93,11 @@ export const mutatorApplyRectBrushStroke = ((writer: PixelWriter<any>, deps: Dep
 
       if (bw <= 0 || bh <= 0) return
 
-      const mask = new Uint8Array(bw * bh) as AlphaMask
+      mask.data = new Uint8Array(bw * bh)
+      mask.w = bw
+      mask.h = bh
 
+      const maskData = mask.data
       const halfW = brushWidth / 2
       const halfH = brushHeight / 2
       const invHalfW = 1 / halfW
@@ -143,8 +156,8 @@ export const mutatorApplyRectBrushStroke = ((writer: PixelWriter<any>, deps: Dep
             if (strength > 0) {
               const intensity = (strength * 255) | 0
 
-              if (intensity > mask[maskIdx]) {
-                mask[maskIdx] = intensity
+              if (intensity > maskData[maskIdx]) {
+                maskData[maskIdx] = intensity
               }
             }
           }
@@ -161,7 +174,7 @@ export const mutatorApplyRectBrushStroke = ((writer: PixelWriter<any>, deps: Dep
       blendColorPixelDataAlphaMask(
         writer.target,
         color,
-        mask,
+        mask as AlphaMask,
         blendColorPixelOptions,
       )
     },

package/src/History/PixelMutator/mutatorApplyRectPencil.ts

@@ -11,6 +11,9 @@ const defaults = {
 
 type Deps = Partial<typeof defaults>
 
+/**
+ * @param deps - @hidden
+ */
 export const mutatorApplyRectPencil = ((writer: PixelWriter<any>, deps: Deps = defaults) => {
   const {
     applyRectBrushToPixelData = defaults.applyRectBrushToPixelData,

package/src/History/PixelMutator/mutatorApplyRectPencilStroke.ts

@@ -3,7 +3,7 @@ import {
   type BlendColor32,
   type Color32,
   type ColorBlendOptions,
-  type HistoryMutator,
+  type HistoryMutator, MaskType,
   type Rect,
 } from '../../_types'
 import { forEachLinePoint } from '../../Algorithm/forEachLinePoint'
@@ -21,6 +21,10 @@ const defaults = {
 }
 
 type Deps = Partial<typeof defaults>
+
+/**
+ * @param deps - @hidden
+ */
 export const mutatorApplyRectPencilStroke = ((writer: PixelWriter<any>, deps: Deps = defaults) => {
   const {
     forEachLinePoint = defaults.forEachLinePoint,
@@ -52,6 +56,13 @@ export const mutatorApplyRectPencilStroke = ((writer: PixelWriter<any>, deps: De
     h: 0,
   }
 
+  const mask = {
+    type: MaskType.BINARY,
+    data: null as unknown as Uint8Array,
+    w: 0,
+    h: 0,
+  }
+
   return {
     applyRectPencilStroke(
       color: Color32,
@@ -81,7 +92,11 @@ export const mutatorApplyRectPencilStroke = ((writer: PixelWriter<any>, deps: De
 
       if (bw <= 0 || bh <= 0) return
 
-      const mask = new Uint8Array(bw * bh) as BinaryMask
+      mask.data = new Uint8Array(bw * bh)
+      mask.w = bw
+      mask.h = bh
+
+      const maskData = mask.data
 
       const halfW = brushWidth / 2
       const halfH = brushHeight / 2
@@ -130,7 +145,7 @@ export const mutatorApplyRectPencilStroke = ((writer: PixelWriter<any>, deps: De
             const maskIdx = maskRowOffset + (mx - bx)
 
             if (dx <= halfW && dy <= halfH) {
-              mask[maskIdx] = 1
+              maskData[maskIdx] = 1
             }
           }
         }
@@ -143,7 +158,7 @@ export const mutatorApplyRectPencilStroke = ((writer: PixelWriter<any>, deps: De
       blendColorPixelOptions.w = bw
       blendColorPixelOptions.h = bh
 
-      blendColorPixelDataBinaryMask(writer.target, color, mask, blendColorPixelOptions)
+      blendColorPixelDataBinaryMask(writer.target, color, mask as BinaryMask, blendColorPixelOptions)
     },
   }
 }) satisfies HistoryMutator<any, Deps>

package/src/History/PixelMutator/mutatorBlendColor.ts

@@ -4,6 +4,10 @@ import { PixelWriter } from '../PixelWriter'
 
 const defaults = { blendColorPixelData }
 type Deps = Partial<typeof defaults>
+
+/**
+ * @param deps - @hidden
+ */
 export const mutatorBlendColor = ((writer: PixelWriter<any>, deps: Deps = defaults) => {
   const {
     blendColorPixelData = defaults.blendColorPixelData,

package/src/History/PixelMutator/mutatorBlendPixelData.ts

@@ -4,6 +4,10 @@ import { PixelWriter } from '../PixelWriter'
 
 const defaults = { blendPixelData }
 type Deps = Partial<typeof defaults>
+
+/**
+ * @param deps - @hidden
+ */
 export const mutatorBlendPixelData = ((writer: PixelWriter<any>, deps: Partial<Deps> = defaults) => {
   const {
     blendPixelData = defaults.blendPixelData,

package/src/History/PixelMutator/mutatorClear.ts

@@ -1,10 +1,14 @@
-import type { Color32, HistoryMutator, Rect } from '../../_types'
+import type { BinaryMaskRect, Color32, HistoryMutator } from '../../_types'
 import { fillPixelData } from '../../PixelData/fillPixelData'
 import { PixelWriter } from '../PixelWriter'
 
 const defaults = { fillPixelData }
 
 type Deps = Partial<typeof defaults>
+
+/**
+ * @param deps - @hidden
+ */
 export const mutatorClear = ((writer: PixelWriter<any>, deps: Deps = defaults) => {
   const {
     fillPixelData = defaults.fillPixelData,
@@ -12,14 +16,13 @@ export const mutatorClear = ((writer: PixelWriter<any>, deps: Deps = defaults) =
 
   return {
     clear(
-      rect: Partial<Rect> = {},
+      rect: Partial<BinaryMaskRect> = {},
     ) {
-      const {
-        x = 0,
-        y = 0,
-        w = writer.target.width,
-        h = writer.target.height,
-      } = rect
+      const x = rect.x ?? 0
+      const y = rect.y ?? 0
+      const w = rect.w ?? writer.target.width
+      const h = rect.h ?? writer.target.height
+
       writer.accumulator.storeRegionBeforeState(x, y, w, h)
       fillPixelData(writer.target, 0 as Color32, x, y, w, h)
     },

package/src/History/PixelMutator/mutatorFill.ts

@@ -4,6 +4,10 @@ import { PixelWriter } from '../PixelWriter'
 
 const defaults = { fillPixelData }
 type Deps = Partial<typeof defaults>
+
+/**
+ * @param deps - @hidden
+ */
 export const mutatorFill = ((writer: PixelWriter<any>, deps: Deps = defaults) => {
   const {
     fillPixelData = defaults.fillPixelData,

package/src/History/PixelMutator/mutatorFillBinaryMask.ts

@@ -0,0 +1,28 @@
+import type { BinaryMask, Color32, HistoryMutator } from '../../_types'
+import { fillPixelDataBinaryMask } from '../../PixelData/fillPixelDataBinaryMask'
+import { PixelWriter } from '../PixelWriter'
+
+const defaults = { fillPixelDataBinaryMask }
+type Deps = Partial<typeof defaults>
+
+/**
+ * @param deps - @hidden
+ */
+export const mutatorFillBinaryMask = ((writer: PixelWriter<any>, deps: Deps = defaults) => {
+  const {
+    fillPixelDataBinaryMask = defaults.fillPixelDataBinaryMask,
+  } = deps
+
+  return {
+    fillBinaryMask(
+      color: Color32,
+      mask: BinaryMask,
+      alpha = 255,
+      x = 0,
+      y = 0,
+    ) {
+      writer.accumulator.storeRegionBeforeState(x, y, mask.w, mask.h)
+      fillPixelDataBinaryMask(writer.target, color, mask, alpha, x, y)
+    },
+  }
+}) satisfies HistoryMutator<any, Deps>

package/src/History/PixelMutator/mutatorInvert.ts

@@ -5,6 +5,9 @@ import { PixelWriter } from '../PixelWriter'
 const defaults = { invertPixelData }
 type Deps = Partial<typeof defaults>
 
+/**
+ * @param deps - @hidden
+ */
 export const mutatorInvert = ((writer: PixelWriter<any>, deps: Deps = defaults) => {
   const {
     invertPixelData = defaults.invertPixelData,

package/src/ImageData/extractImageDataBuffer.ts

@@ -10,8 +10,8 @@ const SCRATCH_BLIT = makeClippedBlit()
  * This is a "read-only" operation that returns a copy of the pixel data.
  *
  * @param imageData - The source image data to read from.
- * @param rect - A {@link Rect} object defining the region to extract.
- * @returns A {@link Uint8ClampedArray} containing the RGBA pixel data of the region.
+ * @param rect - A rect defining the region to extract.
+ * @returns A buffer containing the RGBA pixel data of the region.
  */
 export function extractImageDataBuffer(
   imageData: ImageDataLike,
@@ -23,7 +23,7 @@ export function extractImageDataBuffer(
  * @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 {@link Uint8ClampedArray} containing the RGBA pixel data of the region.
+ * @returns A buffer containing the RGBA pixel data of the region.
  */
 export function extractImageDataBuffer(
   imageData: ImageDataLike,

package/src/ImageData/{imageDataToAlphaMask.ts → imageDataToAlphaMaskBuffer.ts}

@@ -1,4 +1,3 @@
-import type { AlphaMask } from '../_types'
 import { pixelDataToAlphaMask } from '../PixelData/pixelDataToAlphaMask'
 
 /**
@@ -6,9 +5,9 @@ import { pixelDataToAlphaMask } from '../PixelData/pixelDataToAlphaMask'
  * When possible use {@link pixelDataToAlphaMask} instead.
  * Repeat calls to the same data will use less memory.
  */
-export function imageDataToAlphaMask(
+export function imageDataToAlphaMaskBuffer(
   imageData: ImageData,
-): AlphaMask {
+): Uint8Array {
   const {
     width,
     height,
@@ -22,7 +21,7 @@ export function imageDataToAlphaMask(
     data.byteLength >> 2,
   )
   const len = data32.length
-  const mask = new Uint8Array(width * height) as AlphaMask
+  const mask = new Uint8Array(width * height)
 
   for (let i = 0; i < len; i++) {
     const val = data32[i]

package/src/ImageData/resizeImageData.ts

@@ -7,15 +7,13 @@ import type { ImageDataLike } from '../_types'
  * instead, it crops or pads the image based on the new dimensions and
  * provides an offset for repositioning.
  *
- * @param current The source {@link ImageDataLike} to resize.
+ * @param target The target to resize.
  * @param newWidth The target width in pixels.
  * @param newHeight The target height in pixels.
  * @param offsetX The horizontal offset for placing the
  * original image within the new buffer.
- * @default 0
  * @param offsetY The vertical offset for placing the
  * original image within the new buffer.
- * @default 0
  *
  * @returns A new {@link ImageData} instance with the specified dimensions.
  *
@@ -32,7 +30,7 @@ import type { ImageDataLike } from '../_types'
  * ```
  */
 export function resizeImageData(
-  current: ImageDataLike,
+  target: ImageDataLike,
   newWidth: number,
   newHeight: number,
   offsetX = 0,
@@ -43,7 +41,7 @@ export function resizeImageData(
     width: oldW,
     height: oldH,
     data: oldData,
-  } = current
+  } = target
   const newData = result.data
 
   // Determine intersection of the old image (at offset) and new canvas bounds

package/src/ImageData/writeImageDataBuffer.ts

@@ -10,17 +10,17 @@ const SCRATCH_BLIT = makeClippedBlit()
  * into the target {@link ImageData} buffer. It supports both {@link Rect}
  * objects and discrete coordinates.
  *
- * @param imageData - The target {@link ImageData} to write into. Must match the rect width/height.
+ * @param target - The target to write into. Must match the rect width/height.
  * @param data - The source pixel data (RGBA).
- * @param rect - A {@link Rect} object defining the destination region.
+ * @param rect - A rect defining the destination region.
  */
 export function writeImageDataBuffer(
-  imageData: ImageData,
+  target: ImageData,
   data: Uint8ClampedArray,
   rect: Rect,
 ): void
 /**
- * @param imageData - The target {@link ImageData} to write into.
+ * @param target - The target to write into.
  * @param data - The source pixel data (RGBA). Must match the width/height.
  * @param x - The starting horizontal coordinate in the target.
  * @param y - The starting vertical coordinate in the target.
@@ -28,7 +28,7 @@ export function writeImageDataBuffer(
  * @param h - The height of the region to write.
  */
 export function writeImageDataBuffer(
-  imageData: ImageData,
+  target: ImageData,
   data: Uint8ClampedArray,
   x: number,
   y: number,
@@ -36,7 +36,7 @@ export function writeImageDataBuffer(
   h: number,
 ): void
 export function writeImageDataBuffer(
-  imageData: ImageData,
+  target: ImageData,
   data: Uint8ClampedArray,
   _x: Rect | number,
   _y?: number,
@@ -47,7 +47,7 @@ export function writeImageDataBuffer(
     ? _x
     : { x: _x, y: _y!, w: _w!, h: _h! }
 
-  const { width: dstW, height: dstH, data: dst } = imageData
+  const { width: dstW, height: dstH, data: dst } = target
 
   const clip = resolveBlitClipping(
     x,

package/src/Mask/AlphaMask.ts

@@ -0,0 +1,16 @@
+import { type AlphaMask, MaskType } from '../_types'
+
+/**
+ * Creates an Alpha Mask
+ * @param w - width
+ * @param h - height
+ * @param data - values 0-255
+ */
+export function makeAlphaMask(w: number, h: number, data?: Uint8Array): AlphaMask {
+  return {
+    type: MaskType.ALPHA,
+    data: data ?? new Uint8Array(w * h),
+    w,
+    h,
+  }
+}

package/src/Mask/BinaryMask.ts

@@ -0,0 +1,16 @@
+import { type BinaryMask, MaskType } from '../_types'
+
+/**
+ * Creates a Binary Mask
+ * @param w - width
+ * @param h - height
+ * @param data - values 0-1
+ */
+export function makeBinaryMask(w: number, h: number, data?: Uint8Array): BinaryMask {
+  return {
+    type: MaskType.BINARY,
+    data: data ?? new Uint8Array(w * h),
+    w,
+    h,
+  }
+}

package/src/Mask/CircleBrushAlphaMask.ts

@@ -0,0 +1,32 @@
+import { type CircleBrushAlphaMask, MaskType } from '../_types'
+
+export function makeCircleBrushAlphaMask(size: number, fallOff: (d: number) => number = () => 1): CircleBrushAlphaMask {
+  const area = size * size
+  const data = new Uint8Array(area)
+  const radius = size / 2
+  const invR = 1 / radius
+
+  const minOffset = -Math.ceil(radius - 0.5)
+
+  for (let y = 0; y < size; y++) {
+    for (let x = 0; x < size; x++) {
+      const dx = x - radius + 0.5
+      const dy = y - radius + 0.5
+      const distSqr = dx * dx + dy * dy
+      if (distSqr <= (radius * radius)) {
+        const dist = Math.sqrt(distSqr)
+        data[y * size + x] = (fallOff(1 - (dist * invR)) * 255) | 0
+      }
+    }
+  }
+
+  return {
+    type: MaskType.ALPHA,
+    data,
+    w: size,
+    h: size,
+    radius,
+    size,
+    minOffset,
+  }
+}

package/src/Mask/CircleBrushBinaryMask.ts

@@ -0,0 +1,30 @@
+import { type CircleBrushBinaryMask, MaskType } from '../_types'
+
+export function makeCircleBrushBinaryMask(size: number): CircleBrushBinaryMask {
+  const area = size * size
+  const data = new Uint8Array(area)
+  const radius = size / 2
+
+  const minOffset = -Math.ceil(radius - 0.5)
+
+  for (let y = 0; y < size; y++) {
+    for (let x = 0; x < size; x++) {
+      const dx = x - radius + 0.5
+      const dy = y - radius + 0.5
+      const distSqr = dx * dx + dy * dy
+      if (distSqr <= (radius * radius)) {
+        data[y * size + x] = 1
+      }
+    }
+  }
+
+  return {
+    type: MaskType.BINARY,
+    data,
+    w: size,
+    h: size,
+    radius,
+    size,
+    minOffset,
+  }
+}

package/src/Mask/applyBinaryMaskToAlphaMask.ts

@@ -2,9 +2,7 @@ import type { AlphaMask, ApplyMaskToPixelDataOptions, BinaryMask } from '../_typ
 
 export function applyBinaryMaskToAlphaMask(
   alphaMaskDst: AlphaMask,
-  dstWidth: number,
   binaryMaskSrc: BinaryMask,
-  srcWidth: number,
   opts: ApplyMaskToPixelDataOptions = {},
 ): void {
   const {
@@ -17,12 +15,14 @@ export function applyBinaryMaskToAlphaMask(
     invertMask = false,
   } = opts
 
+  const dstWidth = alphaMaskDst.w
   if (dstWidth <= 0) return
-  if (binaryMaskSrc.length === 0) return
+  if (binaryMaskSrc.data.length === 0) return
+  const srcWidth = binaryMaskSrc.w
   if (srcWidth <= 0) return
 
-  const dstHeight = (alphaMaskDst.length / dstWidth) | 0
-  const srcHeight = (binaryMaskSrc.length / srcWidth) | 0
+  const dstHeight = (alphaMaskDst.data.length / dstWidth) | 0
+  const srcHeight = (binaryMaskSrc.data.length / srcWidth) | 0
 
   if (dstHeight <= 0) return
   if (srcHeight <= 0) return
@@ -46,6 +46,9 @@ export function applyBinaryMaskToAlphaMask(
   const iterW = Math.min(dstX1 - dstX0, srcWidth - srcX0)
   const iterH = Math.min(dstY1 - dstY0, srcHeight - srcY0)
 
+  const srcData = binaryMaskSrc.data
+  const dstData = alphaMaskDst.data
+
   let dstIdx = dstY0 * dstWidth + dstX0
   let srcIdx = srcY0 * srcWidth + srcX0
 
@@ -57,8 +60,8 @@ export function applyBinaryMaskToAlphaMask(
 
       while (d < dstEnd) {
         // inverted
-        if (binaryMaskSrc[s] !== 0) {
-          alphaMaskDst[d] = 0
+        if (srcData[s] !== 0) {
+          dstData[d] = 0
         }
         d++
         s++
@@ -75,8 +78,8 @@ export function applyBinaryMaskToAlphaMask(
 
       while (d < dstEnd) {
         // If binary mask is empty, clear the alpha pixel.
-        if (binaryMaskSrc[s] === 0) {
-          alphaMaskDst[d] = 0
+        if (srcData[s] === 0) {
+          dstData[d] = 0
         }
         d++
         s++

package/src/Mask/copyMask.ts

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

package/src/Mask/extractMask.ts

@@ -1,45 +1,41 @@
-import type { Rect } from '../_types'
+import { type Mask, 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 mask - 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.
+ * @param mask - The target mask.
+ * @param rect - A rect defining the region to extract.
+ * @returns A new mask containing the extracted region.
  */
-export function extractMask(
-  mask: Uint8Array,
-  maskWidth: number,
+export function extractMask<T extends Mask>(
+  mask: T,
   rect: Rect,
-): Uint8Array
+): T
+
 /**
- * @param mask - The source 1D array representing the full 2D mask.
- * @param maskWidth - The width of the original source mask (stride).
+ * @param mask - The target mask.
  * @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 extractMask(
-  mask: Uint8Array,
-  maskWidth: number,
+export function extractMask<T extends Mask>(
+  mask: T,
   x: number,
   y: number,
   w: number,
   h: number,
-): Uint8Array
-export function extractMask(
-  mask: Uint8Array,
-  maskWidth: number,
+): T
+export function extractMask<T extends Mask>(
+  mask: T,
   xOrRect: number | Rect,
   y?: number,
   w?: number,
   h?: number,
-): Uint8Array {
+): T {
   let finalX: number
   let finalY: number
   let finalW: number
@@ -57,28 +53,34 @@ export function extractMask(
     finalH = h!
   }
 
-  const out = new Uint8Array(finalW * finalH)
-  const srcH = mask.length / maskWidth
+  const out = {
+    type: mask.type,
+    w: finalW,
+    h: finalH,
+    data: new Uint8Array(finalW * finalH),
+  } as T
+
+  // Calculate the total height of the source mask based on the buffer size
+  const srcH = mask.h
+  const stride = mask.w
 
   for (let row = 0; row < finalH; row++) {
     const currentSrcY = finalY + row
 
-    if (currentSrcY < 0 || currentSrcY >= srcH) {
-      continue
-    }
+    // Safety Check: If the requested row is outside the source mask, skip it (leave as 0)
+    if (currentSrcY < 0 || currentSrcY >= srcH) continue
 
+    // Calculate valid horizontal range within the source stride
+    // We only copy if srcX is within the actual bounds of the source width
     const start = Math.max(0, finalX)
-    const end = Math.min(maskWidth, finalX + finalW)
+    const end = Math.min(stride, finalX + finalW)
 
     if (start < end) {
-      const srcOffset = currentSrcY * maskWidth + start
-      const dstOffset = (row * finalW) + (start - finalX)
+      const srcOffset = currentSrcY * stride + start
+      const dstOffset = row * finalW + (start - finalX)
       const count = end - start
 
-      out.set(
-        mask.subarray(srcOffset, srcOffset + count),
-        dstOffset,
-      )
+      out.data.set(mask.data.subarray(srcOffset, srcOffset + count), dstOffset)
     }
   }