pixel-data-js 0.3.0 → 0.5.0

package/src/Algorithm/floodFillSelection.ts

@@ -0,0 +1,229 @@
+import { type Color32, type ImageDataLike, MaskType, type Rect, type SelectionRect } from '../_types'
+import { colorDistance } from '../color'
+import { extractImageDataPixels } from '../ImageData/extractImageDataPixels'
+import type { PixelData } from '../PixelData'
+import { trimRectBounds } from '../Rect/trimRectBounds'
+
+export type FloodFillImageDataOptions = {
+  contiguous?: boolean
+  tolerance?: number
+  bounds?: Rect
+}
+
+export type FloodFillResult = {
+  startX: number
+  startY: number
+  selectionRect: SelectionRect
+  pixels: Uint8ClampedArray
+}
+
+/**
+ * Performs a color-based flood fill selection on {@link ImageData} or {@link PixelData}.
+ * This utility identifies pixels starting from a specific coordinate that fall within a
+ * color tolerance. It can operate in "contiguous" mode (classic bucket fill) or
+ * "non-contiguous" mode (selects all matching pixels in the buffer).
+ *
+ * @param img - The source image data to process.
+ * @param startX - The starting horizontal coordinate.
+ * @param startY - The starting vertical coordinate.
+ * @param options - Configuration for the fill operation.
+ * @param options.contiguous - @default true. If true, only connected pixels are
+ * selected. If false, all pixels within tolerance are selected regardless of position.
+ * @param options.tolerance - @default 0. The maximum allowed difference in color
+ * distance (0-255) for a pixel to be included.
+ * @param options.bounds - Optional bounding box to restrict the search area.
+ *
+ * @returns A {@link FloodFillResult} containing the mask and bounds of the selection,
+ * or `null` if the starting coordinates are out of bounds.
+ *
+ * @example
+ * ```typescript
+ * const result = floodFillImageDataSelection(
+ * ctx.getImageData(0, 0, 100, 100),
+ * 50,
+ * 50,
+ * {
+ * tolerance: 20,
+ * contiguous: true
+ * }
+ * );
+ * ```
+ */
+export function floodFillSelection(
+  img: ImageDataLike | PixelData,
+  startX: number,
+  startY: number,
+  {
+    contiguous = true,
+    tolerance = 0,
+    bounds,
+  }: FloodFillImageDataOptions = {},
+): FloodFillResult | null {
+
+  let imageData: ImageDataLike
+  let data32: Uint32Array
+  if ('data32' in img) {
+    data32 = img.data32
+    imageData = img.imageData
+  } else {
+    data32 = new Uint32Array(
+      img.data.buffer,
+      img.data.byteOffset,
+      img.data.byteLength >> 2,
+    )
+    imageData = img
+  }
+  const {
+    width,
+    height,
+  } = img
+
+  const limit = bounds || {
+    x: 0,
+    y: 0,
+    w: width,
+    h: height,
+  }
+
+  const xMin = Math.max(0, limit.x)
+  const xMax = Math.min(width - 1, limit.x + limit.w - 1)
+  const yMin = Math.max(0, limit.y)
+  const yMax = Math.min(height - 1, limit.y + limit.h - 1)
+
+  if (startX < xMin || startX > xMax || startY < yMin || startY > yMax) {
+    return null
+  }
+
+  const baseColor = data32[startY * width + startX] as Color32
+
+  let matchCount = 0
+  const matchX = new Uint16Array(width * height)
+  const matchY = new Uint16Array(width * height)
+
+  let minX = startX
+  let maxX = startX
+  let minY = startY
+  let maxY = startY
+
+  if (contiguous) {
+    const visited = new Uint8Array(width * height)
+    const stack = new Uint32Array(width * height)
+    let stackPtr = 0
+
+    stack[stackPtr++] = (startY << 16) | startX
+    visited[startY * width + startX] = 1
+
+    while (stackPtr > 0) {
+      const val = stack[--stackPtr]
+      const x = val & 0xFFFF
+      const y = val >>> 16
+
+      matchX[matchCount] = x
+      matchY[matchCount] = y
+      matchCount++
+
+      if (x < minX) minX = x
+      if (x > maxX) maxX = x
+      if (y < minY) minY = y
+      if (y > maxY) maxY = y
+
+      // Right
+      if (x + 1 <= xMax) {
+        const idx = y * width + (x + 1)
+        if (!visited[idx] && colorDistance(data32[idx] as Color32, baseColor) <= tolerance) {
+          visited[idx] = 1
+          stack[stackPtr++] = (y << 16) | (x + 1)
+        }
+      }
+      // Left
+      if (x - 1 >= xMin) {
+        const idx = y * width + (x - 1)
+        if (!visited[idx] && colorDistance(data32[idx] as Color32, baseColor) <= tolerance) {
+          visited[idx] = 1
+          stack[stackPtr++] = (y << 16) | (x - 1)
+        }
+      }
+      // Down
+      if (y + 1 <= yMax) {
+        const idx = (y + 1) * width + x
+        if (!visited[idx] && colorDistance(data32[idx] as Color32, baseColor) <= tolerance) {
+          visited[idx] = 1
+          stack[stackPtr++] = ((y + 1) << 16) | x
+        }
+      }
+      // Up
+      if (y - 1 >= yMin) {
+        const idx = (y - 1) * width + x
+        if (!visited[idx] && colorDistance(data32[idx] as Color32, baseColor) <= tolerance) {
+          visited[idx] = 1
+          stack[stackPtr++] = ((y - 1) << 16) | x
+        }
+      }
+    }
+  } else {
+    for (let y = yMin; y <= yMax; y++) {
+      for (let x = xMin; x <= xMax; x++) {
+        const color = data32[y * width + x] as Color32
+        if (colorDistance(color, baseColor) <= tolerance) {
+          matchX[matchCount] = x
+          matchY[matchCount] = y
+          matchCount++
+
+          if (x < minX) minX = x
+          if (x > maxX) maxX = x
+          if (y < minY) minY = y
+          if (y > maxY) maxY = y
+        }
+      }
+    }
+  }
+
+  if (matchCount === 0) {
+    return null
+  }
+  const selectionRect: SelectionRect = {
+    x: minX,
+    y: minY,
+    w: maxX - minX + 1,
+    h: maxY - minY + 1,
+    mask: new Uint8Array((maxX - minX + 1) * (maxY - minY + 1)),
+    maskType: MaskType.BINARY,
+  }
+
+  // REMOVED trimRectBounds from here
+
+  const sw = selectionRect.w
+  const sh = selectionRect.h
+  const finalMask = selectionRect.mask!
+
+  for (let i = 0; i < matchCount; i++) {
+    const mx = matchX[i] - selectionRect.x
+    const my = matchY[i] - selectionRect.y
+
+    if (mx >= 0 && mx < sw && my >= 0 && my < sh) {
+      finalMask[my * sw + mx] = 1
+    }
+  }
+
+  // trimRectBounds can see them and work correctly.
+  trimRectBounds(
+    selectionRect,
+    { x: 0, y: 0, w: width, h: height },
+  )
+
+  // Use the UPDATED values from the selectionRect after trimming
+  const extracted = extractImageDataPixels(
+    imageData,
+    selectionRect.x,
+    selectionRect.y,
+    selectionRect.w,
+    selectionRect.h,
+  )
+
+  return {
+    startX,
+    startY,
+    selectionRect,
+    pixels: extracted,
+  }
+}

