pixel-data-js 0.3.0 → 0.5.0

package/src/ImageData/{writeImageData.ts → writeImageDataPixels.ts}

@@ -1,11 +1,30 @@
 import type { Rect } from '../_types'
 
-export function writeImageData(
+/**
+ * Copies a pixel buffer into a specific region of an {@link ImageData} object.
+ *
+ * This function performs a direct memory copy from a {@link Uint8ClampedArray}
+ * 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 data - The source pixel data (RGBA).
+ * @param rect - A {@link Rect} object defining the destination region.
+ */
+export function writeImageDataPixels(
   imageData: ImageData,
   data: Uint8ClampedArray,
   rect: Rect,
 ): void
-export function writeImageData(
+/**
+ * @param imageData - The target {@link ImageData} 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.
+ * @param w - The width of the region to write.
+ * @param h - The height of the region to write.
+ */
+export function writeImageDataPixels(
   imageData: ImageData,
   data: Uint8ClampedArray,
   x: number,
@@ -13,7 +32,7 @@ export function writeImageData(
   w: number,
   h: number,
 ): void
-export function writeImageData(
+export function writeImageDataPixels(
   imageData: ImageData,
   data: Uint8ClampedArray,
   _x: Rect | number,

package/src/Input/fileInputChangeToImageData.ts

@@ -0,0 +1,37 @@
+import { fileToImageData } from '../../src'
+
+/**
+ * A convenience wrapper that extracts the first {@link File} from an
+ * {@link HTMLInputElement} change event and converts it into {@link ImageData}.
+ *
+ * This function handles the boilerplate of accessing the file list and checking
+ * for existence. It is ideal for use directly in an `onchange` event listener.
+ *
+ * @param event - The change {@link Event} from an `<input type="file">` element.
+ *
+ * @returns A promise that resolves to {@link ImageData} if a file was successfully
+ * processed, or `null` if no file was selected or the input was cleared.
+ *
+ * @example
+ * ```typescript
+ * const input = document.querySelector('input[type="file"]');
+ *
+ * input.addEventListener('change', async (event) => {
+ *   const imageData = await fileInputChangeToImageData(event);
+ *
+ *   if (imageData) {
+ *     console.log('Image loaded:', imageData.width, imageData.height);
+ *   }
+ * });
+ * ```
+ */
+export async function fileInputChangeToImageData(
+  event: Event,
+): Promise<ImageData | null> {
+  const target = event.target as HTMLInputElement
+
+  const file = target.files?.[0]
+  if (!file) return null
+
+  return await fileToImageData(file)
+}

package/src/Input/fileToImageData.ts

@@ -0,0 +1,75 @@
+import { OFFSCREEN_CANVAS_CTX_FAILED } from '../Canvas/_constants'
+
+/**
+ * Thrown when the user provides a file that isn't an image.
+ */
+export class UnsupportedFormatError extends Error {
+  constructor(mimeType: string) {
+    super(`File type ${mimeType} is not a supported image format.`)
+    this.name = 'UnsupportedFormatError'
+  }
+}
+
+/**
+ * Converts a browser {@link File} object into {@link ImageData}.
+ * This utility handles the full pipeline of image decoding using hardware-accelerated
+ * APIs {@link createImageBitmap} and {@link OffscreenCanvas}. It ensures that underlying
+ * resources like `ImageBitmap` are properly closed even if the conversion fails.
+ *
+ * @param file - The image file to convert. Can be null or undefined.
+ * @returns A `Promise` resolving to the pixel data as {@link ImageData},
+ * or `null` if no file was provided.
+ * @throws {@link UnsupportedFormatError}
+ * Thrown if the provided file's MIME type does not start with `image/`.
+ * @example
+ * ```typescript
+ * try {
+ *   const imageData = await fileToImageData(file);
+ *   if (imageData) {
+ *     console.log('Pixels:', imageData.data);
+ *   }
+ * } catch (err) {
+ *   if (err instanceof UnsupportedFormatError) {
+ *     // Handle bad file type
+ *   }
+ * }
+ * ```
+ */
+export async function fileToImageData(
+  file: File | null | undefined,
+): Promise<ImageData | null> {
+  if (!file) return null
+
+  if (!file.type.startsWith('image/')) {
+    throw new UnsupportedFormatError(file.type)
+  }
+
+  let bitmap: ImageBitmap | null = null
+
+  try {
+    bitmap = await createImageBitmap(file)
+
+    const canvas = new OffscreenCanvas(
+      bitmap.width,
+      bitmap.height,
+    )
+
+    const ctx = canvas.getContext('2d')
+    if (!ctx) throw new Error(OFFSCREEN_CANVAS_CTX_FAILED)
+
+    ctx.drawImage(
+      bitmap,
+      0,
+      0,
+    )
+
+    return ctx.getImageData(
+      0,
+      0,
+      bitmap.width,
+      bitmap.height,
+    )
+  } finally {
+    bitmap?.close()
+  }
+}

package/src/Input/getSupportedRasterFormats.ts

@@ -0,0 +1,74 @@
+// Cache the Promise to prevent race conditions during initialization
+let formatsPromise: Promise<string[]> | null = null
+
+const defaultRasterMimes = [
+  'image/png',
+  'image/jpeg',
+  'image/webp',
+  'image/avif',
+  'image/gif',
+  'image/bmp',
+]
+
+/**
+ * Probes the browser environment to determine which image MIME types are
+ * supported for pixel-level operations.
+ * This function performs a one-time check by attempting to convert a
+ * {@link OffscreenCanvas} to MIME types. The result is
+ * cached to prevent redundant hardware-accelerated operations on
+ * subsequent calls.
+ * @param rasterMimes List of MIME types to check
+ * @default ['image/png',
+ *   'image/jpeg',
+ *   'image/webp',
+ *   'image/avif',
+ *   'image/gif',
+ *   'image/bmp']
+ * @returns A `Promise` resolving to an array of supported MIME
+ * types from the `rasterMimes` list.
+ * @throws {Error} If the {@link OffscreenCanvas} context cannot be initialized.
+ * @example
+ * ```typescript
+ * const supported = await getSupportedPixelFormats();
+ * if (supported.includes('image/avif')) {
+ *   console.log('High-efficiency formats available');
+ * }
+ * ```
+ */
+export async function getSupportedPixelFormats(rasterMimes = defaultRasterMimes): Promise<string[]> {
+  if (formatsPromise) {
+    return formatsPromise
+  }
+
+  const probeCanvas = async () => {
+    const canvas = new OffscreenCanvas(1, 1)
+
+    const results = await Promise.all(
+      rasterMimes.map(async (mime) => {
+        try {
+          const blob = await canvas.convertToBlob({
+            type: mime,
+          })
+
+          return blob.type === mime ? mime : null
+        } catch {
+          return null
+        }
+      }),
+    )
+
+    return results.filter((type): type is string => {
+      return type !== null
+    })
+  }
+
+  // By chaining .catch here, the microtask guarantees formatsPromise
+  // is assigned the promise BEFORE the catch block runs to reset it.
+  formatsPromise = probeCanvas().catch((error) => {
+    formatsPromise = null
+
+    throw error
+  })
+
+  return formatsPromise
+}

package/src/Mask/extractMask.ts

@@ -0,0 +1,86 @@
+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 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.
+ */
+export function extractMask(
+  mask: Uint8Array,
+  maskWidth: number,
+  rect: Rect,
+): Uint8Array
+/**
+ * @param mask - 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 extractMask(
+  mask: Uint8Array,
+  maskWidth: number,
+  x: number,
+  y: number,
+  w: number,
+  h: number,
+): Uint8Array
+export function extractMask(
+  mask: 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 = mask.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(
+        mask.subarray(srcOffset, srcOffset + count),
+        dstOffset,
+      )
+    }
+  }
+
+  return out
+}

package/src/Mask/mergeMasks.ts

@@ -1,9 +1,4 @@
-import {
-  type AnyMask,
-  type AlphaMask,
-  type ApplyMaskOptions,
-  MaskType,
-} from '../_types'
+import { type AlphaMask, type AnyMask, type ApplyMaskOptions, MaskType } from '../_types'
 
 /**
  * Merges a source mask into a destination AlphaMask.

package/src/PixelData/blendColorPixelData.ts

@@ -82,16 +82,16 @@ export function blendColorPixelData(
         const mVal = mask[mIdx]
 
         if (isAlphaMask) {
-        const effectiveM = invertMask
-          ? 255 - mVal
-          : mVal
+          const effectiveM = invertMask
+            ? 255 - mVal
+            : mVal
 
-        // If mask is transparent, skip
-        if (effectiveM === 0) {
-          dIdx++
-          mIdx++
-          continue
-        }
+          // If mask is transparent, skip
+          if (effectiveM === 0) {
+            dIdx++
+            mIdx++
+            continue
+          }
 
           // globalAlpha is not a factor
           if (globalAlpha === 255) {

package/src/PixelData/fillPixelData.ts

@@ -2,24 +2,63 @@ import type { Color32, Rect } from '../_types'
 import type { PixelData } from '../PixelData'
 
 /**
- * A high-performance solid fill for PixelData.
+ * Fills a region or the {@link PixelData} buffer with a solid color.
+ *
+ * @param dst - The target {@link PixelData} to modify.
+ * @param color - The {@link Color32} value to apply.
+ * @param rect - A {@link Rect} defining the area to fill. If omitted, the entire
+ * buffer is filled.
  */
 export function fillPixelData(
   dst: PixelData,
   color: Color32,
   rect?: Partial<Rect>,
+): void
+/**
+ * @param dst - The target {@link PixelData} to modify.
+ * @param color - The {@link Color32} value to apply.
+ * @param x - Starting horizontal coordinate.
+ * @param y - Starting vertical coordinate.
+ * @param w - Width of the fill area.
+ * @param h - Height of the fill area.
+ */
+export function fillPixelData(
+  dst: PixelData,
+  color: Color32,
+  x: number,
+  y: number,
+  w: number,
+  h: number,
+): void
+export function fillPixelData(
+  dst: PixelData,
+  color: Color32,
+  _x?: Partial<Rect> | number,
+  _y?: number,
+  _w?: number,
+  _h?: number,
 ): void {
-  const {
-    x: targetX = 0,
-    y: targetY = 0,
-    w: width = dst.width,
-    h: height = dst.height,
-  } = rect || {}
-
-  let x = targetX
-  let y = targetY
-  let w = width
-  let h = height
+  let x: number
+  let y: number
+  let w: number
+  let h: number
+
+  if (typeof _x === 'object') {
+    x = _x.x ?? 0
+    y = _x.y ?? 0
+    w = _x.w ?? dst.width
+    h = _x.h ?? dst.height
+  } else if (typeof _x === 'number') {
+    x = _x
+    y = _y!
+    w = _w!
+    h = _h!
+  } else {
+    x = 0
+    y = 0
+    w = dst.width
+    h = dst.height
+  }
 
   // Destination Clipping
   if (x < 0) {

package/src/PixelData/invertPixelData.ts

@@ -0,0 +1,16 @@
+import type { PixelData } from '../PixelData'
+
+export function invertPixelData(
+  pixelData: PixelData,
+): PixelData {
+
+  const data32 = pixelData.data32
+  const len = data32.length
+
+  for (let i = 0; i < len; i++) {
+    // XOR with 0x00FFFFFF flips RGB bits and ignores Alpha (the top 8 bits)
+    data32[i] = data32[i] ^ 0x00FFFFFF
+  }
+
+  return pixelData
+}

package/src/PixelData/pixelDataToAlphaMask.ts

@@ -0,0 +1,28 @@
+import type { AlphaMask } from '../_types'
+import type { PixelData } from '../PixelData'
+
+/**
+ * Extracts the alpha channel from PixelData into a single-channel mask.
+ * Returns a Uint8Array branded as AlphaMask.
+ */
+export function pixelDataToAlphaMask(
+  pixelData: PixelData,
+): AlphaMask {
+  const {
+    data32,
+    width,
+    height,
+  } = pixelData
+  const len = data32.length
+  const mask = new Uint8Array(width * height) as AlphaMask
+
+  for (let i = 0; i < len; i++) {
+    const val = data32[i]
+
+    // Extract the Alpha byte (top 8 bits in ABGR / Little-Endian)
+    // Shift right by 24 moves the 4th byte to the 1st position
+    mask[i] = (val >>> 24) & 0xff
+  }
+
+  return mask
+}

package/src/Rect/trimRectBounds.ts

@@ -0,0 +1,118 @@
+import type { Rect, SelectionRect } from '../_types'
+import { extractMask } from '../Mask/extractMask'
+
+/**
+ * Intersects a target rectangle with a boundary, trimming dimensions and masks in-place.
+ * This utility calculates the axis-aligned intersection between the `target` and `bounds`.
+ * If the `target` includes a `mask` (as in a {@link SelectionRect}), the mask is physically
+ * cropped and re-aligned using `extractMask` to match the new dimensions.
+ * @param target - The rectangle or selection object to be trimmed. **Note:** This object is mutated in-place.
+ * @param bounds - The boundary rectangle defining the maximum allowable area (e.g., canvas dimensions).
+ * @example
+ * const selection = { x: -10, y: -10, w: 50, h: 50, mask: new Uint8Array(2500) };
+ * const canvas = { x: 0, y: 0, w: 100, h: 100 };
+ * // Selection will be moved to (0,0) and resized to 40x40.
+ * // The mask is cropped by 10 px on the top and left.
+ * trimRectBounds(selection, canvas);
+ */
+export function trimRectBounds<T extends Rect | SelectionRect>(
+  target: T,
+  bounds: Rect,
+): void {
+  const originalX = target.x
+  const originalY = target.y
+  const originalW = target.w
+
+  const intersectedX = Math.max(target.x, bounds.x)
+  const intersectedY = Math.max(target.y, bounds.y)
+
+  const intersectedMaxX = Math.min(
+    target.x + target.w,
+    bounds.x + bounds.w,
+  )
+  const intersectedMaxY = Math.min(
+    target.y + target.h,
+    bounds.y + bounds.h,
+  )
+
+  // Intersection check
+  if (intersectedMaxX <= intersectedX || intersectedMaxY <= intersectedY) {
+    target.w = 0
+    target.h = 0
+
+    if ('mask' in target && target.mask) {
+      // This line is now hit by the 'empty intersection' test below
+      target.mask = new Uint8Array(0)
+    }
+
+    return
+  }
+
+  const intersectedW = intersectedMaxX - intersectedX
+  const intersectedH = intersectedMaxY - intersectedY
+  const offsetX = intersectedX - originalX
+  const offsetY = intersectedY - originalY
+
+  target.x = intersectedX
+  target.y = intersectedY
+  target.w = intersectedW
+  target.h = intersectedH
+
+  if ('mask' in target && target.mask) {
+    const currentMask = extractMask(
+      target.mask,
+      originalW,
+      offsetX,
+      offsetY,
+      intersectedW,
+      intersectedH,
+    )
+
+    let minX = intersectedW
+    let maxX = -1
+    let minY = intersectedH
+    let maxY = -1
+
+    // Scan for content
+    for (let y = 0; y < intersectedH; y++) {
+      for (let x = 0; x < intersectedW; x++) {
+        if (currentMask[y * intersectedW + x] !== 0) {
+          if (x < minX) minX = x
+          if (x > maxX) maxX = x
+          if (y < minY) minY = y
+          if (y > maxY) maxY = y
+        }
+      }
+    }
+
+    // If no content is found (all zeros)
+    if (maxX === -1) {
+      target.w = 0
+      target.h = 0
+      // This covers the specific line you mentioned
+      target.mask = new Uint8Array(0)
+      return
+    }
+
+    const finalW = maxX - minX + 1
+    const finalH = maxY - minY + 1
+
+    // Only shift and crop if the content is smaller than the intersection
+    if (finalW !== intersectedW || finalH !== intersectedH) {
+      target.mask = extractMask(
+        currentMask,
+        intersectedW,
+        minX,
+        minY,
+        finalW,
+        finalH,
+      )
+      target.x += minX
+      target.y += minY
+      target.w = finalW
+      target.h = finalH
+    } else {
+      target.mask = currentMask
+    }
+  }
+}