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