Image-Q: Image Quantization Library

Common errors

• TypeError: iq.PaletteQuantizer.quantize is not a function

  cause Attempting to call the synchronous `quantize` method after it was renamed. The `quantize` method is now asynchronous (returns a Promise), and the synchronous version is `quantizeSync`.
  fix If you intend a synchronous operation, change the call to `paletteQuantizer.quantizeSync(...)`. If you intend an asynchronous operation, ensure you `await` the call: `await paletteQuantizer.quantize(...)`.

• ReferenceError: require is not defined

  cause Trying to use the CommonJS `require()` syntax in an ES Module context (e.g., in a Node.js project with `"type": "module"` or a browser environment without a CJS-aware bundler).
  fix Use the ES Module import syntax: `import * as iq from 'image-q';` or `import { utils } from 'image-q';`. Ensure your environment or bundler is configured to handle ES Modules.

• TypeError: (0 , image_q__WEBPACK_IMPORTED_MODULE_0__.utils).PointContainer.fromImageData is not a function

  cause This Webpack/bundler-specific error often indicates an issue with how sub-modules are imported, especially when a global `iq` object might be expected or tree-shaking is over-aggressive.
  fix Ensure you are using specific named imports for sub-modules if you're not importing the entire namespace: `import { utils, dist, palette, image } from 'image-q';` rather than relying solely on `import * as iq from 'image-q'` for direct access to sub-modules without namespace qualification (e.g., `iq.utils.PointContainer`).

Warnings

• breaking The synchronous `quantize` method on `PaletteQuantizer` and `ImageQuantizer` classes was renamed to `quantizeSync` to distinguish it from the new promise-based `quantize` method.
  Fix: Update calls from `quantize()` to `quantizeSync()` for synchronous operations, or use the new `await quantize()` for asynchronous, promise-based workflows.
• breaking Several color distance class names were updated for clarity. For example, `EuclideanRgbQuantWOAlpha` became `EuclideanBT709NoAlpha`, and `EuclideanRgbQuantWithAlpha` became `EuclideanBT709`.
  Fix: Review and update usages of affected color distance classes to their new names according to the API documentation.
• gotcha From version 3.0.2, the dedicated CommonJS (CJS) build was removed and replaced by a UMD (Universal Module Definition) build. While `require('image-q')` still functions, its behavior might have changed slightly, as the UMD build bundles all dependencies, potentially leading to larger bundle sizes or different loading characteristics compared to a pure CJS build.
  Fix: Users relying on strict CommonJS module behavior or specific CJS build characteristics should verify compatibility. Consider using ES module imports (`import * as iq from 'image-q';`) with a bundler for optimal results, especially in Node.js ESM projects.

Install

• npm install image-q npm
• yarn add image-q yarn
• pnpm add image-q pnpm

Imports

• iq
  wrong:

  const iq = require('image-q');

  correct:

  import * as iq from 'image-q';

  The recommended ES Module import. This will load the ESM build via bundlers. CommonJS `require` is also supported but loads the UMD build since v3.0.2.
• { utils, dist, palette, image }

  import { utils, dist, palette, image } from 'image-q';

  For granular imports of specific sub-modules, which can aid tree-shaking in bundlers.
• iq

  var iq = require('image-q');

  Standard CommonJS import. Since v3.0.2, this loads the UMD build, which bundles all dependencies into a single file.

Quickstart

This quickstart demonstrates how to perform image quantization using a mock `ImageData` object, applying a NeuQuant palette generation algorithm and Floyd-Steinberg dithering to reduce the image's color count. It showcases the full async API flow.

import {
  utils,
  dist,
  palette,
  image,
} from 'image-q';

// Mock ImageData for demonstration. In a real app, you'd get this from a CanvasRenderingContext2D.
const width = 16;
const height = 16;
const data = new Uint8Array(width * height * 4);
for (let i = 0; i < data.length; i += 4) {
  data[i] = Math.floor(Math.random() * 256);     // R
  data[i + 1] = Math.floor(Math.random() * 256); // G
  data[i + 2] = Math.floor(Math.random() * 256); // B
  data[i + 3] = 255;                             // A
}
const imageData = { data, width, height };

async function quantizeImage() {
  // 1. Convert raw image data to PointContainer format
  const inPointContainer = utils.PointContainer.fromImageData(imageData);

  // 2. Define a color distance metric (e.g., Euclidean with BT.709 coefficients)
  const distanceCalculator = new dist.EuclideanBT709();

  // 3. Define a palette quantizer (e.g., NeuQuant to generate a 256-color palette)
  const paletteQuantizer = new palette.NeuQuant(distanceCalculator, 256);
  const colorPointContainer = await paletteQuantizer.quantize(inPointContainer);

  // 4. Define an image quantizer (e.g., Floyd-Steinberg error diffusion dithering)
  const imageQuantizer = new image.ErrorDiffusionArray(
    distanceCalculator,
    image.ErrorDiffusionArrayKernel.FloydSteinberg
  );

  // 5. Quantize the image pixels against the generated palette
  const outPointContainer = await imageQuantizer.quantize(inPointContainer, colorPointContainer);

  // 6. Get the result as a Uint8Array (RGBA data)
  const quantizedData = outPointContainer.toUint8Array();
  console.log('Quantized image data (first 16 bytes):', quantizedData.slice(0, 16));
  console.log('Original image dimensions:', `${width}x${height}`);
  console.log('Quantized image data length:', quantizedData.length);
}

quantizeImage().catch(console.error);