package/src/Canvas/PixelCanvas.ts

@@ -0,0 +1,31 @@
+import { CANVAS_CTX_FAILED } from './_constants'
+
+export type PixelCanvas = {
+  readonly canvas: HTMLCanvasElement,
+  readonly ctx: CanvasRenderingContext2D,
+  readonly resize: (w: number, h: number) => void
+}
+
+/**
+ * Ensures the canvas ctx is always set to imageSmoothingEnabled = false.
+ * Intended for canvas elements that are already part of the DOM.
+ * @see makeReusableCanvas
+ * @throws {Error} If the {@link HTMLCanvasElement} context cannot be initialized.
+ */
+export function makePixelCanvas(
+  canvas: HTMLCanvasElement,
+): PixelCanvas {
+  const ctx = canvas.getContext('2d')
+  if (!ctx) throw new Error(CANVAS_CTX_FAILED)
+  ctx.imageSmoothingEnabled = false
+
+  return {
+    canvas,
+    ctx,
+    resize(w: number, h: number) {
+      canvas.width = w
+      canvas.height = h
+      ctx.imageSmoothingEnabled = false
+    },
+  }
+}

package/src/Canvas/ReusableCanvas.ts

@@ -0,0 +1,44 @@
+import { CANVAS_CTX_FAILED } from './_constants'
+
+export type ReusableCanvas = {
+  readonly canvas: HTMLCanvasElement
+  readonly ctx: CanvasRenderingContext2D
+}
+
+/**
+ * Creates a reusable canvas and context that are not part of the DOM.
+ * Ensures it is always set to `context.imageSmoothingEnabled = false`
+ * @see makePixelCanvas
+ * @throws {Error} If the {@link HTMLCanvasElement} context cannot be initialized.
+ */
+export function makeReusableCanvas() {
+  let canvas: HTMLCanvasElement | null = null
+  let ctx: CanvasRenderingContext2D | null = null
+
+  function get(width: number, height: number): ReusableCanvas {
+    if (canvas === null) {
+      canvas = document.createElement('canvas')!
+      ctx = canvas.getContext('2d')!
+      if (!ctx) throw new Error(CANVAS_CTX_FAILED)
+    }
+
+    // Resize if needed (resizing auto-clears)
+    if (canvas.width !== width || canvas.height !== height) {
+      canvas.width = width
+      canvas.height = height
+      ctx!.imageSmoothingEnabled = false
+    } else {
+      // Same size → manually clear
+      ctx!.clearRect(0, 0, width, height)
+    }
+
+    return { canvas, ctx: ctx! }
+  }
+
+  get.reset = () => {
+    canvas = null
+    ctx = null
+  }
+
+  return get
+}

