Registry / ai-ml / image-q

image-q

JSON →
library4.0.0jsnpmunverified

Image-Q is a comprehensive TypeScript library for image color quantization, providing various algorithms to reduce the number of colors in an image while preserving visual quality. It supports alpha channels and offers multiple quantization methods, including NeuQuant, RGBQuant, and Xiaolin Wu's algorithms, alongside a broad selection of color distance formulas such as Euclidean, Manhattan, CIEDE2000, and CIE94. The library features both synchronous and promise-based asynchronous APIs, as well as generator-based advanced APIs, making it adaptable for various use cases. It supports both browser (Chrome 7+, Firefox 4+, IE 10+, Opera 11.6+, Safari 5.1+) and Node.js (6.0+) environments. Currently stable at version 4.0.0, the package has a moderate release cadence, with previous major versions introducing significant API changes, particularly around method naming and build outputs. Its key differentiators include a rich set of algorithms and distance metrics, full TypeScript support, and broad platform compatibility. The library is MIT licensed.

npm install image-q
INSTALL
IMPORT
SIG · IMAGE-Q
I
image-q
ai-mljavascriptv4.0.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.

iq
import * as iq from 'image-q';
const iq = require('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.

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);
Debug
Known issues
breakingThe 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.
affects: >=2.1.1
breakingSeveral 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.
affects: >=2.0.1
gotchaFrom 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.
affects: >=3.0.2
Errors
Common errors & fixes
TypeError: iq.PaletteQuantizer.quantize is not a function
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
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
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`).
Upgrade
Version history
4.0.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
6 hits · last 30 days
node
6
Resources
image-q — npm install image-q · libregistry