Class Color

An immutable representation of a colour in the sRGB (Standard Red Green Blue) space.

Each component of a Color is described by a number between 0 and 1 inclusive. For example, (0.5, 0, 0) would yield pure red at half the possible brightness. An alpha (opacity) level can optionally be specified as a fourth component, with 0 meaning fully transparent and 1 meaning fully opaque.

Color instances are immutable: once created, the component values of a particular Color can't be changed.

Example: Convert a CSS color name to its hex notation equivalent

let c = micd.Color.fromCss("pink");
console.log(c.toHexString());

Hierarchy

  • Color

Index

Constructors

constructor

  • new Color(red: number, green: number, blue: number, alpha?: number): Color
  • Creates a new colour with the specified levels of red, green, blue, and alpha (opacity). Arguments are clamped, if necessary, to the 0 to 1 range.

    throws

    TypeError If arguments are missing or not numbers.

    Parameters

    • red: number

      The amount of red light, from 0 to 1.

    • green: number

      The amount of green light, from 0 to 1.

    • blue: number

      The amount of blue light, from 0 to 1.

    • Optional alpha: number

      The opacity of the colour, from 0 to 1.

    Returns Color

Properties

Readonly alpha

alpha: number

The alpha value (opacity) of this colour, from 0 (transparent) to 1 (opaque) inclusive.

Readonly blue

blue: number

The amount of blue in this colour, from 0 (none) to 1 (maximum) inclusive.

Readonly green

green: number

The amount of green in this colour, from 0 (none) to 1 (maximum) inclusive.

Readonly red

red: number

The amount of red in this colour, from 0 (none) to 1 (maximum) inclusive.

Methods

derive

  • derive(hueRotation: number, saturationFactor: number, valueFactor: number, alphaFactor: number): Color
  • Returns a new Color instance whose color is derived from this color by rotating its hue and multiplying its saturation, value, and alpha by the specified factors. This Color will be converted to HSV, adjusted by the specified factors, clamped to valid values, and then returned as a new Color.

    Parameters

    • hueRotation: number

      The amount to rotate the hue by, measured in rotations. Use 0 for no change, 0.5 to use the opposite hue.

    • saturationFactor: number

      The saturation adjustment factor, from 0 to 1. Use 1 for no change, 0 to convert to greyscale.

    • valueFactor: number

      The value adjustment factor. Use 1 to retain the current brightness.

    • alphaFactor: number

      The opacity of the colour, from 0 to 1. Use 1 for no change.

    Returns Color

    A Color instance representing the same color.

layer

  • layer(topColor: Color, newAlpha?: number): Color
  • Mixes this color with another color as if by painting the specified top color over this color. If the top color is opaque, it will replace this color. Otherwise the colors will be blended in proportion to the top color's alpha value.

    see

    withAlpha

    Parameters

    • topColor: Color

      The color to mix in by “painting over” this color.

    • Optional newAlpha: number

      If specified, this value becomes the alpha value of the new color; otherwise the alpha value of the new color is the same as this color (the bottom color).

    Returns Color

    A new color that simulates layering the specified color over this color.

mix

  • Mixes this color with another color, returning the new, combined color. The alpha values of the two input colors are ignored. The result will have red, green, and blue values at the midpoints between the two colors and an alpha of 1 (fully opaque).

    Parameters

    • withColor: Color

      The color to mix this color with.

    Returns Color

    An opaque color halfway between this color and the specified color.

toBits

  • toBits(): number
  • Returns the value of the color as a 32-bit unsigned integer.

    Returns number

    The color in RGBA32 format.

toHexString

  • toHexString(): string
  • Returns a string representation of this colour using CSS hexadecimal notation. For example, a colour with red 1, green 0.75, blue 0.5, and opacity 0.25 might return the string "#ffbf8040".

    Returns string

    A CSS hexadecimal string that describes this color.

toHsv

  • toHsv(): [number, number, number]
  • Returns the value of the color in the HSV (hue-saturation-value) color space as an array in hue, saturation, value order.

    Returns [number, number, number]

toString

  • toString(): string
  • Returns a string representation of this colour using CSS rgb() or rgba() notation. For example, a colour with red 1, green 0.75, blue 0.5, and alpha 0.25 might return the string "rgba(255,191,128,0.25)".

    Returns string

    An rgb(a) string that describes this color.

withAlpha

  • withAlpha(newAlpha?: number): Color
  • Returns a new color identical to this color but with a different translucency (alpha value).

    Parameters

    • Optional newAlpha: number

      The new alpha value. The default is 1 (fully opaque).

    Returns Color

    A color identical to this color except that its alpha value is as specified.

Static fromBits

  • fromBits(rgba32: number): Color
  • Creates a Color instance from the specified 32-bit unsigned integer.

    Parameters

    • rgba32: number

      The color in RGBA32 format.

    Returns Color

    A Color instance representing the same color.

