image-q

A Palette Quantizer is an object used to manually control the palette generation process. You can sample one or more PointContainer objects and then run the quantization.

Manual Workflow (Sync)

1. Instantiate a quantizer (e.g., new WuQuant(distanceCalculator, colors)).
2. Call .sample(pointContainer) for each image you want to include in the sampling.
3. Call .quantizeSync() to get the resulting [[Palette]].

Generator Workflow (Async-like)

The .quantize() method returns a generator, allowing you to track progress or wrap the iteration in setTimeout to avoid blocking the main thread.

Available Quantizers

• NeuQuant: Original port with integer calculations.
• NeuQuantFloat: Floating-point calculations.
• RGBQuant
• WuQuant

// Sync usage
const paletteQuantizer = new WuQuant(distanceCalculator, 256);
paletteQuantizer.sample(pointContainer1);
paletteQuantizer.sample(pointContainer2);
const palette = paletteQuantizer.quantizeSync();

// Generator usage
const paletteQuantizer = new WuQuant(distanceCalculator, 256);
paletteQuantizer.sample(pointContainer1);
const generator = paletteQuantizer.quantize();
let palette;
while (true) {
  const result = generator.next();
  if (result.done) break;
  if (result.value.palette) palette = result.palette;
  console.log(`${result.value.progress}% done`);
}

To reduce the color depth of an image (e.g., converting a 24-bit PNG to an 8-bit indexed format), you must first load the image data into a PointContainer, build a color palette from that container, and then apply the palette back to the container.

Note: This example uses pngjs for file reading, but image-q can work with various sources via PointContainer methods.

import { PNG } from 'pngjs';
import { buildPaletteSync, utils, applyPaletteSync } from 'image-q';
import fs from 'fs';

// 1. Read file and convert to PointContainer
const { data, width, height } = PNG.sync.read(fs.readFileSync('file.png'));
const inPointContainer = utils.PointContainer.fromUint8Array(
  data,
  width,
  height,
);

// 2. Build the palette from the image
const palette = buildPaletteSync([inPointContainer]);

// 3. Apply the palette to create the indexed image
const outPointContainer = applyPaletteSync(inPointContainer, palette);

// Use outPointContainer.toUint8Array() to get the resulting data

To create a palette (a set of colors) from an existing image, follow these steps:

1. Load the image into a PointContainer using iq.utils.PointContainer.fromHTMLImageElement(img).
2. Choose a distance calculator (e.g., iq.distance.Euclidean).
3. Initialize a palette quantizer (e.g., iq.palette.RGBQuant) with the distance calculator and your targetColors count.
4. Call .sample(pointContainer) on the quantizer to analyze the image colors.
5. Call .quantizeSync() to retrieve the generated palette.

// 1. Setup target colors
var targetColors = 256;

// 2. Create PointContainer from image
var pointContainer = iq.utils.PointContainer.fromHTMLImageElement(img);

// 3. Setup distance calculator
var distanceCalculator = new iq.distance.Euclidean();

// 4. Setup palette quantizer
var paletteQuantizer = new iq.palette.RGBQuant(distanceCalculator, targetColors);

// 5. Sample the image
paletteQuantizer.sample(pointContainer);

// 6. Get the palette
var palette = paletteQuantizer.quantizeSync();

The buildPalette API quantizes sample images to create a [[Palette]] instance. You can use either the asynchronous (Promise-based) or synchronous version.

Async version

Use buildPalette for non-blocking operations. It accepts an array of PointContainer objects and an options object.

Sync version

Use buildPaletteSync for immediate execution. Note that the underlying generator is wrapped with setImmediate (polyfilled).

Options

• colorDistanceFormula: (string) The formula used to calculate color similarity.
• paletteQuantization: (string) The algorithm used for palette generation.
• colors: (number) The target number of colors in the palette.
• onProgress: (function) A callback receiving the current progress value.

// Async
import { buildPalette } from 'image-q';
const palette = await buildPalette([pointContainer], {
  colorDistanceFormula: 'euclidean',
  paletteQuantization: 'neuquant',
  colors: 128,
  onProgress: (progress) => console.log('applyPalette', progress),
});

// Sync
import { buildPaletteSync } from 'image-q';
const palette = buildPaletteSync([pointContainer], {
  colorDistanceFormula: 'euclidean',
  paletteQuantization: 'neuquant',
  colors: 128,
});

ErrorDiffusionArray is an image quantizer that supports various error propagation modes (dithering kernels) like FloydSteinberg, Stucki, Atkinson, Jarvis, etc. You can use it synchronously or via a generator for progress tracking.

Synchronous Usage

Use quantizeSync to process the image immediately.

Generator Usage

Use quantize to get a generator. This is useful for tracking progress or preventing UI blocking by wrapping .next() calls in setTimeout to make them asynchronous.

Supported Kernels

• FloydSteinberg
• FalseFloydSteinberg
• Stucki
• Atkinson
• Jarvis
• Burkes
• Sierra
• TwoSierra
• SierraLite

const imageQuantizer = new ErrorDiffusionArray(
  distanceCalculator,
  ErrorDiffusionArrayKernel.Jarvis,
);

// Synchronous
const outPointContainer = imageQuantizer.quantizeSync(
  inPointContainer,
  palette,
);

// Generator (for progress tracking)
const generator = imageQuantizer.quantize(inPointContainer, palette);
let outPointContainer;
while (true) {
  const result = generator.next();
  if (result.done) break;
  if (result.value.pointContainer) outPointContainer = result.value.pointContainer;
  console.log(`${result.value.progress}% done`);
}

The applyPalette API applies an existing [[Palette]] to a [[PointContainer]], returning a new [[PointContainer]] representing the quantized image.

Async version

Use applyPalette for Promise-based workflows.

Sync version

Use applyPaletteSync for synchronous workflows.

Options

• colorDistanceFormula: (string) The formula used to match pixels to palette colors.
• imageQuantization: (string) The dithering algorithm used (e.g., 'floyd-steinberg').
• onProgress: (function) A callback receiving the current progress value.

// Async
import { applyPalette } from 'image-q';
const outPointContainer = await applyPalette(pointContainer, palette, {
  colorDistanceFormula: 'euclidean',
  imageQuantization: 'floyd-steinberg',
  onProgress: (progress) => console.log('applyPalette', progress),
});

// Sync
import { applyPaletteSync } from 'image-q';
const outPointContainer = applyPaletteSync(pointContainer, palette, {
  colorDistanceFormula: 'euclidean',
  imageQuantization: 'floyd-steinberg',
});