first commit

docs/media/image/image-quantisation/src/spatial/cleanup/cleanup.md

@@ -0,0 +1,69 @@
+# Spatial Cleanup
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Merge small anti-aliasing pools into their nearest spatial neighbours by colour distance. This preserves intentional detail while removing AA noise. Unlike global k-means quantisation, spatial cleanup only merges pools that are physically adjacent, so a small blue dot next to a red region stays blue while a near-red edge pixel gets absorbed into the red region.
+
+## Features
+
+- Spatially-aware merge (not global k-means)
+- Configurable colour distance and pool size thresholds
+- Returns a new pixel buffer (non-destructive)
+- Fast pixel-to-pool index lookup via `Int32Array`
+
+## Usage: Basic Example
+
+```ts
+import {
+    detectPools,
+    spatialCleanup,
+} from "@suaveplan/image-quantisation";
+
+const pools = detectPools(pixels, 32, 32);
+const cleaned = spatialCleanup(pixels, 32, 32, pools);
+```
+
+## Usage: Advanced Example
+
+```ts
+import {
+    detectPools,
+    spatialCleanup,
+    countUniqueColours,
+} from "@suaveplan/image-quantisation";
+
+const pools = detectPools(pixels, 64, 64);
+const before = countUniqueColours(pixels, 64, 64);
+
+const cleaned = spatialCleanup(pixels, 64, 64, pools, {
+    maxDistance: 25,
+    maxPoolSize: 3,
+});
+
+const after = countUniqueColours(cleaned, 64, 64);
+console.log(`Removed ${before - after} colours`);
+```
+
+## API Reference
+
+### `spatialCleanup(pixels, width, height, pools, options?): Uint8Array`
+
+- `pixels` — RGBA `Uint8Array`
+- `width`, `height` — image dimensions
+- `pools` — array of `Pool` from `detectPools`
+- `options.maxDistance` — default 30
+- `options.maxPoolSize` — default 4
+
+Returns a new `Uint8Array` with merged pixels.
+
+### `countUniqueColours(pixels, width, height): number`
+
+Counts distinct colours in the buffer using a 32-bit packed key.
+
+## Implementation Notes
+
+The algorithm builds an adjacency map for pools that are physically adjacent in the image. For each small pool, it finds the neighbour with the minimum `rgbDistance`. If the distance is within `maxDistance`, the pool is recoloured. The pixel-to-pool index is stored in an `Int32Array` initialised to `-1` for fast O(1) lookup during adjacency building.