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

<!-- begin:auto-docs -->
## Documentation tree

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

## Installation

```bash
bun add @suaveplan/image-quantisation
```

## Quick Start

```ts
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`](src/analysis/classify/classify.md) — Complexity classification
- [`src/analysis/colour/colour.md`](src/analysis/colour/colour.md) — Colour distance and keying utilities
- [`src/analysis/edges/edges.md`](src/analysis/edges/edges.md) — Edge sharpness analysis
- [`src/analysis/pools/pools.md`](src/analysis/pools/pools.md) — Pool detection and distribution
- [`src/errors/image-quantisation-error.md`](src/errors/image-quantisation-error.md) — Structured error types
- [`src/pipeline/pipeline.md`](src/pipeline/pipeline.md) — Adaptive pipeline
- [`src/quantise/quantise.md`](src/quantise/quantise.md) — Colour quantisation
- [`src/schemas/options.schema.md`](src/schemas/options.schema.md) — Zod validation schemas
- [`src/spatial/cleanup/cleanup.md`](src/spatial/cleanup/cleanup.md) — Spatial AA cleanup
- [`src/types/common.md`](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