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