guptarohit / asciigraph / 27897859507

93%

push

github

feat: add spectrum/heatmap gradient coloring (#84)

## Summary

Adds option to enable value-based gradient coloring so each point is
colored by its value — warm tones for high values, cool tones for low —
instead of a single solid color per series. Closes #81.

<img width="1413" height="902" alt="gradient"
src="https://github.com/user-attachments/assets/d000fbda-05ca-4b5f-a847-966aa2dc0330"
/>

## What's new

- **`SeriesColorGradient(stops ...AnsiColor)`** option — colors points
along a palette (lowest value → first stop, highest → last). Applies to
all series and takes precedence over `SeriesColors`.
- **`HeatmapSpectrum`** — a built-in cool-to-warm palette (blue → cyan →
green → yellow → red).
- **Smooth RGB interpolation** between stops, so even two colors blend
into a gradient. A value landing exactly on a stop returns that stop
unchanged, so the built-in palette and exact colors are preserved.
- **CLI `-g` flag** — `-g spectrum` for the built-in palette, or custom
stops like `-g blue,green,yellow,red`.

## Usage

```go
asciigraph.Plot(data,
    asciigraph.Height(15),
    asciigraph.SeriesColorGradient(asciigraph.HeatmapSpectrum...),
)
```

```bash
seq 1 10 | asciigraph -g spectrum -h 12
seq 1 10 | asciigraph -g blue,green,yellow,red -h 12
```

See `examples/gradient/` for a runnable example.

## Tests & docs

- `TestGradientColor` — value→color mapping incl. clamping and RGB
interpolation.
- `TestSeriesColorGradient` — exact colored output of a small plot.
- README section + new `examples/gradient/main.go`.

## Notes

- Additive, no breaking changes; no new dependencies; Go 1.17 / 32-bit
safe.
- Related #38 (`ColorAbove`/`ColorBelow`) is intentionally left as a
follow-up; this PR adds the per-value coloring mechanism it can build
on.

94 of 104 new or added lines in 4 files covered. (90.38%)

669 of 722 relevant lines covered (92.66%)

1342.31 hits per line