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