docs(color): update readme (color sorting)

alfu32 · Jan 2, 2021 · ce79843 · ce79843
1 parent 75164aa
commit ce79843
Show file tree

Hide file tree

Showing 3 changed files with 38 additions and 0 deletions.
diff --git a/assets/color/swatches-ex02.svg b/assets/color/swatches-ex02.svg
diff --git a/packages/color/README.md b/packages/color/README.md
@@ -15,6 +15,7 @@ For the Clojure version, please visit: [thi.ng/color-clj](https://thi.ng/color-c
   - [Color spaces / modes](#color-spaces--modes)
     - [Class wrappers](#class-wrappers)
   - [Color theme generation](#color-theme-generation)
+  - [Color sorting](#color-sorting)
   - [RGBA transformations](#rgba-transformations)
   - [RGBA Porter-Duff compositing](#rgba-porter-duff-compositing)
   - [Cosine gradients](#cosine-gradients)
@@ -188,6 +189,24 @@ writeFileSync("export/swatches-ex01.svg", serialize(doc));
 
 ![example result color swatches](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/color/swatches-ex01.svg)
 
+### Color sorting
+
+The `sortColors()` function can be used to sort an array of colors using
+arbitrary sort criteria. The following comparators are bundled:
+
+- `selectChannel(i)` - sort by channel
+- `proximityHSV(target)` - sort by distance to target color (HSV colors)
+- `proximityRGB(target)` - sort by distance to target color (RGB colors)
+
+```ts
+// (see above example)
+const colors = [...colorsFromTheme(theme, { num: 200, variance: 0.05 })];
+
+sortColors(colors, proximityHSV([0,1,0.5]));
+```
+
+![sorted color swatches](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/color/swatches-ex02.svg)
+
 ### RGBA transformations
 
 RGBA [color matrix

diff --git a/packages/color/tpl.readme.md b/packages/color/tpl.readme.md
@@ -171,6 +171,24 @@ writeFileSync("export/swatches-ex01.svg", serialize(doc));
 
 ![example result color swatches](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/color/swatches-ex01.svg)
 
+### Color sorting
+
+The `sortColors()` function can be used to sort an array of colors using
+arbitrary sort criteria. The following comparators are bundled:
+
+- `selectChannel(i)` - sort by channel
+- `proximityHSV(target)` - sort by distance to target color (HSV colors)
+- `proximityRGB(target)` - sort by distance to target color (RGB colors)
+
+```ts
+// (see above example)
+const colors = [...colorsFromTheme(theme, { num: 200, variance: 0.05 })];
+
+sortColors(colors, proximityHSV([0,1,0.5]));
+```
+
+![sorted color swatches](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/color/swatches-ex02.svg)
+
 ### RGBA transformations
 
 RGBA [color matrix