qualpal: Generate qualitative color palettes

Description

Given a collection of colors, qualpal() algorithmically tries to select to n most distinct colors from the provided input colors, optionally taking color vision deficiency into account.

Usage

qualpal(
  n,
  colorspace = list(h = c(0, 360), s = c(0.2, 0.5), l = c(0.6, 0.85)),
  cvd = c(protan = 0, deutan = 0, tritan = 0),
  cvd_severity,
  bg = NULL,
  metric = c("ciede2000", "din99d", "cie76"),
  extend = NULL
)

Value

A list of class qualpal with the following components.

HSL: A matrix of the colors in the HSL color space.
RGB: A matrix of the colors in the sRGB color space.
hex: A character vector of the colors in hex notation.
de_DIN99d: A distance matrix of color differences according to the metric used. The name is misleading, bu kept for backwards compatibility.
hex: A character vector of the colors in hex notation.
min_de_DIN99d: The minimum pairwise DIN99d color difference among all colors in the palette.

Arguments

n

The number of colors to generate.

colorspace

A color space to generate colors from. Can be any of the following:

A list that describes a color space in either HSL or LCHab color space. In the first case (HSL), the list must contain the following named vectors, each of length two, giving a range for each item.

h

Hue, in range from -360 to 360

s

Saturation, in the range from 0 to 1

l

Lightness, in the range from 0 to 1

In the second case (LCHab), the list must contain the following named vectors, each of length two, giving a range for each item.

h: Hue, in range from -360 to 360
c: Chroma, in the range from 0 to infinity
l: Lightness, in the range from 0 to 100

In these cases, qualpal() will generate

A character vector of length one in the form of "Source:Palette", where Domain is the name of a source that provides a color palette, and Palette is the name of a color palette from that source. See list_palettes() for available palettes.

A matrix or data frame of RGB values (with values between 0 and 1).

cvd

Color vision deficiency adaptation. This must be a named vector with names protan, deutan, and tritan and values between 0 and 1, where 0 means no adaptation and 1 means full adaptation.

cvd_severity

DEPRECATED. Use a named cvd vector instead, e.g. c(protan = 0.5, deutan = 0.2, tritan = 0).

Background color to consider (but not include) when generating the palette. This is useful to avoid colros that are too close to the background/canvas color. If NULL (the default), the background color is not considered at all. Any color that is convertable via col2rgb is acceptable, including hex colors.

metric

The color metric to use for the color distance matrix.

extend

A palette of colors to use as a fixed set of initial colors in the palette, which can be either a matrix or data frame of RGB values (with values between 0 and 1) or a character vector of hex colors (or any other format that's acceptable in grDevices::col2rgb()).

Details

The main idea is to compute a distance matrix from all the input colors, and then try to select the most distinct colors based on the color differences between them. It does this iteratively by first selecting the first n colors from the input colors, then iterates over the palette, putting colors back into the total set and replaces it with a new color until it has gone through the whole range without changing any of the colors.

Optionally, qualpal can adapt palettes to cater to color vision deficiency (CVD). This is accomplished by taking the colors provided by the user and transforming them to colors that someone with CVD would see, that is, simulating CVD qualpal then chooses colors from these new colors.

Examples

Run this code

# Generate 3 distinct colors from the default color space
qualpal(3)

# Provide a custom color space
qualpal(n = 3, list(h = c(35, 360), s = c(0.5, 0.7), l = c(0, 0.45)))

qualpal(3, "ColorBrewer:Set2")

# Adapt palette to deuteranopia
qualpal(5, "ColorBrewer:Dark2", cvd = c(deutan = 1))

# Adapt palette to protanomaly with severity 0.4
qualpal(8, cvd = c(protan = 0.4))

# Generate and extend a palette with 3 colors, using the DIN99d
# metric
pal <- qualpal(3)
qualpal(5, extend = pal$hex, metric = "din99d")

if (FALSE) {
# The range of hue cannot exceed 360
qualpal(3, list(h = c(-20, 360), s = c(0.5, 0.7), l = c(0, 0.45)))
}