Complexity Classification

(no submodules)

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

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

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.

2.4 KiB Raw Blame History Unescape Escape