first commit

docs/media/image/image-quantisation/src/analysis/pools/pools.md

@@ -0,0 +1,56 @@
+# Pool Detection
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Find contiguous regions of identical colour via 4-connected flood fill. Pool size distribution is the primary signal for image complexity classification. A pixel-art image may have only a handful of large pools, while a photograph may have thousands of singleton pools. This module provides both detection and statistical summary functions.
+
+## Features
+
+- 4-connected BFS flood fill
+- Returns pools sorted by size descending
+- Computes distribution statistics
+- Zero dependencies beyond colour utilities
+
+## Usage: Basic Example
+
+```ts
+import { detectPools } from "@suaveplan/image-quantisation/analysis/pools";
+
+const pools = detectPools(pixels, 32, 32);
+console.log(pools.length); // number of distinct colour regions
+console.log(pools[0]!.size); // largest region
+```
+
+## Usage: Advanced Example
+
+```ts
+import {
+    detectPools,
+    poolDistribution,
+} from "@suaveplan/image-quantisation/analysis/pools";
+
+const pools = detectPools(pixels, 64, 64);
+const dist = poolDistribution(pools);
+
+if (dist.singletonRatio > 0.7) {
+    console.log("Photographic — many 1-pixel pools");
+}
+```
+
+## API Reference
+
+### `detectPools(pixels, width, height): Pool[]`
+
+Returns an array of `Pool` objects sorted by size descending.
+
+### `poolDistribution(pools): PoolDistribution`
+
+Computes count, min, max, mean, median, p90, singletons, and singletonRatio.
+
+## Implementation Notes
+
+Flood fill uses a stack-based BFS with a `Uint8Array` visited mask for memory efficiency. The `pixels` buffer is read-only. Pools are sorted by size descending so that the dominant colour regions appear first, which is useful for downstream algorithms that only need to inspect the largest pools. The visited mask uses a single byte per pixel, which keeps memory overhead low even for large images. Because every pixel is visited exactly once, the overall time complexity is O(width * height) in the worst case. For images with many small pools, the BFS queue may grow large, but the `Uint8Array` visited mask ensures that each pixel is never enqueued more than once.