Static fromBytes

  • fromBytes(redByte: number, greenByte: number, blueByte: number, alphaByte?: number): Color
  • Creates a Color instance from the given byte values. If alpha is not specified, it is treated as 255 (fully opaque).

    throws

    TypeError If arguments are missing or not numbers.

    Parameters

    • redByte: number

      The amount of red light, from 0 to 255.

    • greenByte: number

      The amount of green light, from 0 to 255.

    • blueByte: number

      The amount of blue light, from 0 to 255.

    • Optional alphaByte: number

      The opacity of the colour, from 0 to 255.

    Returns Color

    A Color instance representing the described colour.

Static fromCss

  • fromCss(cssColorValue: string): Color
  • Creates a Color instance from the specified CSS Color value. Any notation recognized by the browser is acceptable, including functional (e.g., "rgba(176, 224, 230, 0.87)", "hsl(270deg, 60%, 70%)""), hexadecimal (e.g., "#b0e0e6"), and keywords (e.g., "powderblue"). As with theme colours, "hexa" notation (#rrggbbaa and #rgba) is allowed even when not supported by the browser. If the specified string is not a valid colour, null is returned instead.

    Parameters

    • cssColorValue: string

      A (possible) CSS Color value.

    Returns Color

    A Color instance representing the same color, or null if the string was not a valid.

Static fromHsv

  • fromHsv(hue: number, saturation: number, value: number, alpha?: number): Color
  • Creates a Color instance from the given values in the HSV (hue-saturation-value) color space. If alpha is not specified, it is treated as 1 (fully opaque).

    Parameters

    • hue: number

      The hue, as an angle measured in rotations.

    • saturation: number

      The saturation, from 0 to 1.

    • value: number

      The value (roughly, the admixture of black or white), from 0 to 1.

    • Optional alpha: number

      The opacity of the colour, from 0 to 1.

    Returns Color

    A Color instance representing the same color.

Static hsvToRgb

  • hsvToRgb(hue: number, saturation: number, value: number): [number, number, number]
  • Converts a colour value from the HSV (hue-saturation-value) color space to the RGB (red-green-blue) color space. The saturation and value arguments will be clamped, if necessary, to the 0 to 1 range. The hue value can be any number. The whole part is discarded and the fraction bits are used to describe an angle around a color wheel. (Multiply the hue by 360 to convert to degrees.)

    throws

    TypeError If arguments are missing or not numbers.

    see

    rgbToHsv

    Parameters

    • hue: number

      The hue, as an angle measured in rotations.

    • saturation: number

      The saturation, from 0 to 1.

    • value: number

      The value (roughly, the admixture of black or white), from 0 to 1.

    Returns [number, number, number]

    An array of the converted color components in red, green, blue order.

Static rgbToHsv

  • rgbToHsv(red: number, green: number, blue: number): [number, number, number]
  • Converts a colour value from the RGB (red-green-blue) color space to the HSV (hue-saturation-value) color space. The arguments will be clamped, if necessary, to the 0 to 1 range.

    throws

    TypeError If arguments are missing or not numbers.

    see

    hsvToRgb

    Parameters

    • red: number

      The amount of red light, from 0 to 1.

    • green: number

      The amount of green light, from 0 to 1.

    • blue: number

      The amount of blue light, from 0 to 1.

    Returns [number, number, number]

    An array of the converted color components in hue, saturation, value order.

Static rgbaToCss

  • rgbaToCss(red: number, green: number, blue: number, alpha?: number): string
  • Converts an RGB or RGBA color description to a string in CSS rgb() or rgba() notation.

    throws

    TypeError If arguments are missing or not numbers.

    see

    toString

    Parameters

    • red: number

      The amount of red light, from 0 to 1.

    • green: number

      The amount of green light, from 0 to 1.

    • blue: number

      The amount of blue light, from 0 to 1.

    • Optional alpha: number

      The opacity of the colour, from 0 to 1.

    Returns string

    A CSS rgb(a) string that describes the color.

Static rgbaToHexString

  • rgbaToHexString(red: number, green: number, blue: number, alpha?: number): any
  • Converts an RGB or RGBA color description to a string in CSS hexadecimal notation.

    throws

    TypeError If arguments are missing or not numbers.

    see

    toHexString

    Parameters

    • red: number

      The amount of red light, from 0 to 1.

    • green: number

      The amount of green light, from 0 to 1.

    • blue: number

      The amount of blue light, from 0 to 1.

    • Optional alpha: number

      The opacity of the colour, from 0 to 1.

    Returns any

This API is still under development and is subject to change. Copyright © Math I Can Do Solutions Incorporated and/or its licensors.