first commit
This commit is contained in:
88
docs/media/image/image-quantisation/README.md
Normal file
88
docs/media/image/image-quantisation/README.md
Normal file
@@ -0,0 +1,88 @@
|
||||
# @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
|
||||
|
||||
Reference in New Issue
Block a user