setTextContrastColor function

Define visible text color

Given a vector or colors, define a contrasting color for text, typically using either white or black. The useGrey argument defines the offset from pure white and pure black, to use a contrasting grey shade.

setTextContrastColor(
  color,
  hclCutoff = 60,
  rgbCutoff = 127,
  colorModel = c("hcl", "rgb"),
  useGrey = 0,
  keepAlpha = FALSE,
  alphaLens = 0,
  bg = NULL,
  ...
)

Arguments

• color: character vector with one or more R-compatible colors.
• hclCutoff: numeric threshold above which a color is judged to be bright, therefore requiring a dark text color. This comparison uses the L value from the col2hcl() function, which scales colors from 1 to 100.
• rgbCutoff: numeric threshold above which a color is judged to be bright, therefore requiring a dark text color. The mean r,g,b value is used.
• colorModel: Either 'hcl' or 'rgb' to indicate how the colors will be judged for overall brightness. The 'hcl' method uses the L value, which more reliably represents overall visible lightness.
• useGrey: numeric threshold used to define dark and bright text colors, using the R greyscale gradient from 0 to 100: useGrey=10 implies "grey10" and "grey90" for the contrasting text colors; useGrey=15 is useful if labels may also overlap white or black space, since the text will never be fully white or black.
• keepAlpha: logical indicates whether the input color alpha transparency should be maintained in the text color. By default, text alpha is not maintained, and instead is set to alpha=1, fully opaque.
• alphaLens: numeric value used to adjust the effect of alpha transparency, where positive values emphasize the background color, and negative values emphasize the foreground (transparent) color.
• bg: vector of R colors, used as a background when determining the brightness of a semi-transparent color. The corresponding brightness value from the bg is applied via weighted mean to the input color brightness, the result is compared the the relevant cutoff. By default graphics::par("bg") is used to determine the default plot background color, only when there is an open graphics device, otherwise calling graphics::par("bg") would open a graphics device, which is not desireable. When no graphics device is open, and when bg=NULL, the default is bg="white".
• ...: additional arguments are ignored.

Returns

character vector of R colors.

Details

The color is expected to represent a background color, the output is intended to be a color with enough contrast to read text legibly.

The brightness of the color is detected dependent upon the colorModel: when "hcl" the luminance L is compared to hclCutoff; when "rgb" the brightness is the sum of the RGB channels which is compared to rgbCutoff. In most cases the "hcl" and L will be more accurate.

When color contains transparency, an optional argument bg

represents the figure background color, as if the color is used to draw a color-filled rectangle. In this case, the bg

and color are combined to determine the resulting actual color. This scenario is mostly useful when plotting text labels on a dark background, such as black background with colored text boxes.

Examples

color <- c("red","yellow","lightblue","darkorchid1","blue4");
setTextContrastColor(color);

# showColors() uses setTextContrastColor() for labels
showColors(color)
# printDebugI() uses setTextContrastColor() for foreground text
printDebugI(color)

# demonstrate the effect of alpha transparency
colorL <- lapply(nameVector(c(1, 0.9, 0.8, 0.6, 0.3)), function(i){
   nameVector(alpha2col(color, alpha=i), color);
})
jamba::showColors(colorL,
   groupCellnotes=FALSE,
   srtCellnote=seq(from=15, to=-15, length.out=5));
graphics::title(ylab="alpha", line=1.5);

# change background to dark blue
withr::with_par(list("bg"="navy", "col"="white", "col.axis"="white"), {
jamba::showColors(colorL,
   groupCellnotes=FALSE,
   srtCellnote=seq(from=15, to=-15, length.out=5))
graphics::title(ylab="alpha", line=1.5);
})

# Example using transparency and drawLabels()
bg <- "blue4";
col <- fixYellow("palegoldenrod");
nullPlot(fill=bg, plotAreaTitle="", doMargins=FALSE);
for (alpha in c(0.1, 0.3, 0.5, 0.7, 0.9)) {
   labelCol <- setTextContrastColor(
      alpha2col("yellow", alpha),
      bg=bg);
   drawLabels(x=1 + alpha,
      y=2 - alpha,
      labelCex=1.5,
      txt="Plot Title",
      boxColor=alpha2col(col, alpha),
      boxBorderColor=labelCol,
      labelCol=labelCol);
}

See Also

Other jam color functions: alpha2col(), applyCLrange(), col2alpha(), col2hcl(), col2hsl(), col2hsv(), color2gradient(), fixYellow(), fixYellowHue(), getColorRamp(), hcl2col(), hsl2col(), hsv2col(), isColor(), kable_coloring(), makeColorDarker(), rainbow2(), rgb2col(), setCLranges(), showColors(), unalpha(), warpRamp()