toosoon-utils/lib/extras/colors/ColorScale.d.ts

Utility functions & classes

import type { Range } from '../../types';
import Color, { type ColorInterpolationsParameters, type ColorInterpolation } from './Color';
/**
 * Processing parameter used to modify an input value into a target.
 *   - If the target is a number, the input will be set to its value
 *   - If the target is an array of numbers, the input will be clamped inside the range [min, max]
 *   - If the target is undefined, the input will stay the same
 */
export type ColorScaleProcessingTarget = number | Range | undefined;
/**
 * Parameters used for color scale processing
 */
export type ColorScaleProcessingParameters = {
    /**
     * Processing HSL modifiers
     */
    hsl?: {
        hue?: ColorScaleProcessingTarget;
        saturation?: ColorScaleProcessingTarget;
        lightness?: ColorScaleProcessingTarget;
    };
    /**
     * Processing HSB modifiers
     */
    hsb?: {
        hue?: ColorScaleProcessingTarget;
        saturation?: ColorScaleProcessingTarget;
        brightness?: ColorScaleProcessingTarget;
    };
    /**
     * Processing HCL modifiers
     */
    hcl?: {
        hue?: ColorScaleProcessingTarget;
        chroma?: ColorScaleProcessingTarget;
        luminance?: ColorScaleProcessingTarget;
    };
};
/**
 * Utility class for generating and processing color scales
 *
 * @exports
 * @class ColorScale
 */
