Skip to main content

Colors in Bitbybit

Color category icon

View Full Source & Details on GitHub

bitbybit.color builds colors, converts them between the forms the library uses, reads single channels and inverts them.

Two ways to write a color​

  • Hex text, such as #ff5733: six hex digits for red, green and blue. This is what materials and drawing options take, and they read six digits only. The functions on this page also read the short form #f53, where each digit stands for a pair, so #f53 is #ff5533.
  • An object { r, g, b }, or { r, g, b, a } with an opacity a from 0 (transparent) to 1 (opaque). Its channels run either from 0 to 255 or from 0 to 1, and the functions that convert say which range they read or write.

Giving a color a name​

These functions return their input unchanged. They exist so that a color can be picked once in Rete or Blockly, named and reused:

  • hexColor for hex text;
  • rgb255Color and rgb1Color for { r, g, b } with channels from 0 to 255 or from 0 to 1;
  • rgba255Color (color channels from 0 to 255, a from 0 to 1) and rgba1Color (every channel from 0 to 1).

rgbAtomic255Color and rgbAtomic1Color build an { r, g, b } object from three separate numbers.

Converting​

  • hexToRgb reads hex text into { r, g, b } with channels from 0 to 255: #FF5733 gives { r: 255, g: 87, b: 51 }. The # is optional and the short form reads as its pairs, so #f53 gives { r: 255, g: 85, b: 51 }; anything else stops the script with an error.

  • hexToRgbMapped does the same and remaps the channels so that 0 becomes from and 255 becomes to. With from 0 and to 1, #FF5733 gives { r: 1, g: 0.341, b: 0.2 }.

  • rgbToHex writes three channel values as hex text, and rgbObjToHex does the same from an { r, g, b } object. min and max say which range the values use; with max 1, channels from 0 to 1 are remapped to 0 to 255 and rounded first, so { r: 1, g: 0.5, b: 0.2 } gives #ff8033. rgbToHex also holds each channel between 0 and 255 after rounding, so a value past the range writes ff or 00 rather than a broken color.

  • hexToRgba writes hex text with an opacity alpha as a CSS color, for a style that lets what is behind it show through: #ff5733 with alpha 0.5 gives rgba(255, 87, 51, 0.5). The opacity is held between 0 and 1.

Colors by hue​

hslToHex writes a color given by hue, saturation and lightness as hex text. hue is an angle round the color wheel in degrees, 0 red, 120 green and 240 blue, and wraps round, so 480 is green again. saturation runs from 0 for grey to 1 for the purest hue, and lightness from 0 for black through 0.5 for the full hue to 1 for white; both are held between 0 and 1. Hue 210 with saturation 0.6 and lightness 0.5 gives #3380cc. Colors that differ by hue alone, such as a palette spread evenly round the wheel, come from stepping hue and keeping the other two.

Reading one channel​

  • getRedParam, getGreenParam and getBlueParam read a channel of a hex color, remapped to the range from to to as hexToRgbMapped does.
  • rgbToRed, rgbToGreen and rgbToBlue read a channel of an { r, g, b } object as it is.

Inverting​

invert turns each channel of a hex color into 255 minus its value, so #FF5733 gives #00a8cc. With blackAndWhite on, it gives black for a light color and white for a dark one instead, judged by perceived brightness, which keeps text readable on a colored background.

Linear light and sRGB​

The channels of a hex color, and of every color the functions above read or write, are sRGB-encoded: the numbers are spaced the way eyes see brightness, not the way light adds up. Lighting, glTF material factors and the colors OpenCascade holds after reading a STEP file work in linear light instead, so a color crossing between the two needs converting, or it comes out too dark or too pale.

  • srgbToLinear turns one sRGB channel, from 0 to 1, into linear light: 0.5 gives about 0.214.
  • linearToSrgb turns a linear channel back: 0.214 gives 0.5.

Both work on one channel at a time, so convert red, green and blue separately; hexToRgbMapped with from 0 and to 1 gives the channels of a hex color to start from. Blending two colors, or comparing how bright they are, is right in linear light: convert, blend, and convert the result back.

Every function​

FunctionWhat it does
getBlueParamReads the blue channel of a hex color, remapped to a range of your choice.
getGreenParamReads the green channel of a hex color, remapped to a range of your choice.
getRedParamReads the red channel of a hex color, remapped to a range of your choice.
hexColorPasses a hex color through unchanged, so a color can be given a name and reused.
hexToRgbReads a hex color into an { r, g, b } object with channels from 0 to 255.
hexToRgbaWrites a hex color with an opacity as a CSS rgba() color, for a style that needs to see through.
hexToRgbMappedReads a hex color into an { r, g, b } object with the channels remapped to a range of your choice.
hslToHexWrites a color given by hue, saturation and lightness as a hex color: a way to pick colors that differ by hue alone, such as a palette spread round the wheel.
invertInverts a hex color, turning each channel into its opposite: 255 minus the value.
linearToSrgbTurns one linear-light color channel back into its sRGB encoding, the inverse of srgbToLinear, as a hex color holds it.
rgb1ColorPasses an { r, g, b } color with channels from 0 to 1 through unchanged, so it can be given a name and reused.
rgb255ColorPasses an { r, g, b } color with channels from 0 to 255 through unchanged, so it can be given a name and reused.
rgba1ColorPasses an { r, g, b, a } color with every channel from 0 to 1 through unchanged, so it can be given a name and reused.
rgba255ColorPasses an { r, g, b, a } color with color channels from 0 to 255 and opacity from 0 to 1 through unchanged, so it can be given a name and reused.
rgbAtomic1ColorBuilds an { r, g, b } color from three separate channel values from 0 to 1.
rgbAtomic255ColorBuilds an { r, g, b } color from three separate channel values from 0 to 255.
rgbObjToHexWrites an { r, g, b } color as a hex color.
rgbToBlueReads the blue channel of an { r, g, b } color.
rgbToGreenReads the green channel of an { r, g, b } color.
rgbToHexWrites three channel values as a hex color.
rgbToRedReads the red channel of an { r, g, b } color.
srgbToLinearTurns one sRGB-encoded color channel into linear light, the form glTF, STEP colors read by XCAF and the renderers' lighting work in.