⚠️ 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

``bash
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.