89 lines
6.4 KiB
Markdown
89 lines
6.4 KiB
Markdown
# @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
|
|
|