API Docs for: 1.4.0
Show:

Kiwi.Utils.Color Class

Defined in: src\utils\Color.ts:8
Module: Utils
Parent Module: Kiwi

Available since 1.2.0

Utility class used to make color management more transparent. Color objects hold color and alpha values, and can get or set them in a variety of ways.

Construct this object in one of the following ways.

  • Pass 3 or 4 numbers to determine RGB or RGBA. If the numbers are in the range 0-1, they will be parsed as normalized numbers. If they are in the range 1-255, they will be parsed as 8-bit channels.

  • Pass 3 or 4 numbers followed by the string "hsv" or "hsl" (lowercase) to parse HSV or HSL color space (with optional alpha). HSV and HSL colors may be specified as normalized parameters (0-1), or as an angle (0-360) and two percentages (0-100).

  • Pass a string containing a hexadecimal color with or without alpha (such as "ff8040ff" or "4080ff"). You may prepend "#" or "0x", but they are not necessary and will be stripped.

  • Pass a string containing a CSS color function, such as "rgb(255,255,255)", "rgba( 192, 127, 64, 32 )", "hsl(180, 100, 100)", or "hsla(360, 50, 50, 50)".

  • Pass 1 number to set a grayscale value, or 2 numbers to set grayscale with alpha. These are interpreted as with RGB values.

The color object stores its internal values as normalized RGBA channels. This is the most mathematically useful format, and corresponds with the WebGL color paradigm. When you query the color object's values, such as with "r" or "red" properties, it will return normalized values. You can get values in the 0-255 8-bit range by calling the corresponding x255 value. For example, if r = 1, then r255 = 255.

We advise that you work with normalized colors wherever possible. While the Color object is smart enough to recognise non-normalized ranges in most cases, it cannot tell the difference between 0.5 on a 0-1 scale, and 0.5 on a 0-255 scale. Try to reduce ambiguity by working in normalized color space.

You can get HSV, HSL, and hexadecimal values with the functions "getHsva", "getHsla", and "getHex". By default, these all include an alpha term. You can omit alpha from the getHex result by calling the function with the parameter "false". As getHsva and getHsla return objects rather than strings, you can freely ignore the provided alpha.

You can modify a Color object once created using its properties, methods, or the "set" method as you would use the constructor.

Constructor

Kiwi.Utils.Color

(
  • [...args]
)

Defined in src\utils\Color.ts:8

Available since 1.2.0

Parameters:

  • [...args] Object optional

    Any number of arguments

Methods

_hue2rgb

(
  • p
  • q
  • t
)
private

Method used for computing HSL values. Based on algorithms at http://axonflux.com/handy-rgb-to-hsl-and-rgb-to-hsv-color-model-c

Parameters:

  • p Number
  • q Number
  • t Number

Returns:

number

getHex

(
  • [alpha=true]
)
String public

Returns color as a hexadecimal string

Parameters:

  • [alpha=true] Boolean optional

    Whether to include the alpha

Returns:

String:

A hexadecimal color such as "13579bdf"

getHsla

() Object public

Returns HSL value of the Color. Based on algorithms at http://axonflux.com/handy-rgb-to-hsl-and-rgb-to-hsv-color-model-c

Returns:

Object:

Object with normalized h, s, l, a properties.

getHsva

() Object

Returns HSV value of the Color. Based on algorithms at http://axonflux.com/handy-rgb-to-hsl-and-rgb-to-hsv-color-model-c

Returns:

Object:

Object with normalized h, s, v, a properties.

parseHex

(
  • color
)
Kiwi.Utils.Color public

Parse hexadecimal colors from strings

Parameters:

  • color String

    A hexadecimal color such as "ffffff" (no alpha) or "ffffffff" (with alpha). Also supports "fff" and "ffff" with 4-bit channels.

Returns:

Kiwi.Utils.Color:

This object with the new color set

parseHsl

(
  • h
  • s
  • l
  • a
)
Kiwi.Utils.Color public

Parses HSL value onto the Color. Interprets either normalized values, or H in degrees (0-360) and S and L in % (0-100).

Based on algorithms at http://axonflux.com/handy-rgb-to-hsl-and-rgb-to-hsv-color-model-c

Parameters:

  • h Number

    Hue

  • s Number

    Saturation

  • l Number

    Lightness

  • a Number

    Alpha

Returns:

Kiwi.Utils.Color:

This object with the new color set

parseHsv

(
  • h
  • s
  • v
  • a
)
Kiwi.Utils.Color public

Parses normalized HSV values into the Color. Interprets either normalized values, or H in degrees (0-360) and S and V in % (0-100).

Based on algorithms at http://axonflux.com/handy-rgb-to-hsl-and-rgb-to-hsv-color-model-c

Parameters:

  • h Number

    Hue

  • s Number

    Saturation

  • v Number

    Value

  • a Number

    Alpha

Returns:

Kiwi.Utils.Color:

This object with the new color set

parseString

(
  • color
)
Kiwi.Utils.Color public

Parse colors from strings

Parameters:

  • color String

    A CSS color specification

Returns:

Kiwi.Utils.Color:

This object with the new color set

set

(
  • params
)
Kiwi.Utils.Color public

Set colors from parameters, as in the class description. If you supply invalid parameters, the color will be unchanged.

Parameters:

  • params Object

    Composite parameter object

Returns:

Kiwi.Utils.Color:

This object with the new color set

Properties

_a

Number private

Alpha channel, stored as a normalized value between 0 and 1. This is most compatible with graphics hardware.

Default: 0.5

_b

Number private

Blue channel, stored as a normalized value between 0 and 1. This is most compatible with graphics hardware.

Default: 0.5

_g

Number private

Green channel, stored as a normalized value between 0 and 1. This is most compatible with graphics hardware.

Default: 0.5

_r

Number private

Red channel, stored as a normalized value between 0 and 1. This is most compatible with graphics hardware.

Default: 0.5

a

Number public

Alpha channel. If set to a number in the range 0-1, is interpreted as a normalized color (see aNorm). If set to a number above 1, is interpreted as an 8-bit channel (see a255). If queried, returns a normalized number in the range 0-1.

a255

Number public

Alpha channel, specified as an 8-bit channel in the range 0-255.

alpha

Number public

Alpha channel, alias of a

aNorm

Number public

Alpha channel, stored as a normalized value between 0 and 1.

b

Number public

Blue channel. If set to a number in the range 0-1, is interpreted as a normalized color (see bNorm). If set to a number above 1, is interpreted as an 8-bit channel (see b255). If queried, returns a normalized number in the range 0-1.

b255

Number public

Blue channel, specified as an 8-bit channel in the range 0-255.

blue

Number public

Blue channel, alias of b

bNorm

Number public

Blue channel, stored as a normalized value between 0 and 1.

g

Number public

Green channel. If set to a number in the range 0-1, is interpreted as a normalized color (see gNorm). If set to a number above 1, is interpreted as an 8-bit channel (see g255). If queried, returns a normalized number in the range 0-1.

g255

Number public

Green channel, specified as an 8-bit channel in the range 0-255.

gNorm

Number public

Green channel, stored as a normalized value between 0 and 1.

green

Number public

Green channel, alias of g

r

Number public

Red channel. If set to a number in the range 0-1, is interpreted as a normalized color (see rNorm). If set to a number above 1, is interpreted as an 8-bit channel (see r255). If queried, returns a normalized number in the range 0-1.

r255

Number public

Red channel, specified as an 8-bit channel in the range 0-255.

red

Number public

Red channel, alias of r

rNorm

Number public

Red channel, stored as a normalized value between 0 and 1.