package/src/Canvas/_constants.ts

@@ -0,0 +1,2 @@
+export const OFFSCREEN_CANVAS_CTX_FAILED = 'Failed to create OffscreenCanvas context'
+export const CANVAS_CTX_FAILED = 'Failed to create Canvas context'

package/src/Clipboard/getImageDataFromClipboard.ts

@@ -0,0 +1,42 @@
+import { imgBlobToImageData } from '../ImageData/imgBlobToImageData'
+
+/**
+ * Extracts {@link ImageData} from a clipboard event if an image is present.
+ *
+ * This function iterates through the {@link DataTransferItemList} to find
+ * the first item with an image MIME type and decodes it.
+ *
+ * @param clipboardEvent - The event object from a `paste` listener.
+ *
+ * @returns A promise resolving to {@link ImageData}, or `null` if no
+ * image was found in the clipboard.
+ *
+ * @example
+ * ```typescript
+ * window.addEventListener('paste', async (event) => {
+ *   const data = await getImageDataFromClipboard(event)
+ *   if (data) {
+ *     console.log('Pasted image dimensions:', data.width, data.height)
+ *   }
+ * });
+ * ```
+ */
+export async function getImageDataFromClipboard(clipboardEvent: ClipboardEvent) {
+  const items = clipboardEvent?.clipboardData?.items
+  if (!items?.length) return null
+
+  for (let i = 0; i < items.length; i++) {
+    const item = items[i]
+
+    if (item.type.startsWith('image/')) {
+      const blob = item.getAsFile()
+
+      if (!blob) {
+        continue
+      }
+
+      return imgBlobToImageData(blob)
+    }
+  }
+  return null
+}

package/src/Clipboard/writeImageDataToClipboard.ts

@@ -0,0 +1,25 @@
+import { imageDataToImgBlob } from '../ImageData/imageDataToImgBlob'
+import { writeImgBlobToClipboard } from './writeImgBlobToClipboard'
+
+/**
+ * Converts {@link ImageData} to a PNG {@link Blob} and writes it to the system clipboard.
+ * This is a high-level utility that combines {@link imageDataToImgBlob} and
+ * {@link writeImgBlobToClipboard}.
+ * @param imageData - The image data to copy to the clipboard.
+ * @returns A promise that resolves when the image has been successfully copied.
+ * @throws {Error}
+ * If the conversion to blob fails or clipboard permissions are denied.
+ *
+ * @example
+ * ```typescript
+ * const canvas = document.querySelector('canvas')
+ * const ctx = canvas.getContext('2d')
+ * const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height)
+ * await writeImageDataToClipboard(imageData)
+ * ```
+ */
+export async function writeImageDataToClipboard(imageData: ImageData): Promise<void> {
+  const blob = await imageDataToImgBlob(imageData)
+
+  return writeImgBlobToClipboard(blob)
+}

package/src/Clipboard/writeImgBlobToClipboard.ts

