Skip to contents

Closest colorjam named_colors

Source: R/jam-color.R
closest_named_color.Rd

Closest colorjam named_colors for a vector of colors

Usage

closest_named_color(
  x,
  colorSet = colorjam::named_colors,
  C_min = Cgrey,
  Cgrey = getOption("jam.Cgrey", 5),
  showPalette = FALSE,
  colorModel = c("hcl", "LUV"),
  Hwt = 2.5,
  Cwt = 1,
  Lwt = 4,
  warpHue = TRUE,
  preset = "ryb",
  method = "maximum",
  returnType = c("color", "name", "match"),
  verbose = FALSE,
  ...
)

Arguments

x

character vector of colors, either in hex format or any valid color in R.

colorSet

character vector of colors, by default named_colors with provides 4,447 total hex colors, each with human-assigned color name. These colors also include hex colors from R colors() which were not already included in the reference colors.

C_min, Cgrey

numeric minimum color Chroma filter applied to handle greyscale colors. In most practical cases C_min and Cgrey should be the same value. Note Cgrey is used as an option in jamba::make_styles(), jamba::applyCLrange() for similar use cases, so it is used here as well: getOption("jamba.Cgrey", 5).

  • C_min is applied to colorSet to require the closest matching color to have at least this color Chroma (saturation).

  • Cgrey is applied to x to determine if the input color itself is considered greyscale, in which case it should not be matched with saturated colors since there is no reliable color hue. Instead, the subset of colorSet with Chroma below C_min is used for color-matching.

Reworded in short:

  • Colors in x with Chroma above Cgrey are matched with colors in colorSet with Chroma above C_min.

  • Colors in x with Chroma below Cgrey are matched with colors in colorSet with Chroma below C_min.

  • The end result should be that saturated input colors match saturated reference colors, and unsaturated input colors match unsaturated reference colors.

showPalette

logical indicating whether to display the input colors and resulting closest matching colors by using jamba::showColors().

colorModel

character color model to use:

  • "hcl": default, uses HCL provided by jamba::col2hcl() which uses the equivalent of colorspace::polarLUV() and considers color hues in terms of 360 degree angles along a color wheel.

  • "LUV": uses CIELUV color space, provided by colorspace::LUV() which encodes the angular color hue in 3-D Cartesian space, allowing comparisons using Euclidean distance.

Hwt, Cwt, Lwt

numeric relative weights for each dimension of HCL colors, for the H, C, and L channels, respectively.

warpHue

logical indicating whether to perform the hue warp operation using h2hw() which improves the ability to match colors between orange and green.

preset

character string to define the color wheel used when matching input colors x to colors in colorSet. This preset is used with h2hw() and hw2h(). The default preset="ryb" allows greatest distinction in colors without imposing additional restrictions such as by preset="dichromat" which would only match color-safe colors. The purpose here is to identify and label colors based upon a reference set of colors.

method

character string passed to stats::dist(). The default method="maximum" works well for colorModel="hcl", and assigns distance using the largest distance across the three color coordinates H, C, and L. It requires the best overall match across all three coordinates rather than any weighted combination of coordinate distances. Other methods in testing allowed matches of different color hues when luminance and chroma values were very similar. With colorModel="LUV" we recommend using method="euclidean", which seems to work well with projected color coordinates L, U, and V. The U, and V coordinates are roughly the angular color hue projected into a flat plane, the L describing Luminance.

returnType

character type of data to return:

  • "color" returns the color values in colorSet, which by default are color names from grDevices::colors()

  • "name" returns names(colorSet) if they exist, otherwise values from colorSet

  • "match" returns an integer vector as an index to colorSet

verbose

logical whether to print verbose output.

See also

Other colorjam core: blend_colors(), closestRcolor(), color_complement(), colors_to_df(), group2colors(), rainbowJam(), sort_colors(), subset_colors()