# ndarray-pixels

> ndarray-pixels

Latest version **5.2.0** (published 2026-07-31) · MIT license · 0 weekly downloads

## Install

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

## Health

**Score 60/100 (C)** — status: active.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 5.2.0 |
| Published | 2026-07-31 |
| First published | 2021-04-17 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 4 |
| Unpacked size | 41.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Don McCurdy <dm@donmccurdy.com> |
| Maintainers | donmccurdy |

## Links

- npm: https://www.npmjs.com/package/ndarray-pixels
- Repository: github:donmccurdy/ndarray-pixels
- npm.io page: https://npm.io/package/ndarray-pixels

## Dependencies (4)

- [sharp](https://npm.io/package/sharp.md) ^0.35.0
- [ndarray](https://npm.io/package/ndarray.md) ^1.0.19
- [ndarray-ops](https://npm.io/package/ndarray-ops.md) ^1.2.2
- [@types/ndarray](https://npm.io/package/@types/ndarray.md) ^1.0.14

## Recent versions

- 5.2.0 (latest) — 2026-07-31
- 5.0.0-alpha.2 (alpha) — 2025-05-28
- 5.0.1 — 2025-06-02
- 5.0.0 — 2025-05-28
- 4.1.0 — 2024-05-17
- 4.0.0 — 2024-05-05
- 3.1.0 — 2023-11-27
- 3.0.4 — 2023-06-14
- 3.0.3 — 2023-06-14
- 3.0.2 — 2023-06-14
- 2.0.4 — 2023-06-14
- 3.0.1 — 2023-06-14
- 2.0.3 — 2023-06-14
- 2.0.2 — 2023-06-14
- 3.0.0 — 2023-06-14
- … 10 more at https://npm.io/package/ndarray-pixels/versions

## README

# ndarray-pixels

[![Latest NPM release](https://img.shields.io/npm/v/ndarray-pixels.svg)](https://www.npmjs.com/package/ndarray-pixels)
[![License](https://img.shields.io/badge/license-MIT-007ec6.svg)](https://github.com/donmccurdy/ndarray-pixels/blob/main/LICENSE)
[![npm bundle size](https://img.shields.io/bundlephobia/minzip/ndarray-pixels)](https://bundlephobia.com/package/ndarray-pixels)
[![CI](https://github.com/donmccurdy/ndarray-pixels/workflows/CI/badge.svg?branch=main&event=push)](https://github.com/donmccurdy/ndarray-pixels/actions?query=workflow%3ACI)

Convert [ndarray](https://www.npmjs.com/package/ndarray) ↔ image data, on Web and Node.js.

Designed to be used with [other ndarray-based packages](http://scijs.net/packages/).

## Supported Formats

| Platform | JPEG | PNG | Other                                                                                                 |
|----------|------|-----|-------------------------------------------------------------------------------------------------------|
| Node.js  | ✅    | ✅   | Based on [sharp support](https://sharp.pixelplumbing.com/)                                            |
| Web      | ✅    | ✅   | Based on [browser support](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/toBlob) |

### Known Bugs

- [ ] Web implementation (Canvas 2D) premultiplies alpha.

## Quickstart

```
npm install --save ndarray-pixels
```

### Web

```javascript
import { getPixels, savePixels } from 'ndarray-pixels';

const bytesIn = await fetch('./input.png')
    .then((res) => res.arrayBuffer())
    .then((arrayBuffer) => new Uint8Array(arrayBuffer));

// read
const pixels = await getPixels(bytesIn, 'image/png'); // Uint8Array -> ndarray

// modify
const [width, height] = pixels.shape;
for (let x = 0; x < width; ++x) {
  for (let y = 0; y < height; ++y) {
    pixels.set(x, y, 0, 255); // R
    pixels.set(x, y, 1, 0.0); // G
    pixels.set(x, y, 2, 0.0); // B
    pixels.set(x, y, 3, 255); // A
  }
}

// write
const bytesOut = await savePixels(pixels, 'image/png'); // ndarray -> Uint8Array
```


### Node.js

```javascript
const fs = require('fs');
const { getPixels, savePixels } = require('ndarray-pixels');

const bufferIn = fs.readFileSync('./input.png');

// read
const pixels = await getPixels(bufferIn, 'image/png'); // Uint8Array -> ndarray

// modify
const [width, height] = pixels.shape;
for (let x = 0; x < width; ++x) {
  for (let y = 0; y < height; ++y) {
    pixels.set(x, y, 0, 255); // R
    pixels.set(x, y, 1, 0.0); // G
    pixels.set(x, y, 2, 0.0); // B
    pixels.set(x, y, 3, 255); // A
  }
}

// write
const bufferOut = await savePixels(pixels, 'image/png'); // ndarray -> Uint8Array
fs.writeFileSync('./output.png', bufferOut);
```

## API

### Function: getPixels()

> **getPixels**(`data`, `mimeType`): `Promise`\<`NdArray`\<`Uint8Array`\<`ArrayBufferLike`\>\>\>

Decodes image data to an `ndarray`.

MIME type is optional when given a path or URL, and required when given a Uint8Array.

Accepts `image/png` or `image/jpeg` in Node.js, and additional formats on browsers with
the necessary support in Canvas 2D.

#### Parameters

##### data

`Uint8Array`

##### mimeType

`string`

`image/jpeg`, `image/png`, etc.

#### Returns

`Promise`\<`NdArray`\<`Uint8Array`\<`ArrayBufferLike`\>\>\>
### Function: savePixels()

> **savePixels**(`pixels`, `typeOrOptions`): `Promise`\<`Uint8Array`\<`ArrayBufferLike`\>\>

Encodes an `ndarray` as image data in the given format.

If the source `ndarray` was constructed manually with default stride, use
`ndarray.transpose(1, 0)` to reshape it and ensure an identical result from getPixels(). For an
ndarray created by getPixels(), this isn't necessary.

Accepts `image/png` or `image/jpeg` in Node.js, and additional formats on browsers with
the necessary support in Canvas 2D.

#### Parameters

##### pixels

`NdArray`\<`Uint8Array`\<`ArrayBufferLike`\> \| `Uint8ClampedArray`\<`ArrayBufferLike`\>\>

ndarray of shape W x H x 4.

##### typeOrOptions

object with encoding options or just the type

`string` |

\{ `quality?`: `number`; `type?`: `string`; \}

object with encoding options or just the type

###### quality?

`number`

quality as a number from 0 to 1, inclusive

###### type?

`string`

target format (`image/jpeg`, `image/png`, `image/webp`, etc.)

#### Returns

`Promise`\<`Uint8Array`\<`ArrayBufferLike`\>\>

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