ColorControl - an interactive GUI for creating dynamic color effects on your leds

[Anders-Holst]

I have released a new version of xled_plus, where the main addition is xled_colorcontrol.py, which when started as

python -m xled_plus.xled_colorcontrol

pops up a window from which you can select a color scheme and corresponding effect type, and then upload it to your leds.
It greatly simplifies creating new effects, since you don't have to edit a python file by hand, trying to figure out suitable HSL or RGB color codes. This way you can create your own daily effects, by just picking the colors you feel like today, and then select whether you want a blinking or glowing or alternating pattern etc.

A prerequisite is that you install the latest (as of 2024-11-26) version of 'colorsphere':

pip install -U colorsphere

And of course the current version (as of 2024-11-27) of xled_plus:

pip install -U xled_plus

This is a first version of the ColorControl. There are several things that can be added or enhanced. For example, right now it picks the first Twinkly device it finds (and hangs if you have no device online). It should of course let you select the device. You can not configure the effects, other than which colors to use. Also, you can not save the effects you create to a file, for later reuse. This must of course be fixed to make it more useful. Nevertheless, please try it out and tell me what you think, and if you have any further ideas for enhancements.

It is in no way meant to replace the entire Twinkly app, although it is meant to replace the part of the app where you select an effect type and then configure its colors through an awkward two-scales color picker. With the ColorControl you get the best effect types from the xled_plus package, and can use the hopefully more intuitive 3D color picker ('colorsphere') I wrote some years ago, to select your color scheme.

Hopefully it is fairly self explanatory. You can press the question mark in the corner of the ColorControl window for some directions. I will give some further hints in the next post.

[Anders-Holst]

Here is some kind of instructions for the ColorControl.

The big colored thing in the middle is the 3D color sphere. It is a spherical representation of the color body of all available colors on your leds. (Quite different from the two scales version in the app, right? There you essentially only see one color at a time, and need to adjust its hue and lightness separately until you find the wanted one. Here you have all the colors right in front of you.) You can rotate the sphere by dragging its surface, or using the arrow keys. It has white at the "north pole", black at the "south pole", and the full color circle around the equator.
Using the scroll wheel you can also go inside the sphere, to less saturated colors. In the middle it is medium gray. You seldom need to go inside though: All the colors inside has a corresponding brighter color somewhere on the surface, and leds are not good at showing unsaturated colors: Gray will just look as a dim white, brown as a dim orange or yellow. Therefore you will find most of the colors you need on the surface of the sphere.

The idea is that you first select a color scheme for your pattern. When you hover over the sphere the corresponding color will show on your leds. Click on the colors you want to use, and they will pile up in the color patches to the left. If you got the wrong color you can select a patch and change its color. You can delete a patch by selecting it and pressing the "delete" key over it. Delete all patches and start over by pressing the cross above the patches. For some effects, the order of the colors matter. You can rearrange the order of patches by dragging them.