@@ -0,0 +1,13 @@
+/**
+ * Writes a {@link Blob} image to the system clipboard.
+ *
+ * @param blob - The image {@link Blob} (typically `image/png`) to copy.
+ * @returns A promise that resolves when the clipboard has been updated.
+ */
+export async function writeImgBlobToClipboard(blob: Blob): Promise<void> {
+  const item = new ClipboardItem({
+    'image/png': blob,
+  })
+
+  await navigator.clipboard.write([item])
+}

package/src/ImageData/{extractImageData.ts → extractImageDataPixels.ts}

@@ -1,17 +1,35 @@
 import type { ImageDataLike, Rect } from '../_types'
 
-export function extractImageData(
+/**
+ * Extracts a specific rectangular region of pixels from a larger {@link ImageDataLike}
+ * source into a new {@link Uint8ClampedArray}.
+ *
+ * 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.
+ */
+export function extractImageDataPixels(
   imageData: ImageDataLike,
   rect: Rect,
 ): Uint8ClampedArray
-export function extractImageData(
+/**
+ * @param imageData - The source image data to read from.
+ * @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 {@link Uint8ClampedArray} containing the RGBA pixel data of the region.
+ */
+export function extractImageDataPixels(
   imageData: ImageDataLike,
   x: number,
   y: number,
   w: number,
   h: number,
 ): Uint8ClampedArray
-export function extractImageData(
+export function extractImageDataPixels(
   imageData: ImageDataLike,
   _x: Rect | number,
   _y?: number,

package/src/ImageData/imageDataToAlphaMask.ts

@@ -0,0 +1,35 @@
+import type { AlphaMask } from '../_types'
+import { pixelDataToAlphaMask } from '../PixelData/pixelDataToAlphaMask'
+
+/**
+ * Extracts the alpha channel from raw ImageData into an AlphaMask.
+ * When possible use {@link pixelDataToAlphaMask} instead.
+ * Repeat calls to the same data will use less memory.
+ */
+export function imageDataToAlphaMask(
+  imageData: ImageData,
+): AlphaMask {
+  const {
+    width,
+    height,
+    data,
+  } = imageData
+
+  // Create a 32-bit view of the existing buffer
+  const data32 = new Uint32Array(
+    data.buffer,
+    data.byteOffset,
+    data.byteLength >> 2,
+  )
+  const len = data32.length
+  const mask = new Uint8Array(width * height) as AlphaMask
+
+  for (let i = 0; i < len; i++) {
+    const val = data32[i]
+
+    // Extract Alpha (top 8 bits in Little-Endian/ABGR)
+    mask[i] = (val >>> 24) & 0xff
+  }
+
+  return mask
+}

package/src/ImageData/imageDataToDataUrl.ts

@@ -0,0 +1,27 @@
+import { makeReusableCanvas } from '../Canvas/ReusableCanvas'
+
+const get = makeReusableCanvas()
+
+/**
+ * Converts an {@link ImageData} object into a base64-encoded Data URL string.
+ *
+ * @param imageData - The pixel data to be converted.
+ *
+ * @returns A string representing the image in `image/png` format as a
+ * [Data URL](https://developer.mozilla.org/en-US/docs/Web/URI/Reference/Schemes/data).
+ * @throws {Error} If the {@link HTMLCanvasElement} context cannot be initialized.
+ * @example
+ * ```typescript
+ * const dataUrl = imageDataToDataUrl(imageData);
+ * const img = new Image();
+ * img.src = dataUrl;
+ * ```
+ */
+export function imageDataToDataUrl(imageData: ImageData): string {
+  const { canvas, ctx } = get(imageData.width, imageData.height)
+
+  ctx.putImageData(imageData, 0, 0)
+  return canvas.toDataURL()
+}
+
+imageDataToDataUrl.reset = get.reset

package/src/ImageData/imageDataToImgBlob.ts

@@ -0,0 +1,31 @@
+/**
+ * Converts an {@link ImageData} object into a {@link Blob} in PNG format.
+ *
+ * This operation is asynchronous and uses {@link OffscreenCanvas}
+ * to perform the encoding, making it suitable for usage in both the main
+ * thread and Web Workers.
+ *
+ * @param imageData - The pixel data to be encoded.
+ *
+ * @returns A promise that resolves to a {@link Blob} with the MIME type `image/png`.
+ *
+ * @throws {Error}
+ * Thrown if the {@link OffscreenCanvas} context cannot be initialized or the blob
+ * encoding fails.
+ *
+ * @example
+ * ```typescript
+ * const blob = await imageDataToImgBlob(imageData);
+ * const url = URL.createObjectURL(blob);
+ * ```
+ */
+export async function imageDataToImgBlob(imageData: ImageData): Promise<Blob> {
+  const canvas = new OffscreenCanvas(imageData.width, imageData.height)
+  const ctx = canvas.getContext('2d')
+  if (!ctx) throw new Error('could not create 2d context')
+
+  ctx.putImageData(imageData, 0, 0)
+  return canvas!.convertToBlob({
+    type: 'image/png',
+  })
+}

package/src/ImageData/imgBlobToImageData.ts

@@ -0,0 +1,52 @@
+/**
+ * Decodes a {@link Blob} (typically PNG) back into an {@link ImageData} object.
+ *
+ * This function uses hardware-accelerated decoding via {@link createImageBitmap}
+ * and processes the data using an {@link OffscreenCanvas} to ensure
+ * compatibility with Web Workers.
+ *
+ * @param blob - The binary image data to decode.
+ *
+ * @returns A promise resolving to the decoded {@link ImageData}.
+ *
+ * @throws {Error}
+ * Thrown if the blob is corrupted or the browser cannot decode the format.
+ *
+ * @example
+ * ```typescript
+ * const blob = await getBlobFromStorage();
+ *
+ * const imageData = await pngBlobToImageData(blob);
+ * ```
+ */
+export async function imgBlobToImageData(
+  blob: Blob,
+): Promise<ImageData> {
+  let bitmap: ImageBitmap | null = null
+
+  try {
+    bitmap = await createImageBitmap(blob)
+
+    const canvas = new OffscreenCanvas(
+      bitmap.width,
+      bitmap.height,
+    )
+
+    const ctx = canvas.getContext('2d')
+
+    if (!ctx) {
+      throw new Error('Failed to get 2D context')
+    }
+
+    ctx.drawImage(bitmap, 0, 0)
+
+    return ctx.getImageData(
+      0,
+      0,
+      bitmap.width,
+      bitmap.height,
+    )
+  } finally {
+    bitmap?.close()
+  }
+}

package/src/ImageData/invertImageData.ts

@@ -0,0 +1,10 @@
+export function invertImageData(imageData: ImageData) {
+  const data = imageData.data
+  let length = data.length
+  for (let i = 0; i < length; i += 4) {
+    data[i] = 255 - data[i]!
+    data[i + 1] = 255 - data[i + 1]!
+    data[i + 2] = 255 - data[i + 2]!
+  }
+  return imageData
+}

package/src/ImageData/resizeImageData.ts

@@ -0,0 +1,75 @@
+/**
+ * Non destructively resizes the {@link ImageData} buffer to new dimensions, optionally
+ * offsetting the original content.
+ * This operation creates a new buffer. It does not scale or stretch pixels;
+ * instead, it crops or pads the image based on the new dimensions and
+ * provides an offset for repositioning.
+ *
+ * @param current The source {@link ImageData} 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.
+ *
+ * @example
+ * ```typescript
+ * // Centers an 80x80 image in a new 100x100 buffer
+ * const resized = resizeImageData(
+ *   originalData,
+ *   100,
+ *   100,
+ *   10,
+ *   10
+ * );
+ * ```
+ */
+export function resizeImageData(
+  current: ImageData,
+  newWidth: number,
+  newHeight: number,
+  offsetX = 0,
+  offsetY = 0,
+): ImageData {
+  const result = new ImageData(newWidth, newHeight)
+  const {
+    width: oldW,
+    height: oldH,
+    data: oldData,
+  } = current
+  const newData = result.data
+
+  // Determine intersection of the old image (at offset) and new canvas bounds
+  const x0 = Math.max(0, offsetX)
+  const y0 = Math.max(0, offsetY)
+  const x1 = Math.min(newWidth, offsetX + oldW)
+  const y1 = Math.min(newHeight, offsetY + oldH)
+
+  if (x1 <= x0 || y1 <= y0) {
+    return result
+  }
+
+  const rowCount = y1 - y0
+  const rowLen = (x1 - x0) * 4
+
+  for (let row = 0; row < rowCount; row++) {
+    const dstY = y0 + row
+    const srcY = dstY - offsetY
+    const srcX = x0 - offsetX
+
+    const dstStart = (dstY * newWidth + x0) * 4
+    const srcStart = (srcY * oldW + srcX) * 4
+
+    newData.set(
+      oldData.subarray(srcStart, srcStart + rowLen),
+      dstStart,
+    )
+  }
+
+  return result
+}