Pool Detection

(no submodules)

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

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

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.

2.1 KiB Raw Blame History