Adaptive Pipeline

(no submodules)

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

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

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.

2.5 KiB Raw Blame History