color2gradient: Make a color gradient
In jmw86069/jamba: Jam Base Methods

color2gradient

R Documentation

Make a color gradient

Description

Make a color gradient

Usage

color2gradient(
  col,
  n = NULL,
  gradientWtFactor = NULL,
  dex = 1,
  reverseGradient = TRUE,
  verbose = FALSE,
  ...
)

Arguments

`col`	some type of recognized R color input as: `character` vector of one or more individual colors, each color is expanded into a gradient of length `n`, where `n` is recycled to the number of unique colors. The value `n` is applied in the order the colors appear in `col`. `list` of color vectors where each vector contains one repeated color `character` vector of repeated colors, where `n` is defined by the number of each color present.
`n`	`integer` vector of length one or more, which defines the number of colors to return for each gradient. When `n=0` then only duplicated colors will be expanded into a gradient.
`gradientWtFactor`	`numeric` fraction representing the amount to expand a color toward its maximum brightness and darkness. It is recommended to use `dex` and not this argument. When `gradientWtFactor=NULL` this value is calculated based upon the number of colors requested, and the initial luminance in HCL space of the starting color. When `gradientWtFactor` is defined, values are recycled to `length(col)`, and can be independently applied to each color.
`dex`	`numeric` value to apply dramatic dark expansion, where: `dex > 1` will make the gradient more dramatic, values `dex < 1` will make the gradient less dramatic, and are considered fractions 1/x. `dex < 0` will make the gradient less dramatic, and values are internally converted to fractions using `1/(2 + abs(dex))`
`reverseGradient`	`logical` whether to return light-to-dark gradient (TRUE) or dark-to-light gradient (FALSE).
`verbose`	`logical` whether to print verbose output.
`...`	other parameters are ignored.

Details

This function converts a single color into a color gradient by expanding the initial color into lighter and darker colors around the central color. The amount of gradient expansion is controlled by gradientWtFactor, which is a weight factor scaled to the maximum available range of bright to dark colors.

As an extension, the function can take a vector of colors, and expand each into its own color gradient, each with its own number of colors. If a vector with supplied that contains repeated colors, these colors are expanded in-place into a gradient, bypassing the value for n.

If a list is supplied, a list is returned of the same length, where each vector inside the list is a color gradient of length specified by n. If the input list contains multiple values, only the first color is used to define the color gradient.

Examples

# given a list, it returns a list
x <- color2gradient(list(Reds=c("red"), Blues=c("blue")), n=c(4,7));
showColors(x);

# given a vector, it returns a vector
xv <- color2gradient(c(red="red", blue="blue"), n=c(4,7));
showColors(xv);

# Expand colors in place
# This process is similar to color jittering
colors1 <- c("red","blue")[c(1,1,2,2,1,2,1,1)];
names(colors1) <- colors1;
colors2 <- color2gradient(colors1);
showColors(list(`Input colors`=colors1, `Output colors`=colors2));

# You can do the same using a list intermediate
colors1L <- split(colors1, colors1);
showColors(colors1L);
colors2L <- color2gradient(colors1L);
showColors(colors2L);

# comparison of fixed gradientWtFactor with dynamic gradientWtFactor
showColors(list(
   `dynamic\ngradientWtFactor\ndex=1`=color2gradient(
      c("yellow", "navy", "firebrick", "orange"),
      n=3,
      gradientWtFactor=NULL,
      dex=1),
   `dynamic\ngradientWtFactor\ndex=2`=color2gradient(
      c("yellow", "navy", "firebrick", "orange"),
      n=3,
      gradientWtFactor=NULL,
      dex=2),
   `fixed\ngradientWtFactor=2/3`=color2gradient(
      c("yellow", "navy", "firebrick", "orange"),
      n=3,
      gradientWtFactor=2/3,
      dex=1)
))

jmw86069/jamba documentation built on Oct. 9, 2024, 10:52 a.m.