skills/plugins/document-navigator/docs/media/image/image-quantisation/README.md

@suaveplan/image-quantisation - Image complexity analysis and adaptive colour quantisation with pool detection, spatial-aware anti-aliasing cleanup, and multiple quantisation algorithms

Image complexity analysis and adaptive colour quantisation with pool detection, spatial-aware anti-aliasing cleanup, and multiple quantisation algorithms. Designed for emblem generation pipelines where pixel-art inputs need minimal processing while photographic inputs need aggressive reduction.

Documentation tree

• classify — Analyse a raw RGBA pixel buffer and classify its complexity into one of four tiers: pixel-art, vector-clean, vector-aa,…
  • classify — Analyse a raw RGBA pixel buffer and classify its complexity into one of four tiers: pixel-art, vector-clean, vector-aa,…
• colour — Low-level colour distance and keying helpers used by the analysis and spatial-cleanup modules. These functions are pure…
  • colour — Low-level colour distance and keying helpers used by the analysis and spatial-cleanup modules. These functions are pure…
• edges — Analyse colour transitions between horizontally and vertically adjacent pixels to determine whether an image has sharp…
  • edges — Analyse colour transitions between horizontally and vertically adjacent pixels to determine whether an image has sharp…
• pools — Find contiguous regions of identical colour via 4-connected flood fill. Pool size distribution is the primary signal fo…
  • pools — Find contiguous regions of identical colour via 4-connected flood fill. Pool size distribution is the primary signal fo…
• errors — Structured error type for all @suaveplan/image-quantisation failures. Extends SuaveplanError so that callers receiv…
  • image-quantisation-error — Structured error type for all @suaveplan/image-quantisation failures. Extends SuaveplanError so that callers receiv…
• pipeline — Full workflow: analyse complexity → spatial cleanup → quantise. Automatically selects the best strategy based on image…
  • pipeline — Full workflow: analyse complexity → spatial cleanup → quantise. Automatically selects the best strategy based on image…
• quantise — Reduce an RGBA pixel buffer to a target number of colours using the image-q library. This module is the primary quant…
  • quantise — Reduce an RGBA pixel buffer to a target number of colours using the image-q library. This module is the primary quant…
• schemas — Zod schemas for runtime validation of quantisation, spatial cleanup, and pipeline options. Every public entry point tha…
  • options.schema — Zod schemas for runtime validation of quantisation, spatial cleanup, and pipeline options. Every public entry point tha…
• cleanup — Merge small anti-aliasing pools into their nearest spatial neighbours by colour distance. This preserves intentional de…
  • cleanup — Merge small anti-aliasing pools into their nearest spatial neighbours by colour distance. This preserves intentional de…
• types — The common.ts module defines the core domain types used across the @suaveplan/image-quantisation package. Every pub…
  • common — The common.ts module defines the core domain types used across the @suaveplan/image-quantisation package. Every pub…

Installation

bun add @suaveplan/image-quantisation

Quick Start

import {
    adaptivePipeline,
    analyseComplexity,
    quantise,
} from "@suaveplan/image-quantisation";

// Full adaptive pipeline: analyse -> cleanup -> quantise
const result = adaptivePipeline(rgbaPixels, width, height);

console.log(result.analysis.tier); // 'pixel-art' | 'vector-aa' | 'photographic'
console.log(result.analysis.uniqueColours);
console.log(result.finalColours); // colour count after quantisation
// result.pixels is ready for downstream consumers

Modules

• src/analysis/classify/classify.md — Complexity classification
• src/analysis/colour/colour.md — Colour distance and keying utilities
• src/analysis/edges/edges.md — Edge sharpness analysis
• src/analysis/pools/pools.md — Pool detection and distribution
• src/errors/image-quantisation-error.md — Structured error types
• src/pipeline/pipeline.md — Adaptive pipeline
• src/quantise/quantise.md — Colour quantisation
• src/schemas/options.schema.md — Zod validation schemas
• src/spatial/cleanup/cleanup.md — Spatial AA cleanup
• src/types/common.md — Core type definitions

Features

• Image complexity classification into four tiers: pixel-art, vector-clean, vector-aa, photographic
• Pool detection via 4-connected flood fill for contiguous same-colour regions
• Pool distribution statistics (count, min, max, mean, median, singleton ratio)
• Edge analysis with sharpness ratio and mean colour distance
• Spatial AA cleanup that merges small pools into nearest spatial neighbours
• Three quantisation algorithms: wuquant (Wu), neuquant (neural network), rgbquant (fast)
• Three colour distance formulas: euclidean, manhattan, ciede2000
• Dithering options: none, floyd-steinberg, riemersma
• Full adaptive pipeline: analyse, cleanup, quantise in one call
• Colour utility functions for distance calculation and key generation
• Zod schemas for runtime option validation
• OpenTelemetry counter and histogram instrumentation
• Structured errors with stable codes via @suaveplan/error
• Property-based tests with fast-check
• 100% test coverage (Istanbul)

License

MIT