Image-pixels NPM

image-pixels

Get pixel data for a given URL, path, buffer, canvas, image or any other source. Intented for image based tests, first of all.

Usage

var pixels = require('image-pixels')

// load single source
var {data, width, height} = await pixels('lena.png')

// load multiple sources in parallel
var [a, b, c] = await pixels.all([
	'./a.jpg',
	{ source: './b.png', cache: false },
	canvas
])

API

`let {data, width, height} = await pixels(source, options?, cb?)`

Loads pixel data from a source based on options. Possibly provide a callback for old-style async calls. Function returns a promise that gets resolved once the source is ready, so that is handy for await call.

In browser the result is ImageData object to easily output to context:

document.body.appendChild(document.createElement('canvas'))
	.getContext('2d')
	.putImageData(await pixels('lena.png'))

`source`

Type	Meaning
`url`, `path`	Relative/absolute path.
`data-uri`, `base64`	String with encoded or raw pixel data. Raw data requires `options.shape`. Encoded data may require `options.type` to skip mime type detection.
`HTMLImageElement`, `SVGImageElement`, `HTMLVideoElement`, `CSSImageValue`	DOM/SVG image elements.
`Image`, `ImageData`, `ImageBitmap`	Browser image data containers.
`File`, `Blob`	Encoded image data.
`Canvas`, `Context2D`	2D drawing context, browser-only.
`WebGLContext`	GL context, node/browser.
`Buffer`, `ArrayBuffer`, `Uint8Array`, `Uint8ClampedArray`	Raw or encoded pixel data. Raw data requires `options.shape`. For encoded data `options.type`skips mime type detection. Supported formats: `png`, `bmp`, `gif`, `jpg`.
`Float32Array`, `Float64Array`, `Array`, `Array` of arrays	Float pixel data with values from `0..1` range.
`Promise`	Promise expecting resolution to an image source.
`ndarray`	Ndarray container with pixel data, compatible with get-pixels.
options object	If `source` argument is omitted, it is taken from `options.source`, useful for `pixels.all`.

`options`

Option	Meaning
`source`	Source data, one from the list above. Applicable for multiple sources.
`shape` or `width`/`height`	Input raw data shape `[width, height]`.
`type`/`mime`	Mime type, optional for raw data to skip detection.
`clip`	Clipping rectangle, `[left, top, right, bottom]` or `{x?, y?, width?, height?}`.
`cache`	Cache loaded data for the source/url for faster subsequent fetch.

`let list|dict = await pixels.all(list|dict, options?)`

Load multiple sources or dict of sources in parallel. options can provide common for every source options.

// load font atlas sprite dict
var atlas = require('font-atlas')({chars: 'abc', step: [10, 10], shape: [20, 20]})

var dict = await pixels({
	a: {clip: [0,0,10,10]},
	b: {clip: [10,0,10,10]},
	c: {clip: [0,10,10,10]}
}, {cache: true, source: atlas})

Related packages

image-save − save image/pixel data to a file, canvas or array.
image-equal − assert image with baseline.

Similar packages

get-pixels − get ndarray with pixel data, limited set of sources.
ndarray-from-image − get-pixels with dtype.
get-image-pixels − get pixel data for Canvas/Image/Video elements, browser-only.
get-image-data − get image data for Canvas/Image/Video elements, browser-only.
readimage − read pixels data into an array in sync fashion in node.