{"id":11560,"library":"pixel-utils","title":"Pixel Utility Functions","description":"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.","status":"active","version":"0.9.0","language":"javascript","source_language":"en","source_url":"https://github.com/DanielJDufour/pixel-utils","tags":["javascript","color","pixel","rgb","rgba","typescript"],"install":[{"cmd":"npm install pixel-utils","lang":"bash","label":"npm"},{"cmd":"yarn add pixel-utils","lang":"bash","label":"yarn"},{"cmd":"pnpm add pixel-utils","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides support for arbitrary image data layouts, a core feature differentiating pixel-utils from other libraries.","package":"xdim"}],"imports":[{"note":"While CommonJS is supported, ESM imports are preferred in modern TypeScript/Node.js environments. Function signatures are currently in beta and may change.","wrong":"const rawToRgba = require('pixel-utils').rawToRgba;","symbol":"rawToRgba","correct":"import { rawToRgba } from 'pixel-utils';"},{"note":"All core utility functions are named exports from the main package entry point. Direct subpath imports might not be stable or intended.","wrong":"import eachPixel from 'pixel-utils/eachPixel'; // incorrect path for named export","symbol":"eachPixel","correct":"import { eachPixel } from 'pixel-utils';"},{"note":"TypeScript types are included, ensuring strong typing for pixel arrays. Incorrect pixel array structures will result in type errors during development.","wrong":"const { rgbToRgba } = require('pixel-utils');","symbol":"rgbToRgba","correct":"import { rgbToRgba } from 'pixel-utils';"}],"quickstart":{"code":"import { rawToRgba, eachPixel } from 'pixel-utils';\n\n// Example raw pixel data (e.g., from a sensor, could be any number)\nconst rawImageBuffer = [\n  1000, 2000, 3000, // Pixel 1 data\n  4000, 5000, 6000, // Pixel 2 data\n  7000, 8000, 9000  // Pixel 3 data\n];\n\n// Define image dimensions and no-data value for raw conversion\nconst width = 3;\nconst height = 1;\nconst bands = 3;\nconst noDataValue = 0; // Assuming 0 for simplicity, actual would depend on sensor\n\n// Convert raw data to RGBA (0-255 range)\n// This example assumes a simple scaling for demonstration.\n// In a real scenario, you'd likely map sensor values to a visual range.\nconst rgbaPixels = rawToRgba({\n  data: rawImageBuffer,\n  width,\n  height,\n  bands,\n  noData: noDataValue,\n  scale: (value: number) => Math.min(255, Math.max(0, value / 40))\n});\n\nconsole.log('Converted RGBA Pixels (first 4 values):', rgbaPixels.data.slice(0, 4));\n\n// Iterate over the RGBA pixels\nlet pixelCount = 0;\neachPixel({\n  data: rgbaPixels.data,\n  width: rgbaPixels.width,\n  height: rgbaPixels.height,\n  bands: 4 // RGBA has 4 bands\n}, (pixel: number[], x: number, y: number) => {\n  console.log(`Pixel at (${x}, ${y}): [${pixel.join(', ')}]`);\n  pixelCount++;\n});\n\nconsole.log(`Processed ${pixelCount} pixels.`);","lang":"typescript","description":"Demonstrates converting raw, unscaled pixel data into RGBA format and then iterating through the resulting RGBA pixel array."},"warnings":[{"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.","message":"This 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.","severity":"breaking","affected_versions":">=0.0.1"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=0.0.1"},{"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.","message":"Some 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.","severity":"gotcha","affected_versions":">=0.0.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Attempting to use a function or variable that was not correctly imported or does not exist.","error":"TypeError: Cannot destructure property 'data' of 'undefined' as it is undefined."},{"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.","cause":"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).","error":"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)"},{"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.","cause":"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.","error":"Property 'scale' is missing in type '{ data: number[]; width: number; height: number; bands: number; noData: number; }' but required in type 'RawToRgbaOptions'."}],"ecosystem":"npm"}