Then you select an effect to the right. Again, the resulting effect with the created color scheme will be displayed on the leds, so you can see what it will look like. Change another effect, or modify the colors (and reselect the effect) if you are not satisfied. (The code for ColorControl is modular in the sense that it is easy to configure in the python code which effects that are available. In this version I just picked some natural and nice ones, but it may be extended, from within `xled_colorcontrol.py'.)

A few words about the current effects:
"Breathe" will randomly assign one of the selected colors to each led, which will stick to its color but slowly vary in lightness, making a breathing/living appearance of the colors.
"Glow" will let each led randomly wander smoothly between the selected colors. However, there is an intentional unbalance, such that the first color in the color scheme is most frequent, and the following colors less and less abundant. A hint to make a nice glowing pattern is to start the color scheme with two nearby highly saturated colors, then add a very light version of similar hue and then a very dark one, and finally add one or two "spice" colors of a more distant hue.
"Twinkle" are like gently appearing and disappearing stars, randomly chosen from the selected colors.
"Sparkle" is similar but each colored light starts by a sudden flash, making a sparkling appearance.
"Glitter" uses the first color in the scheme as background, and randomly flashes the other colors. Best effect is achieved by selecting a deep dark color as background, and then a few light colors of compatible hues, or just white.
"Sequence" slowly shifts between the colors in the sequence given by the scheme. If you want it to stay at each color a while, you might want to duplicate each color in the sequence. If the transitions between colors are unintuitive (because it passes through the interior of the color sphere), you may want to provide suitable transition colors in between as well.
"Bands" is actually similar to sequence, but it plays the sequence in bands running from top to bottom of the leds (if you have added a layout, otherwise the bands run along the strings).

When you are happy with the effect you press Apply to upload it as a movie to the leds.

And that's it. To quit press "q".

[Anders-Holst]

Why did I create this new "color sphere" color model to pick colors from, when there are already so many color models out there?

So here I would like to rant a while about color models. If you don't care about colors and color models you will not miss anything by not reading this post.

---

I'm happy you continued reading. After all, if we buy a string of lights a magnitude more expensive than the strings most people buy, that is because we love and care about colors, right? (Well, or about gadgets, or both.)

First a confession: I am not the first to construct spherical color bodies. There are several examples out there, already from early 19:th century, long before the age of computers and displays. I only discovered recently that some of them are almost identical to the one I present here. Instead, I started out from the fairly common HSL - Hue Saturation Lightness - color model. The sphere is actually just a visual representation of (a slight modification of, see below) the HSL model: The longitude represents the hue parameter, the latitude the lightness parameter, and (for points inside the sphere) the proportion of the distance from the axis between the poles to the surface represents the saturation parameter. The HSL model is in my view the most appropriate and convenient of the models out there. This is why the xled_plus package uses (h,s,l)-tuples to represent colors.

But why do we need a color model? Isn't RGB - Red Green Blue - good enough? It can be represented as a cube with black, red, green, blue, cyan, magenta, yellow and white in the corners.

Well, the raw RGB values are unsuitable to work with for several reasons. Firstly, most displays needs a gamma correction. This means that the brightness of the pixels does not increase linearly with the pixel value. Rather, it increases approximately as the square of the pixel value. However, curiously enough the leds need no gamma correction, because they achieve different brightness by quickly pulsing between full on and off, with the proportion of on corresponding to the pixel value. This however means that the same RGB values look quite different on a computer or phone compared to on the leds. Even many professional programs make this mistake in their color picker dialogues. Without gamma compensation, the color scale looks like this:

That is, long stretches of red, green, and blue, and very quick transitions in between them over narrow yellow, cyan and magenta.
The correct scale, with gamma compensation, should look like this (provided you have the same gamma value on your screen as I have on mine):

Here the transitions are much more evenly spread out between the "corner colors" red, yellow, green, cyan, blue and magenta. (It is unclear to me if the Twinkly app makes this mistake - it looks to me like something in between.)

A second problem with the raw RGB values is that different devices may have different white balance, i.e the red, green and blue pixels have different relative strengths on different devices. What looks like pure white on one device may look slightly tinted on another. This is indeed the case for Twinkly lights, which has a much brighter blue, and a slightly brighter red, than on a normal computer display. When all colors are at their maximum value, the Twinkly lights therefore produce a rather blue-purple tinted white, which gives a very hard and artificial white appearance. To get a nice neutral white and good color balance, the RGB values have to be compensated for this. (Here I think the Twinkly app fails: on my devices, a light pink color in the app looks more purple on the lights, and a pastel green in the app has a tendency towards pastel blue on the lights.) In the file 'ledcolor.py' in the 'xled_plus' package there is a variable 'led_balance' which specifies how much to reduce each base color to get a good white balance. It was originally calibrated for my very first device, but I have noticed that devices differ, and probably changes balance as they age as well, so I am figuring out how to make a balancing tool to make it configurable. An annoying situation in which you may need this is if you have grouped devices, and they are sightly off color from each other. Please tell me if you would have use for such a tool.

So if we consider the above, we may work with a device independent, "normalized" RGB color cube, and then make a device dependent transformation compensating for gamma and white balance when sending it to the device. Back to the question: isn't such a color body good enough? Indeed if we put the RGB cube on its black corner with the white corner pointing up, it looks almost as the color sphere, with a zig-zaging color circle red-yellow-green-cyan-blue-magenta around its belly.

In a sense, all (computer used) color bodies are just transformations of the RGB color cube. If you look at the darker colors on the color sphere, especially around black, red and blue, it is not as smooth as one could have wished, but there are clear traces of the edges of the RGB color cube. (It is not easy to smoothly transform a cube into a sphere, and the eye is very good at noticing even small changes in the gradient.)

So clearly the color sphere is just a transformation of the RGB cube. But the whole point of the transformation is to make it convenient to work with, and also intuitive and natural, without having to bother about the technical details of how colors are produced on computer screens. The most human centered color body is the Lab model (and the quite similar Luv model). It is designed to reflect the colors the human eye (with normal color seeing) can see and distinguish. It is particularly inconvenient to work with on computers, because of its irregular shape, and also because it contains colors outside the range reproducible on a computer screen (especially more green nuances). The part that can be reproduced on screen looks something like this (don't care about the stripy character, its just an artifact from the way I generated it):

Again you can clearly see a distorted RGB cube in there, but it is of course just because the picture only shows the colors that can be rendered on a screen, which is limited to the RGB cube. In the human-visible version of the color body there are no marked cube edges for yellow, cyan, and magenta, and the green part extends much longer. But I will not talk more about this model here.

Most common color models represent hue as a separate parameter. If you want to produce a color circle, this is easy in such a model. It is not easy in the RGB cube: you need to follow the edges around, check a lot of if-statements to figure out which side you are on, and involve all three coordinates. What distinguishes the HSL model from many others is that with the lightness parameter you can start from a hue and seamlessly vary its lightness from black to white. Most other models (like HSV - Hue Saturation Value - and HSB, Hue Saturation Brightness) has a separate parameter to go from black to maximum chroma, and then another parameter to go from there to white. But if you want to draw something with light and dark shadowing (like the cheap 3D-rendering of buttons in the ColorControl), it is more convenient to start from any color and just adjust the lightness parameter, regardless of which side of max chroma the original color is.

But I wanted to do some modifications of the original HSL model for my color sphere. In the original HSL model, all max chroma colors are on the equator. But if you look at the color circles above, that makes them go roller coaster in brightness. Just like in the color spheres from early 19:th century, I wanted the same brightness around the equator, and the brightness (i.e lightness) to change uniformly from black to white along the meridians regardless of the hue.

Then I have also modified the hue parameter: The original hue parameter has, as can be seen in the above color circles, the "computer base colors" red-(yellow)-green-(cyan)-blue-(magenta) at equal distances (I call this scale 3-color). From a human perspective though, it feels more natural with a color circle of the six colors yellow-orange-red-purple-blue-green at equal distances (I call this scale 6-color). This is also the scale many of the early color spheres use. However, just to complicate things, I suggest yet something different, an 8-color scale: Consider that cyan (or its darker version blue-green) is a clearly distinguishable color, as is actually magenta between red and purple. So merging them to the 6-color scale, we get a combination of the two scales with eight colors at equal distances: Blue-cyan-green-yellow-orange-red-magenta-purple. Interestingly, a motivation for the 6-color scale is that complementary colors should be on opposite sides of the scale. And everybody knows that green and red are complementary, right? But if you stare at a red patch for half a minute, and then on something white, you rather see a cyan after-image. And if you similarly look at green and then on something white, it looks more like magenta. So the 8-color model fulfills this complementary condition better. This is thus what I use in the color sphere.

Well, that's all I wanted to say about color models, and to motivate why the sphere looks as it does.

/ Anders

[Anders-Holst]

I should have added what the equi-light 8-color scale looks like. Here it is (starting from magenta). No dramatic brightness changes, smooth transitions. Ok, blue and red are a little faded, and yellow somewhat muted, but the corresponding higher chroma hues can still be found elsewhere on the sphere (towards darker for blue and red and lighter for yellow).

[Anders-Holst]

There is now a new release of xled_plus (r0.1.37) with an upgraded version of ColorControl.

There are several additions:

• You can now save created effects to file, and later loaded back into ColorControl. The created file is at the same time a python script, which when run from the command line will upload the effect to a device. With a command line argument you can control which device. Although I have no home assistant myself, I suppose such a program is convenient to call from a home assistant.
• There is also a button for toggling your device on and off. The device is turned on temporarily as you create and preview your effect, and then "permanently" when you upload it. Thus it is convenient to be able to turn it off again without starting another interface.
• It can now handle several devices: In the top row there is a button for each device it finds on the network, and you can select which one to work with. (It is also meant to work with grouped devices, although it is not much tested yet. Please let me know of any problems you encounter.) It should also be able to handle when there is no connected device - then you can create an effect and save it to file for later use (but of course it is less convenient when you don't know what it will look like until later).
• A previewed effect is now dynamically updated when you update the color scheme.
• Uploaded effects now get named after the effect type, so you can easier distinguish them if you use the app.
• It is easier to add more effect types to ColorControl. Well, it requires some python programming, but it is modular in the sense that you only add the effect class in the table (dict) at the beginning of "xled_colorcontrol.py" and it will turn up as a button in ColorControl. The effect has to be of a type that takes exactly three argument when created: The controlinterface object, the list of HSL colors which is the color scheme, and a third named argument "name" which takes the name of the effect.

Please tell me what you think, and also if there are any bugs or inconvenient behaviors found.

/ Anders