Utilities

Angle wrapped to be between -180 and +180 degrees.

Undocumented

Data structure that stores color, optionally with opacity.

Color can be expressed in a variety of ways:

• As a one of 100+ CSS named colors :

  let darkRed = Color.darkRed
  

• As red, green and blue pixel intensities with optional alpha channel for transparency:

  let black = Color.RGB(255, 255, 255)
  let blackTransparent = Color.RGB(255, 255, 255, 0.2)
  

• As hue, saturation and lightness values, also with optional transparency:

  let pink = Color.HSL(300, 100, 50)
  let pinkTransparent = Color.HSL(300, 100, 50, 0.3)
  

• As a hexadecimal integer literal in 0xRRGGBB format:

  let black: Color = 0xffffff
  

Transparency is expressed as alpha channel between 0 (transparent) and 1 (opaque). Valid lightness and saturation values are percentages between 0 and 100. Hue represents a positive angle smaller than 360°. There are no checks, clippings or exceptions that enforce these constraints.

let black: Color = 0xfff // Blue #000fff
let blackTransparent: Color = 0xffffff88 // Yellow #ffff88

Constant or variable coloring of a property.

Qualitative color scale or a sequence of colors.

Qualitative color sequences are appropriate for data without natural ordering, such as categories, colors, names, countries and so on. The built-in static color sequences are meant to be used mostly as a Layout.colorWay attribute.

Mapping from numerical values to colors.

Instead of constructing a custom color scale, in most situation it’s desirable to pick one from a pre-defined palette. There is a wide range of built-in scales that should suit nearly all applications. Key advantage of these scales is that they address the technicalities to avoid hidden biases that can distort how people naturally perceive the data.

Built-in Color Scales

Based on the type of data the built-in scales are suited to one can distinguish the following types:

• Sequential - Vast majority of continuous data without any special properties.
• Diverging - Continuous data with a natural mid-point or a critical value where roughly half of the data is smaller and the other half is larger.
• Cyclic - Periodic data that wrap back to the same value after reaching end-points. For example tide height plotted on the globe.

Good way to pick one of the scales is to use the swatch() method that displays a figure with the scales other. The following example displays all diverging scales:

let diverging = ColorScale.Diverging.swatch()
// Also: Sequential, Cyclic, Ocean, Brewer, Carto, Plotly
try diverging.show()

Most popular color scales are exposed directly as static properties of ColorScale struct. The following code displays a swatch of the most frequent used scales:

let frequent = ColorScale.swatch()
try frequent.show()

Custom Color Scales

Color scale can be also created manually from a sequence of colors and optional normalizes scale values. In most situations the desirable behavior is a smooth, linear interpolation between in-between the sequence colors. However, it’s also possible to create discontinuous scales with sharp jumps at particular thresholds.

The following example creates a custom color scale by linearly interpolating colors. The minimum/maximum value of the data will be displayed in red/blue with the intermediate values interpolated through green. The min/max value can be changed by manually setting zMin/cMin or zMax/cMax properties of the Trace or Marker objects. Location of the green mid-point can be altered by zMid/cMid property in a similar fashion.

let rgb0: ColorScale = [.red, .green, .blue]
let rgb1 = ColorScale(interpolate: [.red, .green, .blue])

The following example achieves the same result as above but builds the color scale fom a dictionary that maps the scale values to colors:

let rgb0: ColorScale = [0: .red, 0.5: .green, 1.0, .blue]
let rgb1 = ColorScale(interpolate: [0: .red, 0.5: .green, 1.0, .blue])

The next code snippet creates a discontinuous black-white color scale with sharp jump below and above the mid-point:

let bw = ColorScale(interpolate: [(0: .white), (0.5: .white), (0.5, .black), (1.0, .black)])

Encapsulation of either a constant value or a collection of changing data.

A representation of an arbitrary JSON value.

This is a bit more useful than the naive [String:Any] type for JSON values, since it makes sure only valid JSON values are present.