# image-pixels

> Read pixel data from any image source

Latest version **2.2.2** (published 2019-01-26) · MIT license · 0 weekly downloads

## Install

```sh
npm install image-pixels
pnpm add image-pixels
yarn add image-pixels
bun add image-pixels
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.2.2 |
| Published | 2019-01-26 |
| First published | 2018-10-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 23 |
| Unpacked size | 43 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 32 |
| Author | Dmitry Yv |
| Maintainers | dy |
| Keywords | pixel, pixel, image, png, jpeg, jpg, jpe, gif, decode, buffer, data, get-pixels, ndarray, image-pixels, get-pixels, get-pixel-data, get-image-pixels, get-imagedata, get-image-data, image data, image-input, image-output, readimage, ndarray-from-image, image-in, load image, img-load |

## Links

- npm: https://www.npmjs.com/package/image-pixels
- Repository: https://github.com/dy/image-pixels
- Homepage: https://github.com/dy/image-pixels#readme
- Issues: https://github.com/dy/image-pixels/issues
- npm.io page: https://npm.io/package/image-pixels

## Dependencies (23)

- [pxls](https://npm.io/package/pxls.md) ^2.3.2
- [is-url](https://npm.io/package/is-url.md) ^1.2.4
- [is-blob](https://npm.io/package/is-blob.md) ^2.0.0
- [request](https://npm.io/package/request.md) ^2.88.0
- [to-uint8](https://npm.io/package/to-uint8.md) ^1.4.0
- [weak-map](https://npm.io/package/weak-map.md) ^1.0.5
- [is-base64](https://npm.io/package/is-base64.md) ^0.1.0
- [is-buffer](https://npm.io/package/is-buffer.md) ^2.0.3
- [image-type](https://npm.io/package/image-type.md) ^3.0.0
- [is-browser](https://npm.io/package/is-browser.md) ^2.1.0
- [is-promise](https://npm.io/package/is-promise.md) ^2.1.0
- [parse-rect](https://npm.io/package/parse-rect.md) ^1.2.0
- [arr-flatten](https://npm.io/package/arr-flatten.md) ^1.1.0
- [clip-pixels](https://npm.io/package/clip-pixels.md) ^1.0.1
- [flip-pixels](https://npm.io/package/flip-pixels.md) ^1.0.1
- [is-relative](https://npm.io/package/is-relative.md) ^1.0.0
- [image-decode](https://npm.io/package/image-decode.md) ^1.1.0
- [is-plain-obj](https://npm.io/package/is-plain-obj.md) ^1.1.0
- [object-assign](https://npm.io/package/object-assign.md) ^4.1.1
- [is-float-array](https://npm.io/package/is-float-array.md) ^1.0.0
- [primitive-pool](https://npm.io/package/primitive-pool.md) ^1.1.0
- [to-array-buffer](https://npm.io/package/to-array-buffer.md) ^3.1.1
- [arraybuffer-to-string](https://npm.io/package/arraybuffer-to-string.md) ^1.0.2

## Alternatives

- [flatbuffers](https://npm.io/package/flatbuffers.md) — 6.0M weekly downloads
- [jwt-simple](https://npm.io/package/jwt-simple.md) — 259.5K weekly downloads
- [@exodus/patch-broken-hermes-typed-arrays](https://npm.io/package/@exodus/patch-broken-hermes-typed-arrays.md) — 28.5K weekly downloads
- [@native-to-anchor/buffer-layout](https://npm.io/package/@native-to-anchor/buffer-layout.md) — 12.2K weekly downloads
- [binary-parser-encoder](https://npm.io/package/binary-parser-encoder.md) — 5.3K weekly downloads

## Recent versions

- 2.2.2 (latest) — 2019-01-26
- 2.2.1 — 2019-01-12
- 2.2.0 — 2018-11-14
- 2.1.0 — 2018-11-13
- 2.0.4 — 2018-11-13
- 2.0.3 — 2018-11-12
- 2.0.2 — 2018-11-12
- 2.0.1 — 2018-11-11
- 2.0.0 — 2018-11-11
- 1.1.1 — 2018-11-07
- 1.1.0 — 2018-11-07
- 1.0.2 — 2018-10-26

## README

# image-pixels [![Build Status](https://travis-ci.org/dy/image-pixels.svg?branch=master)](https://travis-ci.org/dy/image-pixels) [![unstable](https://img.shields.io/badge/stability-unstable-green.svg)](http://github.com/badges/stability-badges)

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


## Usage

[![$ npm install image-pixels](http://nodei.co/npm/image-pixels.png?mini=true)](http://npmjs.org/package/image-pixels)

```javascript
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:

```js
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](https://ghub.io/ndarray) container with pixel data, compatible with [get-pixels](https://ghub.io/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.

```js
// 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](https://ghub.io/image-save) − save image/pixel data to a file, canvas or array.
* [image-equal](https://ghub.io/image-equal) − assert image with baseline.

## Similar packages

* [get-pixels](https://ghub.io/get-pixels) − get ndarray with pixel data, limited set of sources.
* [ndarray-from-image](https://github.com/thibauts/ndarray-from-image) − get-pixels with dtype.
* [get-image-pixels](https://ghub.io/get-image-pixels) − get pixel data for Canvas/Image/Video elements, browser-only.
* [get-image-data](https://ghub.io/get-image-data) − get image data for Canvas/Image/Video elements, browser-only.
* [readimage](https://ghub.io/readimage) − read pixels data into an array in sync fashion in node.

## License

© 2018 Dmitry Yv. MIT License.

---
_Source: https://npm.io/package/image-pixels · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._