first commit

docs/media/image/image-quantisation/src/pipeline/pipeline.md

@@ -0,0 +1,67 @@
+# Adaptive Pipeline
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Full workflow: analyse complexity → spatial cleanup → quantise. Automatically selects the best strategy based on image content. This is the recommended high-level entry point for emblem-generation pipelines because it encapsulates the decision logic for when to skip quantisation, when to apply spatial cleanup, and when to use dithering.
+
+## Features
+
+- One-call image preparation for emblem-solver
+- Skips quantisation for pixel-art images
+- Applies spatial cleanup for vector-aa and vector-clean tiers
+- Auto-selects dithering for photographic content
+- Zod validation for all options
+- OTel counter and histogram instrumentation
+
+## Usage: Basic Example
+
+```ts
+import { adaptivePipeline } from "@suaveplan/image-quantisation/pipeline";
+
+const result = adaptivePipeline(pixels, 32, 32);
+console.log(result.analysis.tier);
+console.log(result.finalColours);
+```
+
+## Usage: Advanced Example
+
+```ts
+import { adaptivePipeline } from "@suaveplan/image-quantisation/pipeline";
+
+const result = adaptivePipeline(pixels, 64, 64, {
+    maxColours: 16,
+    dither: "floyd-steinberg",
+    spatial: { maxDistance: 25, maxPoolSize: 2 },
+    skipQuantisationForPixelArt: false,
+});
+
+if (result.spatialCleanupApplied) {
+    console.log("Spatial cleanup merged small AA pools");
+}
+```
+
+## API Reference
+
+### `adaptivePipeline(pixels, width, height, options?): AdaptivePipelineResult`
+
+- `pixels` — RGBA `Uint8Array`
+- `width`, `height` — image dimensions
+- `options` — `AdaptivePipelineOptions` (optional)
+
+Returns `AdaptivePipelineResult` with:
+
+- `pixels` — final processed buffer
+- `analysis` — complexity analysis of the original
+- `quantisation` — quantisation result or `null`
+- `spatialCleanupApplied` — boolean
+- `finalColours` — unique colour count after processing
+
+Throws `QuantisationError` on invalid input or options.
+
+## Implementation Notes
+
+The pipeline never mutates the input buffer. Each stage creates a new `Uint8Array` when modification is required. OTel instruments record the complexity tier and whether spatial cleanup was applied as attributes. The final colour count is computed by packing each RGBA tuple into a 32-bit integer and counting distinct values in a `Set`. This design makes the pipeline safe to call repeatedly on the same buffer without copying at the call site. The `skipQuantisationForPixelArt` default is true because pixel-art images already have a low colour count and quantisation would only degrade quality.