Luma and Contrast Nodes

john's Avatar


31 Dec, 2023 03:21 PM

The attached interactive demo introduces TWO new color nodes: Luma and Contrast.

Luma converts a color to a luma value between 0 and 1 (0 is very dark, 1 is very bright). Luma is a measure of the actual perceived brightness of a color that is far more accurate than the standard brightness property displayed in Nodebox color dialogs. Luma takes two inputs:

  • Color. The color you want to measure.
  • Alpha Backgrnd. This is only needed if your color is translucent (alpha less than 100%). Translucent colors will first be placed against the alpha background color (the color behind the color your shape sits on) and turned into a solid color based on that before being measured.

One situation where you might need to set an alpha background is depicted in the demo. Each label sits on a color chip. Some of the color chips may be translucent. The entire array of color chips are set on a cream-colored background. So the actual background for each label is a mix of the translucent chip and the ultimate cream background. In this case you would set the Color to the translucent chip color and the Alpha Backgrnd to the cream color behind all the chips. In most situations, with opaque background colors, you won't need to worry about an alpha background.

Luma values could be used to build a table with filled shapes and their luma values; this would allow you to sort them by perceived brightness and arrange them accordingly. Another great use case is making high-contrast labels...

Contrast sets the fill color of a shape to one of two settings depending on the background it is shown against. It is primarily intended for label text paths, but will work for any closed shape.

Contrast takes six inputs:

  • Shape. The shape you wish to recolor.
  • Background. The color that the shape will be seen against.
  • Alpha Background. The ultimate background behind the background - only needed if the Background is translucent.
  • Light shape color. Your shape's new color if it is set against a dark background. Usually white or near-white.
  • Dark shape color. Your shape's new color if it is set against a light background. Usually black or near-black.
  • Cutoff percent. The luma value cutoff which will determine how light a background must be to require a dark shape color. For example, if you set your cutoff to 40%, then all backgrounds with a luma value less than or equal to 40% will be considered dark and require a light shape color for contrast; any background luma values greater than 40% would cause your shape to be recolored using your dark shape color.

The attached demo provides an example of how both of these nodes work. It is intended to be used interactively, so for full understanding you should launch it and fiddle with the settings.

The initial setting shows an array of 60 randomly-colored paint chips, all opaque. They are sorted from dark in the upper lelf to bright in the lower right. The luma value of each paint chip is displayed on the chip. Feel free to change the random seed in the colors node on top to try a different array of colors.

Notice that the luma values on dark chips are displayed in a light near-white color, while values on light colored chips are displayed in a dark color. This was accomplished using the contrast node (about halfway down the tree). Try changing the cutoff value to see how the labels change. Without this contrast feature, no matter what color you picked for your labels, some of them would be hard to read.

In order to better understand the occasional need for an alpha background setting on both the luma and contrast nodes, try changing the opacity of the color chips. You can do this by lowering the percent in the Fade node near the top. As the paint chips become less and less opaque, you can see the luma values change (and the label color as well to maintain contrast). If you fade out the chips entirely you will be left with all luma values set to 0.863, the luma value of the cream colored background behind the chips.

Now try setting the fade to, say, 50, and then change the main background by changing the "alpha_bg" color node. Any change you make to its hue, saturation, or brightness will affect the luma values of all the paint chips. If you make the main background dark enough, all the chips will darken with it and the resulting luma values will cause all the labels to turn white. Notice that no matter what you do (as long as you have a reasonable cutoff near 50% in the contrast node), all labels will be easy to read.

Although contrast is primarily intended for labels, it will work for any shape with a fill color. To verify this for yourself, find the switch1 node near the center of the tree and change its index from 0 to 1. All the labels will now be replaced by dots. Each dot will be set to either your assigned light color or dark color depending on the background color of the chip it sits on. You can repeat your previous adjustments to watch the dots change color.

Finally, in case you are curious about the difference between luma and brightness, find the switch2 node closer to the bottom of the tree. Changing its index from 0 to 1 will cause the chips to be sorted by brightness instead of luma (luma values are still displayed). As you scan across the rows of chips you will notice a more varied progression from dark to light, with many brighter-seeming colors scattered here and there amidst darker-seeming neighbors. Using brightness to determine contrast would result in situations with some hard to read labels in a seemingly random fashion.

I hope you enjoy both of these nodes. They will appear in the new color section of my Cartan Node Library, which I hope to publish very soon.

  1. Support Staff 1 Posted by john on 05 Jan, 2024 05:10 PM

    john's Avatar

    Just for fun, I present another demo, this one focusing on the contrast node.

    I create a tilted checkerboard of bright and dark colors, then place the word "Hello" in front of it. Because of the varying background, any color for the label would be hard to see...

    So instead of choosing a single color for "Hello", a break it up into pieces and use the contrast node to change the color of each piece to either black or white depending on the luma value of its background. The result is a striking pattern that is a little easier to read.

    Notice that to make the variegated checkerboard I use two other recent nodes: luma_colors and mix. These two nodes made this easy.

    A simple demonstration, but one which would be hard to do without these new nodes.

Reply to this discussion

Internal reply

Formatting help / Preview (switch to plain text) No formatting (switch to Markdown)

Attaching KB article:


Already uploaded files

  • Luma_Contrast_Screenshot.png 645 KB
  • 8.14 KB

Attached Files

You can attach files up to 10MB

If you don't have an account yet, we need to confirm you're human and not a machine trying to post spam.

Keyboard shortcuts


? Show this help
ESC Blurs the current field

Comment Form

r Focus the comment reply box
^ + ↩ Submit the comment

You can use Command ⌘ instead of Control ^ on Mac

Recent Discussions

13 Jul, 2024 06:05 AM
11 Jul, 2024 03:48 PM
28 Jun, 2024 01:51 PM
27 Jun, 2024 02:56 PM
27 Jun, 2024 01:57 PM


26 Jun, 2024 08:17 PM
26 Jun, 2024 11:35 AM
24 Jun, 2024 02:42 AM
24 Jun, 2024 12:46 AM
23 Jun, 2024 08:07 AM
08 Jun, 2024 09:05 AM