first commit

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

@@ -0,0 +1,53 @@
+# Edge Analysis
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Analyse colour transitions between horizontally and vertically adjacent pixels to determine whether an image has sharp edges (pixel art) or soft edges (photographic). Edge metrics are a critical input to the complexity classifier, providing a signal that is orthogonal to pool distribution. Two images may have the same number of pools but very different edge characteristics.
+
+## Features
+
+- Examines every right and bottom neighbour pair
+- Counts hard edges (perceptually distinct) and soft edges (nearly identical)
+- Computes sharpness ratio and mean edge distance
+- Configurable hard/soft thresholds
+
+## Usage: Basic Example
+
+```ts
+import { analyseEdges } from "@suaveplan/image-quantisation/analysis/edges";
+
+const edges = analyseEdges(pixels, 32, 32);
+console.log(edges.sharpnessRatio); // 0.0 – 1.0
+```
+
+## Usage: Advanced Example
+
+```ts
+import { analyseEdges } from "@suaveplan/image-quantisation/analysis/edges";
+
+// Stricter thresholds for high-contrast artwork
+const edges = analyseEdges(pixels, 64, 64, 20, 5);
+
+if (edges.sharpnessRatio > 0.5) {
+    console.log("High-contrast pixel art detected");
+}
+```
+
+## API Reference
+
+### `analyseEdges(pixels, width, height, hardThreshold?, softThreshold?): EdgeAnalysis`
+
+- `pixels` — RGBA `Uint8Array`
+- `width`, `height` — image dimensions
+- `hardThreshold` — default 30
+- `softThreshold` — default 10
+
+Returns `EdgeAnalysis` with `totalEdges`, `hardEdges`, `softEdges`, `sharpnessRatio`, `meanEdgeDistance`.
+
+## Implementation Notes
+
+The function uses `weightedDistance` (ITU-R BT.601) for perceptually fair comparisons. Pairs are counted once each (right and bottom neighbours only) to avoid double counting. A solid-colour image produces zero hard edges and zero mean distance, while a checkerboard produces a very high sharpness ratio. The thresholds can be adjusted for different content types: stricter thresholds treat more edges as hard, which is useful for high-contrast artwork, while lenient thresholds classify most edges as soft, which is better for smooth gradients.