Registry / data / pixel-utils

pixel-utils

JSON →
library0.9.0jsnpmunverified

pixel-utils is a JavaScript/TypeScript library providing minimalist utility functions for pixel manipulation. As of version 0.9.0, it offers conversions between raw, RGB, and RGBA pixel formats, functions for handling 'no data' values, pixel iteration, selection, and transparency adjustments. The library is optimized for speed and supports optional mutability for memory-preserving operations. A key differentiator is its ability to handle raw image data (not limited to 8-bit 0-255 RGBA) and arbitrary image layouts, thanks to integration with the xdim library. While actively developed with frequent minor updates, the project maintains a 'beta' status, indicating that function signatures are subject to change without strict adherence to semantic versioning for breaking changes. Core assumptions involve pixel formats as arrays of numbers (0-255 for RGB/RGBA, arbitrary for raw) and specific conventions for alpha and 'no data' values.

npm install pixel-utils
INSTALL
IMPORT
SIG · PIXEL-UTILS
P
pixel-utils
datajavascriptv0.9.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

rawToRgba
import { rawToRgba } from 'pixel-utils';
const rawToRgba = require('pixel-utils').rawToRgba;
While CommonJS is supported, ESM imports are preferred in modern TypeScript/Node.js environments. Function signatures are currently in beta and may change.
eachPixel
import { eachPixel } from 'pixel-utils';
import eachPixel from 'pixel-utils/eachPixel'; // incorrect path for named export
All core utility functions are named exports from the main package entry point. Direct subpath imports might not be stable or intended.
rgbToRgba
import { rgbToRgba } from 'pixel-utils';
const { rgbToRgba } = require('pixel-utils');
TypeScript types are included, ensuring strong typing for pixel arrays. Incorrect pixel array structures will result in type errors during development.

Demonstrates converting raw, unscaled pixel data into RGBA format and then iterating through the resulting RGBA pixel array.

import { rawToRgba, eachPixel } from 'pixel-utils'; // Example raw pixel data (e.g., from a sensor, could be any number) const rawImageBuffer = [ 1000, 2000, 3000, // Pixel 1 data 4000, 5000, 6000, // Pixel 2 data 7000, 8000, 9000 // Pixel 3 data ]; // Define image dimensions and no-data value for raw conversion const width = 3; const height = 1; const bands = 3; const noDataValue = 0; // Assuming 0 for simplicity, actual would depend on sensor // Convert raw data to RGBA (0-255 range) // This example assumes a simple scaling for demonstration. // In a real scenario, you'd likely map sensor values to a visual range. const rgbaPixels = rawToRgba({ data: rawImageBuffer, width, height, bands, noData: noDataValue, scale: (value: number) => Math.min(255, Math.max(0, value / 40)) }); console.log('Converted RGBA Pixels (first 4 values):', rgbaPixels.data.slice(0, 4)); // Iterate over the RGBA pixels let pixelCount = 0; eachPixel({ data: rgbaPixels.data, width: rgbaPixels.width, height: rgbaPixels.height, bands: 4 // RGBA has 4 bands }, (pixel: number[], x: number, y: number) => { console.log(`Pixel at (${x}, ${y}): [${pixel.join(', ')}]`); pixelCount++; }); console.log(`Processed ${pixelCount} pixels.`);
Debug
Known issues
breakingThis library is currently in beta. Function signatures, API behavior, and assumptions are explicitly stated to be subject to change without adhering to major version bumps. Always review the latest release notes.
fix
Pin to exact versions in `package.json` (e.g., `"pixel-utils": "0.9.0"`) and thoroughly test after any updates, even minor ones. Monitor GitHub releases for announcements.
affects: >=0.0.1
gotchaThe library makes specific 'core assumptions and constraints' about pixel data formats (e.g., RGB as `[R, G, B]`, RGBA as `[R, G, B, A]`, 0-255 range, 'no data' representation). Misunderstanding these can lead to incorrect processing or unexpected visual results.
fix
Carefully read the 'core assumptions and constraints' section in the README. Ensure your input pixel arrays strictly adhere to the expected format and 'no data' conventions for each function.
affects: >=0.0.1
gotchaSome operations, particularly those dealing with 'no data' values or conversions, might involve implicit scaling or default behaviors that could alter pixel values if not explicitly configured. For example, `rawToRgba` requires a `scale` function parameter to correctly map arbitrary raw values to 0-255 RGBA.
fix
Always provide explicit parameters like `scale` or `noData` where applicable, rather than relying on defaults. Thoroughly test edge cases, especially around 'no data' values and range conversions.
affects: >=0.0.1
Errors
Common errors & fixes
TypeError: Cannot destructure property 'data' of 'undefined' as it is undefined.
Attempting to use a function or variable that was not correctly imported or does not exist.
fix
Ensure you are using the correct named import, e.g., `import { someFunction } from 'pixel-utils';`, and that the function name is spelled correctly and available in your installed version. Avoid CommonJS `require` if your project is ESM-first.
Argument of type 'number[]' is not assignable to parameter of type 'RgbPixel'. Type 'number[]' is not assignable to type '[number, number, number]'. Target requires 3 element(s) but source may have fewer.ts(2345)
Passing a pixel array with an incorrect number of elements to a TypeScript-typed function (e.g., 4 elements to an `RgbPixel` expecting 3, or vice-versa).
fix
Ensure your pixel arrays strictly match the expected tuple types (e.g., `[number, number, number]` for RGB, `[number, number, number, number]` for RGBA) that the function expects. Validate your input data structure.
Property 'scale' is missing in type '{ data: number[]; width: number; height: number; bands: number; noData: number; }' but required in type 'RawToRgbaOptions'.
Forgetting to provide a required option like `scale` when converting raw pixel data to a standardized range (0-255). The library does not assume a default scaling factor for raw data.
fix
Always explicitly define and pass a `scale` function in the options object for `rawToRgba` to specify how your raw input values should be mapped to the 0-255 range for RGB/RGBA channels.
Upgrade
Version history
0.9.0latest on npm
Audit
Dependencies
xdimrequiredProvides support for arbitrary image data layouts, a core feature differentiating pixel-utils from other libraries.
Agent activity
2 hits · last 30 days
node
2
Resources
pixel-utils — npm install pixel-utils · libregistry