Pixel Utility Functions

Common errors

• TypeError: Cannot destructure property 'data' of 'undefined' as it is undefined.

  cause 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)

  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).
  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'.

  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.
  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.

Warnings

• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install pixel-utils npm
• yarn add pixel-utils yarn
• pnpm add pixel-utils pnpm

Imports

• rawToRgba
  wrong:

  const rawToRgba = require('pixel-utils').rawToRgba;

  correct:

  import { rawToRgba } from 'pixel-utils';

  While CommonJS is supported, ESM imports are preferred in modern TypeScript/Node.js environments. Function signatures are currently in beta and may change.
• eachPixel
  wrong:

  import eachPixel from 'pixel-utils/eachPixel'; // incorrect path for named export

  correct:

  import { eachPixel } from 'pixel-utils';

  All core utility functions are named exports from the main package entry point. Direct subpath imports might not be stable or intended.
• rgbToRgba
  wrong:

  const { rgbToRgba } = require('pixel-utils');

  correct:

  import { rgbToRgba } from 'pixel-utils';

  TypeScript types are included, ensuring strong typing for pixel arrays. Incorrect pixel array structures will result in type errors during development.

Quickstart

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.`);