@thi.ng/color 4.1.7 → 5.0.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2021-12-13T10:26:00Z
+- **Last updated**: 2022-03-11T12:13:49Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,36 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+# [5.0.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/color@5.0.0) (2022-03-11)
+
+#### 🛑 Breaking changes
+
+- rename color matrix fns ([00fdc31](https://github.com/thi-ng/umbrella/commit/00fdc31))
+- BREAKING CHANGE: rename color matrix fns
+  - add `Mat` suffix, e.g. `grayscale()` => `grayscaleMat()`
+
+#### 🚀 Features
+
+- add color theme strategies ([22057e5](https://github.com/thi-ng/umbrella/commit/22057e5))
+  - add strategy fns:
+    - `complementaryStrategy()`
+    - `splitComplementaryStrategy()`
+    - `monochromeStrategy()`
+    - `triadicStrategy()`
+    - `tetradicStrategy()`
+    - `squareStrategy()`
+- add variations() generator ([91d760f](https://github.com/thi-ng/umbrella/commit/91d760f))
+- add max chroma LCH fns ([ab4e67a](https://github.com/thi-ng/umbrella/commit/ab4e67a))
+- add/update color ops ([33cb4a1](https://github.com/thi-ng/umbrella/commit/33cb4a1))
+  - add `invert()`, `isRgbGamut()`, `lighten()`, `rotate()` ops
+  - add `tint()`, `tone()`, `shade()` ops
+  - update impls for `isBlack/Gray/White()`
+  - add/re-use internal multimethod dispatch fns
+- update ChannelSpec and hue-based modes ([01d93dc](https://github.com/thi-ng/umbrella/commit/01d93dc))
+  - add `hue` flag for channel spec
+  - update `.clamp()` impl to wrap hue in [0..1] interval
+  - add/update LCH conversion paths
+
 ## [4.1.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/color@4.1.0) (2021-11-17)
 
 #### 🚀 Features

package/README.md

@@ -571,7 +571,7 @@ concatenation (see `concat()`) for more efficient application.
 
 ### Support packages
 
-- [@thi.ng/color-palettes](https://github.com/thi-ng/umbrella/tree/develop/packages/color-palettes) - Collection of 132 image based color palettes
+- [@thi.ng/color-palettes](https://github.com/thi-ng/umbrella/tree/develop/packages/color-palettes) - Collection of 176 image based color palettes
 
 ### Related packages
 
@@ -601,7 +601,7 @@ node --experimental-repl-await
 > const color = await import("@thi.ng/color");
 ```
 
-Package sizes (gzipped, pre-treeshake): ESM: 15.02 KB
+Package sizes (gzipped, pre-treeshake): ESM: 17.43 KB
 
 ## Dependencies
 
@@ -659,4 +659,4 @@ If this project contributes to an academic publication, please cite it as:
 
 ## License
 
-© 2016 - 2021 Karsten Schmidt // Apache Software License 2.0
+© 2016 - 2022 Karsten Schmidt // Apache Software License 2.0

package/analog.d.ts

@@ -7,7 +7,7 @@ export declare const defAnalog: FnU3<Fn3<number, number, IRandom, number>, Fn4<C
  * `delta`. Each channel will be randomized by +/- `delta`, optionally using
  * provided {@link @thi.ng/random#IRandom} PRNG.
  */
-export declare const analog: import("@thi.ng/defmulti/api").MultiFn4<import("@thi.ng/vectors").Vec | null, TypedColor<any>, number, IRandom | undefined, import("@thi.ng/vectors").Vec>;
+export declare const analog: import("@thi.ng/defmulti").MultiFn4<import("@thi.ng/vectors").Vec | null, TypedColor<any>, number, IRandom | undefined, import("@thi.ng/vectors").Vec>;
 /**
  * Similar to {@link analogRGB}. Returns an analog color based on given HSVA
  * color, with each channel randomly varied by given channel-specific delta
@@ -20,13 +20,13 @@ export declare const analog: import("@thi.ng/defmulti/api").MultiFn4<import("@th
  * By default (unless `deltaS`, `deltaV`, `deltaA` are provided) only the hue of
  * the color will be modulated.
  *
- * @param out
- * @param src
- * @param deltaH
- * @param deltaS
- * @param deltaV
- * @param deltaA
- * @param rnd
+ * @param out -
+ * @param src -
+ * @param deltaH -
+ * @param deltaS -
+ * @param deltaV -
+ * @param deltaA -
+ * @param rnd -
  */
 export declare const analogHsv: (out: Color | null, src: ReadonlyColor, deltaH: number, deltaS?: number, deltaV?: number, deltaA?: number, rnd?: IRandom) => import("@thi.ng/vectors").Vec;
 /**
@@ -37,13 +37,13 @@ export declare const analogHsv: (out: Color | null, src: ReadonlyColor, deltaH:
  * @remarks
  * By default the green and blue channel variance will be the same as `deltaR`.
  *
- * @param out
- * @param src
- * @param deltaR
- * @param deltaG
- * @param deltaB
- * @param deltaA
- * @param rnd
+ * @param out -
+ * @param src -
+ * @param deltaR -
+ * @param deltaG -
+ * @param deltaB -
+ * @param deltaA -
+ * @param rnd -
  */
 export declare const analogRgb: (out: Color | null, src: ReadonlyColor, deltaR: number, deltaG?: number, deltaB?: number, deltaA?: number, rnd?: IRandom) => import("@thi.ng/vectors").Vec;
 //# sourceMappingURL=analog.d.ts.map

package/analog.js

@@ -3,6 +3,7 @@ import { clamp01 } from "@thi.ng/math/interval";
 import { fract } from "@thi.ng/math/prec";
 import { SYSTEM } from "@thi.ng/random/system";
 import { setC4 } from "@thi.ng/vectors/setc";
+import { __dispatch1 } from "./internal/dispatch.js";
 import { __ensureAlpha } from "./internal/ensure.js";
 /** @internal */
 const analogU = (x, delta, rnd) => delta !== 0 ? x + rnd.norm(delta) : x;
@@ -26,7 +27,7 @@ const analogNUU = defAnalog(analogN, analogU, analogU);
  * `delta`. Each channel will be randomized by +/- `delta`, optionally using
  * provided {@link @thi.ng/random#IRandom} PRNG.
  */
-export const analog = defmulti((_, src) => src.mode, {}, {
+export const analog = defmulti(__dispatch1, {}, {
     hcy: analogHNN,
     hsi: analogHNN,
     hsl: analogHNN,
@@ -49,13 +50,13 @@ export const analog = defmulti((_, src) => src.mode, {}, {
  * By default (unless `deltaS`, `deltaV`, `deltaA` are provided) only the hue of
  * the color will be modulated.
  *
- * @param out
- * @param src
- * @param deltaH
- * @param deltaS
- * @param deltaV
- * @param deltaA
- * @param rnd
+ * @param out -
+ * @param src -
+ * @param deltaH -
+ * @param deltaS -
+ * @param deltaV -
+ * @param deltaA -
+ * @param rnd -
  */
 export const analogHsv = (out, src, deltaH, deltaS = 0, deltaV = 0, deltaA = 0, rnd = SYSTEM) => setC4(out || src, analogN(src[0], deltaH, rnd, fract), analogN(src[1], deltaS, rnd), analogN(src[2], deltaV, rnd), analogA(src[3], deltaA, rnd));
 /**
@@ -66,12 +67,12 @@ export const analogHsv = (out, src, deltaH, deltaS = 0, deltaV = 0, deltaA = 0,
  * @remarks
  * By default the green and blue channel variance will be the same as `deltaR`.
  *
- * @param out
- * @param src
- * @param deltaR
- * @param deltaG
- * @param deltaB
- * @param deltaA
- * @param rnd
+ * @param out -
+ * @param src -
+ * @param deltaR -
+ * @param deltaG -
+ * @param deltaB -
+ * @param deltaA -
+ * @param rnd -
  */
 export const analogRgb = (out, src, deltaR, deltaG = deltaR, deltaB = deltaR, deltaA = 0, rnd = SYSTEM) => setC4(out || src, analogN(src[0], deltaR, rnd), analogN(src[1], deltaG, rnd), analogN(src[2], deltaB, rnd), analogA(src[3], deltaA, rnd));

package/api/constants.d.ts

@@ -131,7 +131,7 @@ export declare let PC: import("@thi.ng/strings").Stringer<number>;
  * Sets precision for CSS formatted values to `x` significant digits (default:
  * 3).
  *
- * @param x
+ * @param x -
  */
 export declare const setPrecision: (x: number) => void;
 export declare const INV8BIT: number;

package/api/constants.js

@@ -157,7 +157,7 @@ export let PC = percent(3);
  * Sets precision for CSS formatted values to `x` significant digits (default:
  * 3).
  *
- * @param x
+ * @param x -
  */
 export const setPrecision = (x) => {
     FF = float(x);

package/api/system.d.ts

@@ -74,7 +74,7 @@ export declare let CSS_SYSTEM_COLORS: SystemColors;
 /**
  * Merges {@link CSS_SYSTEM_COLORS} w/ new values.
  *
- * @param cols
+ * @param cols -
  */
 export declare const setSystemColors: (cols: Partial<SystemColors>) => SystemColors & Partial<SystemColors>;
 //# sourceMappingURL=system.d.ts.map

package/api/system.js

@@ -22,6 +22,6 @@ export let CSS_SYSTEM_COLORS = {
 /**
  * Merges {@link CSS_SYSTEM_COLORS} w/ new values.
  *
- * @param cols
+ * @param cols -
  */
 export const setSystemColors = (cols) => Object.assign(CSS_SYSTEM_COLORS, cols);

package/api.d.ts

@@ -29,9 +29,16 @@ export interface IColor {
 export interface ChannelSpec {
     /**
      * Acceptable value range for this channel. Used by {@link TypedColor.clamp}.
+     *
      * @defaultValue [0,1]
      */
     range?: Range;
+    /**
+     * If true, this channel is used to store normalized hue values.
+     *
+     * @defaultValue false
+     */
+    hue?: boolean;
 }
 export interface ColorSpec<M extends ColorMode, K extends string> {
     mode: M;
@@ -71,10 +78,10 @@ export interface ColorFactory<T extends TypedColor<any>> {
      * `buf` is given, the returned color will wrap `buf` from given `index`
      * (default: 0) and `stride` step size (default: 1).
      *
-     * @param rnd
-     * @param buf
-     * @param index
-     * @param stride
+     * @param rnd -
+     * @param buf -
+     * @param index -
+     * @param stride -
      */
     random(rnd?: IRandom, buf?: NumericArray, index?: number, stride?: number): T;
     /**
@@ -140,13 +147,13 @@ export interface TypedColor<T> extends IColor, IDeref<Color>, IEqualsDelta<T>, I
      * color type (usually [0..1] interval). Alpha channel will remain
      * untouched.
      *
-     * @param rnd
+     * @param rnd -
      */
     randomize(rnd?: IRandom): this;
     /**
      * Copies `src` into this color's array.
      *
-     * @param src
+     * @param src -
      */
     set(src: ReadonlyColor): this;
     /**

package/color-range.d.ts

@@ -23,8 +23,8 @@ export declare const COLOR_RANGES: Record<ColorRangePreset, ColorRange>;
  *
  * A custom PRNG can be defined via the `rnd` option (default: `Math.random`).
  *
- * @param range
- * @param opts
+ * @param range -
+ * @param opts -
  */
 export declare const colorFromRange: (range: ColorRange | keyof typeof COLOR_RANGES, opts?: Partial<Pick<ColorRangeOpts, "variance" | "eps" | "rnd">> | undefined) => LCH;
 /**
@@ -32,8 +32,8 @@ export declare const colorFromRange: (range: ColorRange | keyof typeof COLOR_RAN
  * sequence of random colors based on given range, base color (optional) and
  * other opts. Use `num` option to limit number of results.
  *
- * @param range
- * @param opts
+ * @param range -
+ * @param opts -
  */
 export declare function colorsFromRange(range: ColorRange | keyof typeof COLOR_RANGES, opts?: Partial<ColorRangeOpts>): Generator<LCH, void, unknown>;
 /**
@@ -61,8 +61,8 @@ export declare function colorsFromRange(range: ColorRange | keyof typeof COLOR_R
  * )]
  * ```
  *
- * @param parts
- * @param opts
+ * @param parts -
+ * @param opts -
  */
 export declare function colorsFromTheme(parts: (ColorThemePart | ColorThemePartTuple)[], opts?: Partial<Without<ColorRangeOpts, "base">>): Generator<LCH, void, unknown>;
 //# sourceMappingURL=color-range.d.ts.map

package/color-range.js

@@ -116,8 +116,8 @@ const $rnd = (ranges, rnd) => rnd.minmax(...ranges[rnd.int() % ranges.length]);
  *
  * A custom PRNG can be defined via the `rnd` option (default: `Math.random`).
  *
- * @param range
- * @param opts
+ * @param range -
+ * @param opts -
  */
 export const colorFromRange = (range, opts) => {
     range = {
@@ -165,8 +165,8 @@ export const colorFromRange = (range, opts) => {
  * sequence of random colors based on given range, base color (optional) and
  * other opts. Use `num` option to limit number of results.
  *
- * @param range
- * @param opts
+ * @param range -
+ * @param opts -
  */
 export function* colorsFromRange(range, opts = {}) {
     let num = opts.num != undefined ? opts.num : Infinity;
@@ -241,8 +241,8 @@ const themePartFromString = (part) => ((COLOR_RANGES[part]
  * )]
  * ```
  *
- * @param parts
- * @param opts
+ * @param parts -
+ * @param opts -
  */
 export function* colorsFromTheme(parts, opts = {}) {
     let { num, variance, rnd } = { ...DEFAULT_OPTS, ...opts };

package/convert.d.ts

@@ -4,7 +4,7 @@ export declare const CONVERSIONS: Partial<Record<ColorMode, Conversions>>;
  * Registers conversions for given {@link ColorSpec}. Called by
  * {@link defColor}.
  *
- * @param spec
+ * @param spec -
  *
  * @internal
  */

package/convert.js

@@ -6,7 +6,7 @@ export const CONVERSIONS = {};
  * Registers conversions for given {@link ColorSpec}. Called by
  * {@link defColor}.
  *
- * @param spec
+ * @param spec -
  *
  * @internal
  */

package/cosine-gradients.d.ts

@@ -15,8 +15,8 @@ export declare const COSINE_GRADIENTS: Record<CosineGradientPreset, CosGradientS
  * Computes a single linear RGBA color for given gradient spec and normalized
  * position `t` (in [0..1] interval).
  *
- * @param spec
- * @param t
+ * @param spec -
+ * @param t -
  */
 export declare const cosineColor: (spec: CosGradientSpec, t: number) => Color;
 /**
@@ -28,9 +28,9 @@ export declare const cosineColor: (spec: CosGradientSpec, t: number) => Color;
  * For CSS/SVG use cases you could use {@link srgba} as transformation function
  * to not convert, but reinterpret & wrap raw color values as SRGBA.
  *
- * @param n
- * @param spec
- * @param tx
+ * @param n -
+ * @param spec -
+ * @param tx -
  */
 export declare const cosineGradient: (n: number, spec: CosGradientSpec, tx?: FnU<import("@thi.ng/vectors").Vec, import("@thi.ng/vectors").Vec> | undefined) => Color[];
 /**

package/cosine-gradients.js

@@ -158,8 +158,8 @@ export const COSINE_GRADIENTS = {
  * Computes a single linear RGBA color for given gradient spec and normalized
  * position `t` (in [0..1] interval).
  *
- * @param spec
- * @param t
+ * @param spec -
+ * @param t -
  */
 export const cosineColor = (spec, t) => transduce(map(([a, b, c, d]) => clamp01(a + b * Math.cos(TAU * (c * t + d)))), push(), 
 // @ts-ignore
@@ -173,9 +173,9 @@ zip(...spec));
  * For CSS/SVG use cases you could use {@link srgba} as transformation function
  * to not convert, but reinterpret & wrap raw color values as SRGBA.
  *
- * @param n
- * @param spec
- * @param tx
+ * @param n -
+ * @param spec -
+ * @param tx -
  */
 export const cosineGradient = (n, spec, tx) => transduce(comp(map(partial(cosineColor, spec)), tx ? map(tx) : noop()), push(), normRange(n - 1));
 /**

package/css/parse-css.d.ts

@@ -33,7 +33,7 @@ import { IParsedColor } from "../api.js";
  * and {@link srgb} for non-linear (gamma encoded) RGB colors (CSS uses sRGB by
  * default).
  *
- * @param src
+ * @param src -
  */
 export declare const parseCss: (src: string | IDeref<string>) => IParsedColor;
 export declare const parseHex: (src: string) => number;

package/css/parse-css.js

@@ -43,7 +43,7 @@ import { intArgb32Srgb } from "../int/int-srgb.js";
  * and {@link srgb} for non-linear (gamma encoded) RGB colors (CSS uses sRGB by
  * default).
  *
- * @param src
+ * @param src -
  */
 export const parseCss = (src) => {
     src = (isString(src) ? src : src.deref()).toLowerCase();

package/defcolor.js

@@ -4,6 +4,7 @@ import { isNumber } from "@thi.ng/checks/is-number";
 import { isString } from "@thi.ng/checks/is-string";
 import { illegalArgs } from "@thi.ng/errors/illegal-arguments";
 import { EPS } from "@thi.ng/math/api";
+import { fract } from "@thi.ng/math/prec";
 import { vector } from "@thi.ng/strings/vector";
 import { mapStridedBuffer } from "@thi.ng/vectors/buffer";
 import { clamp4 } from "@thi.ng/vectors/clamp";
@@ -33,6 +34,7 @@ export const defColor = (spec) => {
     const minR = set4([], min);
     const maxR = set4([], max);
     minR[numChannels - 1] = 1;
+    const hueChanID = order.findIndex((id) => !!channels[id].hue);
     const $Color = class {
         constructor(buf, offset = 0, stride = 1) {
             this.offset = offset;
@@ -72,7 +74,9 @@ export const defColor = (spec) => {
             return set4(this, src);
         }
         clamp() {
-            return clamp4(null, this, min, max);
+            hueChanID >= 0 && (this[hueChanID] = fract(this[hueChanID]));
+            clamp4(null, this, min, max);
+            return this;
         }
         eqDelta(o, eps = EPS) {
             return eqDelta4(this, o, eps);

package/distance.d.ts

@@ -4,67 +4,67 @@ import type { ColorDistance } from "./api.js";
  * Higher order function. Returns {@link ColorDistance} function for given color
  * channel ID.
  *
- * @param id
+ * @param id -
  */
 export declare const distChannel: (id: number) => ColorDistance;
 /**
  * Computes distance between two HSV colors, i.e. the eucledian distance between
  * points in a cyclinder.
  *
- * @param a
- * @param b
+ * @param a -
+ * @param b -
  */
 export declare const distHsv: ColorDistance;
 /**
  * Computes difference in saturation between two HSV colors.
  *
- * @param a
- * @param b
+ * @param a -
+ * @param b -
  */
 export declare const distHsvSat: ColorDistance<ReadonlyVec>;
 /**
  * Computes difference in brightness between two HSV or two HSL colors.
  *
- * @param a
- * @param b
+ * @param a -
+ * @param b -
  */
 export declare const distHsvLuma: ColorDistance<ReadonlyVec>;
 /**
  * Computes eucledian distance between two colors. Only the first 3 color
  * channels will be considered.
  *
- * @param a
- * @param b
+ * @param a -
+ * @param b -
  */
 export declare const distEucledian3: ColorDistance;
 export declare const distEucledian4: ColorDistance;
 /**
  * Computes difference in luminance between two RGB colors.
  *
- * @param a
- * @param b
+ * @param a -
+ * @param b -
  */
 export declare const distRgbLuma: ColorDistance;
 export declare const distSrgbLuma: ColorDistance;
 /**
  * Computes red difference between two RGB colors.
  *
- * @param a
- * @param b
+ * @param a -
+ * @param b -
  */
 export declare const distRgbRed: ColorDistance<ReadonlyVec>;
 /**
  * Computes green difference between two RGB colors.
  *
- * @param a
- * @param b
+ * @param a -
+ * @param b -
  */
 export declare const distRgbGreen: ColorDistance<ReadonlyVec>;
 /**
  * Computes blue difference between two RGB colors.
  *
- * @param a
- * @param b
+ * @param a -
+ * @param b -
  */
 export declare const distRgbBlue: ColorDistance<ReadonlyVec>;
 /**

package/distance.js

@@ -10,15 +10,15 @@ const { abs, cos, hypot, sin, sqrt } = Math;
  * Higher order function. Returns {@link ColorDistance} function for given color
  * channel ID.
  *
- * @param id
+ * @param id -
  */
 export const distChannel = (id) => (a, b) => abs(a[id] - b[id]);
 /**
  * Computes distance between two HSV colors, i.e. the eucledian distance between
  * points in a cyclinder.
  *
- * @param a
- * @param b
+ * @param a -
+ * @param b -
  */
 export const distHsv = (a, b) => {
     const aa = cossin(a[0] * TAU, a[1]);
@@ -28,53 +28,53 @@ export const distHsv = (a, b) => {
 /**
  * Computes difference in saturation between two HSV colors.
  *
- * @param a
- * @param b
+ * @param a -
+ * @param b -
  */
 export const distHsvSat = distChannel(1);
 /**
  * Computes difference in brightness between two HSV or two HSL colors.
  *
- * @param a
- * @param b
+ * @param a -
+ * @param b -
  */
 export const distHsvLuma = distChannel(2);
 /**
  * Computes eucledian distance between two colors. Only the first 3 color
  * channels will be considered.
  *
- * @param a
- * @param b
+ * @param a -
+ * @param b -
  */
 export const distEucledian3 = dist3;
 export const distEucledian4 = dist4;
 /**
  * Computes difference in luminance between two RGB colors.
  *
- * @param a
- * @param b
+ * @param a -
+ * @param b -
  */
 export const distRgbLuma = (a, b) => abs(luminanceRgb(a) - luminanceRgb(b));
 export const distSrgbLuma = (a, b) => abs(luminanceSrgb(a) - luminanceSrgb(b));
 /**
  * Computes red difference between two RGB colors.
  *
- * @param a
- * @param b
+ * @param a -
+ * @param b -
  */
 export const distRgbRed = distChannel(0);
 /**
  * Computes green difference between two RGB colors.
  *
- * @param a
- * @param b
+ * @param a -
+ * @param b -
  */
 export const distRgbGreen = distChannel(1);
 /**
  * Computes blue difference between two RGB colors.
  *
- * @param a
- * @param b
+ * @param a -
+ * @param b -
  */
 export const distRgbBlue = distChannel(1);
 const H6 = 6 * DEG2RAD;

package/gradients.d.ts

@@ -37,7 +37,7 @@ import type { GradientOpts } from "./api/gradients.js";
  * );
  * ```
  *
- * @param opts
+ * @param opts -
  */
 export declare const multiColorGradient: <T extends TypedColor<any>>(opts: GradientOpts<T>) => T[];
 /**
@@ -48,7 +48,7 @@ export declare const multiColorGradient: <T extends TypedColor<any>>(opts: Gradi
  * Intended use case for this function: 1D texturemap/tonemap generation, e.g.
  * for dataviz etc. Also @see {@link cosineGradientBuffer}.
  *
- * @param opts
+ * @param opts -
  * @param buffer - target buffer/array
  * @param offset - start index (default: 0)
  * @param cstride - channel stride (default: 1)

package/gradients.js

@@ -37,7 +37,7 @@ import { mix as $mix } from "./mix.js";
  * );
  * ```
  *
- * @param opts
+ * @param opts -
  */
 export const multiColorGradient = (opts) => [...gradient(opts)];
 /**
@@ -48,7 +48,7 @@ export const multiColorGradient = (opts) => [...gradient(opts)];
  * Intended use case for this function: 1D texturemap/tonemap generation, e.g.
  * for dataviz etc. Also @see {@link cosineGradientBuffer}.
  *
- * @param opts
+ * @param opts -
  * @param buffer - target buffer/array
  * @param offset - start index (default: 0)
  * @param cstride - channel stride (default: 1)