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