first commit

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

@@ -0,0 +1,66 @@
+# Complexity Classification
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Analyse a raw RGBA pixel buffer and classify its complexity into one of four tiers: pixel-art, vector-clean, vector-aa, or photographic. The tier determines the optimal processing strategy for emblem generation pipelines. This module combines pool detection, edge analysis, and heuristics into a single high-level entry point.
+
+## Features
+
+- Four-tier classification based on pool distribution and edge sharpness
+- Automatic palette size recommendation
+- Dithering recommendation for photographic content
+- Pure TypeScript with zero external dependencies for analysis
+
+## Usage: Basic Example
+
+```ts
+import { analyseComplexity } from "@suaveplan/image-quantisation/analysis/classify";
+
+const analysis = analyseComplexity(pixels, 32, 32);
+console.log(analysis.tier); // "pixel-art" | "photographic" | ...
+console.log(analysis.recommendedColours); // suggested palette size
+```
+
+## Usage: Advanced Example
+
+```ts
+import { analyseComplexity } from "@suaveplan/image-quantisation/analysis/classify";
+
+const analysis = analyseComplexity(pixels, 128, 128);
+
+const strategy =
+    analysis.tier === "pixel-art"
+        ? "skip_quantise"
+        : analysis.tier === "photographic"
+          ? "heavy_dither"
+          : "light_merge";
+```
+
+## API Reference
+
+### `analyseComplexity(pixels, width, height): ComplexityAnalysis`
+
+Runs pool detection, edge analysis, and tier classification in one call.
+
+Returns a `ComplexityAnalysis` object containing:
+
+- `tier` — classification result
+- `uniqueColours` — number of distinct colours
+- `poolDistribution` — pool size statistics
+- `edgeAnalysis` — edge sharpness metrics
+- `recommendedColours` — suggested palette size (2–256)
+- `recommendDithering` — boolean
+
+## Implementation Notes
+
+Classification heuristics are tuned for emblem-generation workflows:
+
+- Pixel art: ≤32 colours, mean pool size >20
+- Photographic: >70% singleton pools, sharpness <0.05
+- Vector-AA: bimodal distribution with many tiny edge pools
+
+Recommended colours are clamped to a minimum of 2 to satisfy quantiser constraints. The heuristics were derived from empirical testing on a corpus of pixel-art, vector, and photographic images. They are intentionally simple to keep the analysis fast and deterministic. Future versions may expose the threshold constants as configurable parameters.