Highcharts Sunburst chart - What is the range of colorVariation.to values?

Question

Highcharts API reference explains that colorVariation.to is the ending value of color variation that is applied to the last sibling. Demo example : http://jsfiddle.net/gh/get/library/pure/highcharts/highcharts/tree/master/samples/highcharts/demo/sunburst/

levels: [{
        level: 2,
        colorByPoint: true,
        dataLabels: {
            rotationMode: 'parallel'
        }
    },
    {
        level: 3,
        colorVariation: {
            key: 'brightness',
            to: -0.5
        }
    }, {
        level: 4,
        colorVariation: {
            key: 'brightness',
            to: 0.5
        }
    }]

When i set colorVariation.To = 0 for level 3, all the siblings at this level are shown in same color. Refer: http://jsfiddle.net/hqkk8ut5/

levels: [{
        level: 2,
        colorByPoint: true,
        dataLabels: {
            rotationMode: 'parallel'
        }
    },
    {
        level: 3,
        colorVariation: {
            key: 'brightness',
            to: 0
        }
    }, {
        level: 4,
        colorVariation: {
            key: 'brightness',
            to: 0.5
        }
    }]

In my application, I want to configure the colorVariation.to value. I would like to know that what range of values should i allow?

Answer 1

I think that the key to understand how colorVariation.to works is by analyzing two core functions:

1. variation from sunburst.src.js

        function variation(color) {
            var colorVariation = level && level.colorVariation;
            if (colorVariation) {
                if (colorVariation.key === 'brightness') {
                    return H.color(color).brighten(
                        colorVariation.to * (index / siblings)
                    ).get();
                }
            }

            return color;
        }

2. brighten from highcharts.src.js

        brighten: function(alpha) {
            var i,
                rgba = this.rgba;

            if (this.stops) {
                each(this.stops, function(stop) {
                    stop.brighten(alpha);
                });

            } else if (isNumber(alpha) && alpha !== 0) {
                for (i = 0; i < 3; i++) {
                    rgba[i] += pInt(alpha * 255);

                    if (rgba[i] < 0) {
                        rgba[i] = 0;
                    }
                    if (rgba[i] > 255) {
                        rgba[i] = 255;
                    }
                }
            }
            return this;
        },

Example:

Les't assume that we have two siblings on the same level and their colorVariation.to is 0,5. The base color for this level is rgba(255,0,0,1) (red). For the first sibling the index equals to 0 in variation function. So the value passed to the brighten function is 0 (0.5 * (0 / 2)). The next step is multiplying this value by 255 (maximum level of brightness) and adding it to each color component except a: r, g and b. So for the first sibling this value remains the same as colorVariation.to.

For the second sibling the value of alfa is 0.25 (0.5 * (1 /2)). pInt(alpha * 255) will return 63 (pInt works just like Math.floor in this case). So the final value will be rgba(255, 63, 63). The values higher than 255 and 0 are corrected by two if statements.

---

In this case Math.min(r,g,b) is 0, so the if we want to get maximum brightness for the last leaf the alpha should equal to 1 (all components (r,b,g) must have value of 255).

If we solve the equation from variation function: colorVariation.to * (1 / 2) = 1 we will get 2 - the maximum value for colorVariation in this case. All values higher than this will work the same as if they were 2.

The value of colorVariation can be a negative number - it will make colors darker instead of brighter.