Smart Palette

SmartPalette tutorial.

Introduction

A smart palette is similar to linear gradients. It specifies colors mapped to point values or calculations in order to encode a value in point visualizations.

Colors can be specified in a number of ways. Traditional color stops can be supplied through the stops property. Setting the colors property with an array of colors creates equally spaced color gradients. Or if using ranges, each range can have a color specified.

Color Snapping

Mixing solid colors and gradients is a common task and can be accomplished with standard color stops by duplicating a stop with the same color to define the solid color range. While this is not a very complex task, JSCharting simplifies this operation with a feature called color snapping.

Consider this gradient:

Figure 1.

[[0, "blue"], [1, "red"]]

This will gradually change the color from blue to red. However, say we want the gradient to remain solid blue until close to the end and then start turning red as in figure 2.

Figure 2.

The traditional solution is this:

[[0, "blue"], [0.8, "blue"], [1, "red"]]

With color snapping it's simplified to just this:

[[0, "blue", 0.8], [1, "red"]]

Let's say we want to have a solid red color for half the gradient like figure 3.

Figure 3.

Traditionally we would use:

[[0, "blue"], [0.5, "red"], [1, "red"]]

With color snapping:

[[0, "blue", 0, 0.5], [1, "red"]]

It can also be more complex such where both stops include solid colors ranges like figure 4.

Figure 4.

Traditional stops:

[[0, "blue"], [0.2, "blue"], [0.8, "red"], [1, "red"]]

With color snapping:

[[0, "blue", 0.2, 0.8][(1, "red")]]

Stop Values

Color stops use values of 0-1. However, these color stops allow regular values that map to point values like 0-100, or 100-1000.

How colors are mapped to this range is defined by the pointValue property. This property includes full point tokens support including expressions. If the stops define a range of 0-1 in a series of multiple points, the following setting is useful: {%percentOfSeriesMax/100}

This will result in values between 0 and 1.

In cases of a single point where the range is known, this approach can be used. Here it is assumed the range defined by the palette should map to point y values between 0-400. {%yValue/400}

If point values don’t map to the range defined by the stops, they will be converted automatically. For instance in the above example if the pointValue property is set to "%yValue" which results in values 0-400, it will map to the 0-1 stop range.

Note: Using a function with the pointValue property can improve performance with charts that have many data points.

These colors can map to any values supported by string tokens such as x or z values as well as custom attribute values. Mapping to a custom attribute allows encoding an additional value in the data visualization represented by color.

SmartPalette Legend

SmartPalettes can be represented in the legend in two ways. As a color bar, or as range legend entries. In order to show the visual in the legend, the smartPalette must be set on the chart level palette property. By default, the visual will be a colorBar, but if ranges are defined, range legend entries will be used. Ranges will interpolate colors resulting in solid a solid color for each range.

Figure 5. ColorBar

Figure 6. Ranges

Color Ranges

Color ranges can be defined in a number of ways. They can be used with or without the stops or colors properties.

An example:

Figure 7. Example Ranges

{
  ranges: [
    { value: [0, 50], color: "green" },
    { value: [50, 100], color: "yellow" },
    { value: [100, 150], color: "red" }
  ]
}

The above can always be used to have full control, however, it can also be simplified by using colors property.

{
  colors: ["green", "yellow", "red"],
  ranges: [{ value: 0 }, { value: 50 }, { value: [100, 150] }]
}

{
  colors: ["green", "yellow", "red"],
  ranges: [0, 50, [100, 150]]
}

Alternatively, a min/max/interval can be supplied:

{
  colors: ["green", "yellow", "red"],
  ranges: { min: 0, max: 150, interval: 50 }
}

All these approaches will result in the same ranges.

Ranges also support a LegendEntry property giving full control over the entry in the legend. A defaultEntry property allows setting common values for each entry.

{
  ranges: [
    { min: 0, max: 50, color: "green", legendEntry_value: "0 to 50" }
    //…
  ]
}

{
  defaultEntry_value: "%min to %max"
}

Documentation