ColorDef Class

An immutable integer representation of a color.

Colors are stored as 4 components: Red, Blue, Green, and Transparency (0=fully opaque). Each is an 8-bit integer between 0-255.

Much confusion results from attempting to interpret those 4 one-byte values as a 4 byte integer. There are generally two sources of confusion:

  1. The ordering of the Red, Green, Blue bytes; and
  2. Whether to specify transparency or opacity (sometimes referred to as "alpha").

Generally, iModel.js prefers to use 0xTTBBGGRR (red in the low byte. 0==fully opaque in high byte), but this class provides methods to convert to 0xRRGGBB (see ColorDef.getRgb) and 0xAABBGGRR (red in the low byte, 0==fully transparent in high byte. see ColorDef.getAbgr).

The ColorDef.create method also accepts strings in the common HTML formats.

ColorDef is immutable. To obtain a modified copy of a ColorDef, use methods like ColorDef.adjustedForContrast, ColorDef.inverse, or ColorDef.withTransparency. For example:

 const semiTransparentBlue = ColorDef.blue.withTransparency(100);

Methods

Name Description
adjustedForContrast(other: ColorDef, alpha?: number): ColorDef Create a new ColorDef that is adjusted from this ColorDef for maximum contrast against another color.  
equals(other: ColorDef): boolean True if the value of this ColorDef is the same as another ColorDef.  
getAbgr(): number Get the value of the color as a number in 0xAABBGGRR format (i.e.  
getAlpha(): number Get the alpha value for this ColorDef.  
getRgb(): number Get the RGB value of the color as a number in 0xRRGGBB format (i.e blue is in the low byte).  
getTransparency(): number Get the transparency value for this ColorDef (inverse of alpha).  
inverse(): ColorDef Create a new ColorDef that is the inverse (all colors set to 255 - this) of this color.  
lerp(color2: ColorDef, weight: number): ColorDef Create a ColorDef that is the linear interpolation of this ColorDef and another ColorDef, using a weighting factor.  
toHSL(): HSLColor Create an HSLColor from this ColorDef  
toHSV(): HSVColor Create an HSVColor from this ColorDef  
toHexString(): string Convert this ColorDef to a string in the form "#rrggbb" where values are hex digits of the respective colors  
toJSON(): ColorDefProps Convert this ColorDef to a 32 bit number representing the 0xTTBBGGRR value  
toRgbString(): string Convert this ColorDef to a string in the form "rgb(r,g,b)" where values are decimal digits of the respective colors.  
toRgbaString(): string Convert this ColorDef to a string in the form "rgba(r,g,b,a)" where color values are decimal digits and a is a fraction  
withAlpha(alpha: number): ColorDef Return a copy of this ColorDef with the specified alpha component.  
withTransparency(transparency: number): ColorDef Create a copy of this ColorDef with the specified transparency.  
computeTbgrFromComponents(red: number, green: number, blue: number, transparency?: number): number Static Compute the 0xTTBBGGRR value corresponding to the specified Red, Green, Blue, Transparency components.  
computeTbgrFromHSL(h: number, s: number, l: number, transparency: number = 0): number Static Compute the 0xTTBBGGRR color corresponding to the specified hue, saturation, lightness values.  
computeTbgrFromString(val: string): number Static Compute the 0xTTBBGGRR value corresponding to a string representation of a color.  
create(val?: string | ColorDefProps): ColorDef Static Create a new ColorDef.  
from(red: number, green: number, blue: number, transparency?: number): ColorDef Static Create a ColorDef from Red, Green, Blue, Transparency values.  
fromHSL(h: number, s: number, l: number, transparency: number = 0): ColorDef Static Create a ColorDef from hue, saturation, lightness values  
fromHSV(hsv: HSVColor, transparency: number = 0): ColorDef Static Create a ColorDef from an HSVColor  
fromJSON(json?: ColorDefProps): ColorDef Static Create a new ColorDef from a json object.  
fromString(val: string): ColorDef Static Create a ColorDef from a string representation.  
fromTbgr(tbgr: number): ColorDef Static Create a ColorDef from its 0xTTBBGGRR representation.  
getAbgr(tbgr: number): number Static Get the value of a 0xTTBBGGRR color as a number in 0xAABBGGRR format (i.e.  
getAlpha(tbgr: number): number Static Extract the alpha value from a 0xTTBBGGRR color.  
getColors(tbgr: number): object Static Get the r,g,b,t values encoded in an 0xTTBBGGRR value.  
getName(tbgr: number): string | undefined Static Obtain the name of the color in the ColorByName list associated with the specified 0xTTBBGGRR value, or undefined if no such named color exists.  
getRgb(tbgr: number): number Static Get the RGB value of the 0xTTBBGGRR color as a number in 0xRRGGBB format (i.e blue is in the low byte).  
getTransparency(tbgr: number): number Static Extract the transparency component from a 0xTTBBGGRR color as an integer between 0-255..  
inverse(tbgr: number): number Static Return a 0xTTBBGGRR color whose color components are the inverse of the input color.  
isOpaque(tbgr: number): boolean Static True if the specified 0xTTBBGGRR color is fully opaque.  
lerp(tbgr1: number, tbgr2: number, weight: number): number Static Interpolate between two 0xTTBBGGRR colors using a weighting factor.  
toHexString(tbgr: number): string Static Convert the 0xTTBBGGRR value to a string in the form "#rrggbb".  
toRgbString(tbgr: number): string Static Convert the 0xTTBBGGRR color to a string in the form "rgb(r,g,b)" where each component is specified in decimal.  
toRgbaString(tbgr: number): string Static Convert the 0xTTBBGGRR color to a string of the form "rgba(r,g,b,a)" where the color components are specified in decimal and the alpha component is a fraction.  
withAlpha(tbgr: number, alpha: number): number Static Return a color equivalent to the specified 0xTTBBGGRR but with modified alpha component.  
withTransparency(tbgr: number, transparency: number): number Static Compute the 0xTTBBGGRR value of the specified color and transparency.  

Properties

Name Type Description
black Static ColorDef pure black  
blue Static ColorDef pure blue  
colors Accessor ReadOnly object Get the r,g,b,t values from this ColorDef.  
green Static ColorDef pure green  
isOpaque Accessor ReadOnly boolean True if this ColorDef is fully opaque.  
name Accessor ReadOnly string | undefined The "known name" for this ColorDef.  
red Static ColorDef pure red  
tbgr Accessor ReadOnly number The color value of this ColorDef as an integer in the form 0xTTBBGGRR (red in the low byte)  
white Static ColorDef pure white  

Defined in

Last Updated: 23 April, 2020