export default class ColorScale {
    readonly isColorScale = true;
    readonly type: string;
    /**
     * Array of colors composing this color scale
     */
    colors: Color[];
    [Symbol.iterator](): Iterator<Color>;
    /**
     * Pick an interpolated color from this color scale
     *
     * @param {number} t Normalized time value to interpolate
     * @returns {Color} Interpolated color on this scale
     */
    getColor(t: number): Color;
    /**
     * Set this color scale colors to an array of interpolated colors
     *
     * @param {ColorInterpolation} interpolation Type of interpolation used for generation
     * @param {number} length Amount of colors to generate
     * @param {Color} color1 Start color
     * @param {Color} color2 End color
     * @param {object} [params] Interpolation parameters
     * @returns {this}
     */
    generate<I extends ColorInterpolation>(interpolation: I, length: number, color1: Color, color2: Color, params?: ColorInterpolationsParameters[I]): this;
    /**
     * Set this color scale colors to an array of interpolated colors in the RGB color space
     *
     * @param {number} length Amount of colors to generate
     * @param {Color} color1 Start color
     * @param {Color} color2 End color
     * @param {object} [params]       Interpolation parameters
     * @param {number} [params.power] Interpolation exponent
     * @returns {this}
     */
    generateRgb(length: number, color1: Color, color2: Color, params?: ColorInterpolationsParameters['rgb']): this;
    /**
     * Set this color scale colors to an array of interpolated colors in the HSL color space
     *
     * @param {number} length Amount of colors to generate
     * @param {Color} color1 Start color
     * @param {Color} color2 End color
     * @param {object} [params]                Interpolation parameters
     * @param {number|number[]} [params.power] Interpolation exponent(s) : [h, s, l]
     * @param {string} [params.hueMode]        Hue interpolation mode. Can be 'direct' | 'shortest' | 'longest'
     * @returns {this}
     */
    generateHsl(length: number, color1: Color, color2: Color, params?: ColorInterpolationsParameters['hsl']): this;
    /**
     * Set this color scale colors to an array of interpolated colors in the HSB color space
     *
     * @param {number} length Amount of colors to generate
     * @param {Color} color1 Start color
     * @param {Color} color2 End color
     * @param {object} [params]                Interpolation parameters
     * @param {number|number[]} [params.power] Interpolation exponent(s) : [h, s, b]
     * @param {string} [params.hueMode]        Hue interpolation mode. Can be 'direct' | 'shortest' | 'longest'
     * @returns {this}
     */
    generateHsb(length: number, color1: Color, color2: Color, params?: ColorInterpolationsParameters['hsb']): this;
    /**
     * Set this color scale colors to an array of interpolated colors following HCL Qualitative color palettes algorithm
     *
     * @param {number} length Amount of colors to generate
     * @param {Color} color1 Start color
     * @param {Color} color2 End color
     * @param {object} [params]         Interpolation parameters
     * @param {string} [params.hueMode] Hue interpolation mode. Can be 'direct' | 'shortest' | 'longest'
     * @returns {this}
     */
    generateQualitative(length: number, color1: Color, color2: Color, params?: ColorInterpolationsParameters['qualitative']): this;
    /**
     * Set this color scale colors to an array of interpolated colors following HCL Sequential color palettes algorithm
     *
     * @param {number} length Amount of colors to generate
     * @param {Color} color1 Start color
     * @param {Color} color2 End color
     * @param {number|number[]} [params.power] Interpolation exponent(s) : [c, l]
     * @param {string} [params.hueMode]        Hue interpolation mode. Can be 'direct' | 'shortest' | 'longest'
     * @param {number} [params.chromaMax]      Maximum chroma value
     * @returns {this}
     */
    generateSequential(length: number, color1: Color, color2: Color, params?: ColorInterpolationsParameters['sequential']): this;
    /**
     * Set this color scale colors to an array of interpolated colors following HCL Diverging color palettes algorithm
     *
     * @param {number} length Amount of colors to generate
     * @param {Color} color1 Start color
     * @param {Color} color2 End color
     * @param {object} [params]                Interpolation parameters
     * @param {number|number[]} [params.power] Interpolation exponent(s) : ([c, l])
     * @returns {this}
     */
    generateDiverging(length: number, color1: Color, color2: Color, params?: ColorInterpolationsParameters['diverging']): this;
    /**
     * Process all colors composing this scale
     *
     * @param {ColorScaleProcessingParameters} [params] Processing parameters
     * @returns {this}
     */
    process(params?: ColorScaleProcessingParameters): this;
    /**
     * Amount of colors composing this color scale
     */
    get length(): number;
    /**
     * Generate an array of interpolated colors
     *
     * @param {ColorInterpolation} interpolation Type of interpolation used for generation
     * @param {number} length Amount of colors to generate
     * @param {Color} color1 Start color
     * @param {Color} color2 End color
     * @param {object} [params] Interpolation parameters
     * @returns {Color[]} Generated color scale
     */
    static generate<I extends ColorInterpolation>(interpolation: I, length: number, color1: Color, color2: Color, params?: ColorInterpolationsParameters[I]): Color[];
    /**
     * Generate an array of interpolated colors in the RGB color space
     *
     * @param {number} length Amount of colors to generate
     * @param {Color} color1 Start color
     * @param {Color} color2 End color
     * @param {object} [params]       Interpolation parameters
     * @param {number} [params.power] Interpolation exponent
     * @returns {Color[]} Generated RGB color scale
     */
    static generateRgb(length: number, color1: Color, color2: Color, params?: ColorInterpolationsParameters['rgb']): Color[];
    /**
     * Generate an array of interpolated colors in the HSL color space
     *
     * @param {number} length Amount of colors to generate
     * @param {Color} color1 Start color
     * @param {Color} color2 End color
     * @param {object} [params]                Interpolation parameters
     * @param {number|number[]} [params.power] Interpolation exponent(s) : [h, s, l]
     * @param {string} [params.hueMode]        Hue interpolation mode. Can be 'direct' | 'shortest' | 'longest'
     * @returns {Color[]} Generated HSL color scale
     */
    static generateHsl(length: number, color1: Color, color2: Color, params?: ColorInterpolationsParameters['hsl']): Color[];
    /**
     * Generate an array of interpolated colors in the HSB color space
     *
     * @param {number} length Amount of colors to generate
     * @param {Color} color1 Start color
     * @param {Color} color2 End color
     * @param {object} [params]                Interpolation parameters
     * @param {number|number[]} [params.power] Interpolation exponent(s) : [h, s, b]
     * @param {string} [params.hueMode]        Hue interpolation mode. Can be 'direct' | 'shortest' | 'longest'
     * @returns {Color[]} Generated HSB color scale
     */
    static generateHsb(length: number, color1: Color, color2: Color, params?: ColorInterpolationsParameters['hsb']): Color[];
    /**
     * Generate an array of interpolated colors following HCL Qualitative color palettes algorithm
     *
     * @param {number} length Amount of colors to generate
     * @param {Color} color1 Start color
     * @param {Color} color2 End color
     * @param {object} [params]         Interpolation parameters
     * @param {string} [params.hueMode] Hue interpolation mode. Can be 'direct' | 'shortest' | 'longest'
     * @returns {Color[]} Generated qualitative color scale
     */
    static generateQualitative(length: number, color1: Color, color2: Color, params?: ColorInterpolationsParameters['qualitative']): Color[];
    /**
     * Generate an array of interpolated colors following HCL Sequential color palettes algorithm
     *
     * @param {number} length Amount of colors to generate
     * @param {Color} color1 Start color
     * @param {Color} color2 End color
     * @param {object} [params]                Interpolation parameters
     * @param {number|number[]} [params.power] Interpolation exponent(s) : [c, l]
     * @param {string} [params.hueMode]        Hue interpolation mode. Can be 'direct' | 'shortest' | 'longest'
     * @param {number} [params.chromaMax]      Maximum chroma value
     * @returns {Color[]} Generated sequential color scale
     */
    static generateSequential(length: number, color1: Color, color2: Color, params?: ColorInterpolationsParameters['sequential']): Color[];
    /**
     * Generate an array of interpolated colors following HCL Diverging color palettes algorithm
     *
     * @param {number} length Amount of colors to generate
     * @param {Color} color1 Start color
     * @param {Color} color2 End color
     * @param {object} [params]                Interpolation parameters
     * @param {number|number[]} [params.power] Interpolation exponent(s) : ([c, l])
     * @returns {Color[]} Generated diverging color scale
     */
    static generateDiverging(length: number, color1: Color, color2: Color, params?: ColorInterpolationsParameters['diverging']): Color[];
    /**
     * Process a given value
     *
     * @param {number} value Value to process
     * @param {ColorScaleProcessingTarget} [target] Processing target
     * @returns {number} Processed value
     */
    static processValue(value: number, target: ColorScaleProcessingTarget): number;
    /**
     * Process a given color
     *
     * @param {Color} color Color to process
     * @param {ColorScaleProcessingParameters} [params] Processing parameters
     * @returns {Color} Processed color
     */
    static processColor(color: Color, params?: ColorScaleProcessingParameters): Color;
    /**
     * Process all colors composing a given scale
     *
     * @param {ColorScale} scale Color scale to process
     * @param {ColorScaleProcessingParameters} [params] Processing parameters
     * @returns {ColorScale} Processed color scale
     */
    static process(scale: ColorScale, params?: ColorScaleProcessingParameters): ColorScale;
    private static _getInterpolateFunction;
}