closestRcolor: Find the closest R color

In jmw86069/colorjam: Jam Color manipulation functions

Find the closest R color

Description

Find the closest R color for a vector of colors

Usage

closestRcolor(
  x,
  colorSet = colors(),
  Cgrey = getOption("jam.Cgrey", 5),
  C_min = Cgrey,
  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,
  ...
)

closest_named_color(
  x,
  colorSet = colorjam::named_colors,
  Cgrey = getOption("jam.Cgrey", 5),
  C_min = Cgrey,
  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 includes the R colors grDevices::colors().
Cgrey, C_min	numeric default 5, using getOption("jamba.Cgrey", 5), the Chroma at which colors are considered "grey" ("gray"). The purpose is for saturated colors to match saturated colors, and non-saturated colors to match non-saturated colors. Cgrey is applied to colorSet. C_min is applied to x. They should be the same value in most scenarios, however it may be useful to force x to match with non-grey colors even with small but non-zero Chroma. Rules: All non-grey colors x are compared with non-grey colorSet. Grey colors x are compared with grey colorSet, therefore color Hue is not used. Note Cgrey is an argument in jamba::make_styles(), and jamba::applyCLrange() for similar use cases.
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, defaults 2.5, 1, 4, respectively, relative weights for the H, C, and L channels, respectively, only when colorModel="hcl".
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.

Details

This function is intended as a relatively efficient method to compare a set of colors to the named R colors provided by grDevices::colors().

Color matching provides substantial improvements over similar functions from other R packages. Notably, colors are matched using either HCL or LUB color model by default, both of which provide vast improvement over RGB color matching, due to better spacing of colors, and increased resolution of color hue.

For colorModel="HCL" the coordinates are weighted to prioritize matching color Hue above Chroma and Luminance. The distance method by default uses method="maximum" which also emphasizes the lowest distance in any of the three dimensions.

Notably, this function does not use color_distance(), in part because in practice the color metrics used by 'cie2000', 'cie94', 'cmc' did not prioritize the same color hue, and often the returned color was similar but not the most visibly similar in terms of hue.

Also color_distance() does not currently permit weights for Hue, Chroma, Luminance, as these values are already defined in farver::compare_colour().

Todo

• Consider testing then adding color_distance() as an optional metric. Test whether it could improve results.

Value

character vector of colors, optionally customized by argument returnType.

See Also

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

Examples

closestRcolor(rainbowJam(12), showPalette=TRUE);

jmw86069/colorjam documentation built on June 10, 2025, 12:02 p.m.