Skip to contents

Generate qualitative color palettes

Source: R/qualpal.R
qualpal.Rd

Given a color space or collection of colors, qualpal() projects these colors to the DIN99d color space, where it generates a color palette from the most visually distinct colors, optionally taking color vision deficiency into account.

Usage

qualpal(
  n,
  colorspace = "pretty",
  cvd = c("protan", "deutan", "tritan"),
  cvd_severity = 0,
  n_threads
)

Arguments

n

The number of colors to generate.

colorspace

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

  • A list with the following named vectors, each of length two, giving a range for each item.

    h

    Hue, in the range [-360, 360]

    s

    Saturation, in the range [0, 1]

    l

    Lightness, in the range [0, 1]

  • A character vector of length one specifying one of these predefined color spaces:

    pretty

    Tries to provide aesthetically pleasing, but still distinct color palettes. Hue ranges from 0 to 360, saturation from 0.1 to 0.5, and lightness from 0.5 to 0.85. This palette is not suitable for high n

    pretty_dark

    Like pretty but darker. Hue ranges from 0 to 360, saturation from 0.1 to 0.5, and lightness from 0.2 to 0.4.

    rainbow

    Uses all hues, chromas, and most of the lightness range. Provides distinct but not aesthetically pleasing colors.

    pastels

    Pastel colors from the complete range of hues (0-360), with saturation between 0.2 and 0.4, and lightness between 0.8 and 0.9.

  • A matrix of colors from the sRGB color space, each row representing a unique color.

  • A data.frame that can be converted to a matrix via data.matrix

cvd

Color vision deficiency adaptation. Use cvd_severity to set the severity of color vision deficiency to adapt to. Permissible values are "protan", "deutan", and "tritan".

cvd_severity

Severity of color vision deficiency to adapt to. Can take any value from 0, for normal vision (the default), and 1, for dichromatic vision.

n_threads

Previously the number of threads to use, but this argument is now deprecated.

Value

A list of class qualpal with the following components.

HSL

A matrix of the colors in the HSL color space.

DIN99d

A matrix of the colors in the DIN99d color space (after power transformations).

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 delta E DIN99d.

min_de_DIN99d

The smallest pairwise DIN99d color difference.

Details

The function takes a color subspace in the HSL color space, where lightness and saturation take values from 0 to 1. Hue take values from -360 to 360, although negative values are brought to lie in the range {0, 360}; this behavior exists to enable color subspaces that span all hues being that the hue space is circular.

The HSL color subspace that the user provides is projected into the DIN99d color space, which is approximately perceptually uniform, i.e. color difference is proportional to the euclidean distance between two colors. A distance matrix is computed and, as an additional step, is transformed using power transformations discovered by Huang 2015 in order to fine tune differences.

qualpal then searches the distance matrix for the most distinct colors; it does this iteratively by first selecting a random set of colors and then iterates over each color, 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.

qualpal currently only supports the sRGB color space with the D65 white point reference.

See also

plot.qualpal, pairs.qualpal

Examples

# Generate 3 distinct colors from the default color space
qualpal(3)
#> ---------------------------------------- 
#> Colors in the HSL color space 
#> 
#>           Hue Saturation Lightness
#> #C96C69   1.9       0.47      0.60
#> #6E9DCE 210.6       0.49      0.62
#> #9FCB6A  87.0       0.48      0.61
#> 
#>  ---------------------------------------- 
#> DIN99d color difference distance matrix 
#> 
#>         #C96C69 #6E9DCE
#> #6E9DCE      24        
#> #9FCB6A      24      24

# Provide a custom color space
qualpal(n = 3, list(h = c(35, 360), s = c(0.5, 0.7), l = c(0, 0.45)))
#> ---------------------------------------- 
#> Colors in the HSL color space 
#> 
#>         Hue Saturation Lightness
#> #BF26B8 303       0.67     0.449
#> #7CC223  87       0.70     0.449
#> #061D0B 134       0.67     0.067
#> 
#>  ---------------------------------------- 
#> DIN99d color difference distance matrix 
#> 
#>         #BF26B8 #7CC223
#> #7CC223      34        
#> #061D0B      30      30

qualpal(3, "pretty")
#> ---------------------------------------- 
#> Colors in the HSL color space 
#> 
#>           Hue Saturation Lightness
#> #C96C69   1.9       0.47      0.60
#> #6E9DCE 210.6       0.49      0.62
#> #9FCB6A  87.0       0.48      0.61
#> 
#>  ---------------------------------------- 
#> DIN99d color difference distance matrix 
#> 
#>         #C96C69 #6E9DCE
#> #6E9DCE      24        
#> #9FCB6A      24      24

# Adapt palette to deuteranopia
qualpal(5, colorspace = "pretty_dark", cvd = "deutan", cvd_severity = 1)
#> ---------------------------------------- 
#> Colors in the HSL color space 
#> 
#>           Hue Saturation Lightness
#> #121F4A 247.8       0.47      0.20
#> #AB9036  57.1       0.50      0.40
#> #2E2A1B   1.9       0.46      0.20
#> #54618D 197.1       0.49      0.37
#> #6F6C61 152.1       0.41      0.36
#> 
#>  ---------------------------------------- 
#> DIN99d color difference distance matrix 
#> 
#>         #121F4A #AB9036 #2E2A1B #54618D
#> #AB9036      31                        
#> #2E2A1B      18      23                
#> #54618D      16      25      20        
#> #6F6C61      22      15      16      16

# Adapt palette to protanomaly with severity 0.4
qualpal(8, colorspace = "pretty_dark", cvd = "protan", cvd_severity = 0.4)
#> ---------------------------------------- 
#> Colors in the HSL color space 
#> 
#>           Hue Saturation Lightness
#> #563F94 293.5       0.48      0.39
#> #7F8832  94.3       0.48      0.38
#> #40271E   4.1       0.48      0.23
#> #4E6D8E 200.0       0.44      0.38
#> #658B79 162.7       0.46      0.40
#> #2C3542 207.7       0.25      0.20
#> #364529 135.6       0.44      0.20
#> #7A5936  20.6       0.45      0.39
#> 
#>  ---------------------------------------- 
#> DIN99d color difference distance matrix 
#> 
#>         #563F94 #7F8832 #40271E #4E6D8E #658B79 #2C3542 #364529
#> #7F8832      28                                                
#> #40271E      20      22                                        
#> #4E6D8E      15      23      22                                
#> #658B79      23      14      23      15                        
#> #2C3542      15      24      14      14      20                
#> #364529      23      16      14      19      16      14        
#> #7A5936      23      14      14      21      18      19      14

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)))
}