⚠️ This library is currently in beta, so the function signatures are subject to change.

pixel-utils

Minimalist Utility Functions for Pixels

features

• no data values
• optional mutability for fast memory-preserving operations
• optimized for speed
• range flipping
• simple conversion between RGB and RGBA
• support for CommonJS and ES Modules
• typescript

install

npm install pixel-utils

functions

• conversion
  • rawToRgb - convert a raw unprocessed pixel value to RGB
  • rawToRgba - convert a raw unprocessed pixel value to RGBA
  • rgbToRgba - convert from RGB to RGBA
  • rgbaToRgb - convert from RGBA to RGB
• no data
  • makeNoDataRgb - create a no data RGB pixel
  • makeNoDataRgba - create a no data RGB pixel
• iteration
  • eachPixel - call a callback for each pixel
• selection
  • select - select a pixel from image data of arbitrary dimensions
• transparency
  • addAlpha - add an alpha transparency channel
  • isHidden - check if an RGBA pixel is transparent
  • setHidden - mutates input pixel, setting alpha channel to visible
  • showRGBA - make RGBA visible
• and many more

core assumptions and constraints

An RGB pixel has these assumed properties:

• array of 3 numbers between zero and 255
• no data is represented by either black or white

An RGBA pixel has these assumed properties:

• array of 4 numbers between zero and 255
• the first 3 numbers are "data" values and the last value is an alpha tranparency value
• an alpha value of 0 indicates that at least one of the data bands is "no data"
• there may be a per-band no data value, but it is not required

A raw (unscaled) pixel value has these assumed properties:

• between 1 and inifinity number of bands
• number can be any valid number
• no data value must be the same for each band (we don't love this, but it's a common constraint)
• there is no transparency channel/band (we may work to remove this constraint)

comparison

There are several other pixel manipulation libraries, including p5js and fabricjs, however pixel-utils provides some unique features not found in other libraries:

• raw image data support: most (if not all) alternatives assume that an image is a 8-bit 0-255 RGBA data
• arbitrary image layout support: most (if not all) alternatives assume that your data is in a flat Uint8ClampedArray, but pixel-utils support all possible data layouts thanks to the xdmin layout syntax.