From cb8ac58e9bc987dc76aa3360da6a151daff9dbb7 Mon Sep 17 00:00:00 2001
From: regorxxx <regorxxx@protonmail.com>
Date: Tue, 20 Feb 2024 18:16:14 +0100
Subject: [PATCH] * added chroma.stdDeviation() to retrieve the variance in an
 array of colors as an RGBA component. See [Issue 328]
 (https://github.com/gka/chroma.js/issues/328#issuecomment-1951628498) * added
 chroma.palette() to retrieve the n-most representative colors in an array of
 colors. See [Issue 328]
 (https://github.com/gka/chroma.js/issues/328#issuecomment-1951628498)

Signed-off-by: regorxxx <regorxxx@protonmail.com>
---
 docs/src/index.md | 32 ++++++++++++++++++++++++++++++++
 index.js          |  2 ++
 2 files changed, 34 insertions(+)

diff --git a/docs/src/index.md b/docs/src/index.md
index 95818bf7..0b8c9592 100644
--- a/docs/src/index.md
+++ b/docs/src/index.md
@@ -380,6 +380,38 @@ And the available scales within a palette:
 chroma.brewer.getPalette('Qualitative').slice(0, 2);
 ```
 
+### chroma.palette
+#### (colors, mode, n)
+
+A helper function that computes a n-palette, based on input colors. It supports the modes [_contrast_ (c)](#chromacontrast), [_distance_ (d)](#chromadistance) and [_deltaE_ (de)](#chromadeltaE). Let's take a few colors as sample.
+
+```js
+var colors = ['#D2691E', '#8B4513', '#A0522D'
+			,'#0000FF', '#668B8B', '#FFC0CB'];
+```
+
+**[Contrast](#chromacontrast)** retrieves the n colors with highest contrast between them from the input colors:
+
+```js
+chroma.palette(colors, 'c', 2);
+```
+
+It also supports Chroma color objects as input, without needing to convert back an forth between formats:
+
+```js
+colors = colors.map(function (c) {return chroma(c)});
+chroma.palette(colors, 'c', 2);
+```
+
+### chroma.stdDeviation
+#### (colors)
+
+A helper function that computes the standard deviation of input colors. Colors are internally parsed as [RGBA](#colorrgba) and output represents the mean RGBA component deviation. Divide it by 255 to get a percentage. Also supports Chroma color objects as input.
+
+```js
+chroma.stdDeviation(colors);
+```
+
 ### chroma.limits
 #### (data, mode, n)
 
diff --git a/index.js b/index.js
index 50d9f390..59b78a69 100644
--- a/index.js
+++ b/index.js
@@ -60,6 +60,8 @@ chroma.analyze = require('./src/utils/analyze').analyze;
 chroma.contrast = require('./src/utils/contrast');
 chroma.deltaE = require('./src/utils/delta-e');
 chroma.distance = require('./src/utils/distance');
+chroma.stdDeviation = require('./src/utils/deviation');
+chroma.palette = require('./src/utils/palette');
 chroma.limits = require('./src/utils/analyze').limits;
 chroma.valid = require('./src/utils/valid');
 chroma.noHueAsZero = require('./src/utils/nohueaszero');