h2hwOptions: Get hue color warp options

h2hwOptionsR Documentation

Get hue color warp options

Description

Get hue color warp options used to convert color wheels

Usage

h2hwOptions(
  h1 = getOption("h2hw.h1"),
  h2 = getOption("h2hw.h2"),
  preset = getOption("colorjam.preset", "custom"),
  direction = NULL,
  default_preset = "dichromat2",
  reset = FALSE,
  setOptions = c("FALSE", "TRUE", "ifnull"),
  verbose = FALSE,
  ...
)

Arguments

h1

numeric vector of color hue values which represent the "from" hue angles, also referred to as "hue warp" or "hw" values. One example of a typical operation: one may want to know the R hue for a particular red-yellow-blue hue. In this scenario the h1 "hue warp" is the red-yellow-blue hue, and the "hue" is the R typical hue used in colorspace::polarLUV() grDevices::hcl(), and farver::convert_colour(). For evenly-spaced red-yellow-blue colors, one would define a sequence of "hue warp" values from 0 to 360, then convert them to the default hue used by other R functions.

h2

numeric vector of color hue values which represent the "to" hue angles, also referred to as "hue" or "h".

preset

character string indicating whether to define h1, and h2 values based upon named presets:

  • "custom" uses values defined in options("h2hw.h1") and options("h2hw.h2") if they exist, otherwise default_preset.

  • other character values obtained by colorjam_presets(), some examples include:

    • "dichromat" (default) color wheel intended to be color-blind friendly by omitting much of the green color region from the color wheel, and by reviewing output by dichromat::dichromat()

    • "ryb" basic red-yellow-blue color wheel

    • "ryb1","ryb2","ryb3" experimental red-yellow-blue alternative color wheels designed to emphasize various features in the red-orange-yellow-green range to varying degrees.

    • "rgb" for the default R red-green-blue color wheel

default_preset

character string indicating which value in preset should be used as the default when reset=FALSE and h1 and/or h2 are not defined in options().

reset

logical whether to reset h1 and h2 values to the default values as defined in h1default and h2default. When reset=TRUE all other preset and default_preset arguments are ignored.

setOptions

character or logical indicating whether to update options() for "h2hw.h1" and "h2hw.h2". When "ifnull" the options() are only updated if they were previously NULL.

verbose

logical whether to print verbose output

Details

This function retrieves and/or defines, the h1 and h2 hue vectors used to convert between h1 "hue warp", and h2 "actual hue".

The "actual" hue is used by standard R #' functions such as colorspace::polarLUV(), grDevices::hcl(), and farver::convert_colour().

The mapping from h1 to h2 allows customization of the spacing and order of colors, which allows emulation of a red-yellow-blue color wheel for example.

The h1 represents the color hue in terms of a degree angle ranging from 0 to 360 - a full circle - for the observer. It is then transformed to h2 for use in generating actual R colors.

  • colorjam_presets() lists all recognized colorjam presets.

  • add_colorjam_preset() will add or overwrite a colorjam preset by name.

In general, most colorjam functions with argument preset will follow this progression:

  • Argument preset=getOption("colorjam.preset", "custom") which uses preset when defined, otherwise "custom".

  • When this option matches a recognized preset name, the corresponding h1,h2 values are used.

  • When preset="custom", arguments h1,h2 will also poll getOption("h2hw.h1") and getOption("h2hw.h2") for default values.

  • When neither h1,h2 is defined, the argument default_preset="dichromat" is used to obtain h1,h2 values.

To disable the warped hue mechanic, set preset="rgb" which usess the default R color wheel with no adjustment.

Details

The h1,h2 values are passed to approx_degrees() to convert hue degree angles. See adjust_hue_warp() for detailed examples of manipulating color warp values.

Value

list with names h1 and h2 containing numeric vectors of hues between 0 and 360.

See Also

Other colorjam hue warp: add_colorjam_preset(), add_colorjam_step(), adjust_hue_warp(), approx_degrees(), colorjam_presets(), colorjam_steps(), display_degrees(), h2hw(), hcl_to_hsl_hue(), hsl_to_hcl_hue(), hw2h(), mean_angle(), plot_colorjam_preset(), remap_colorjam_preset(), validate_colorjam_preset()

Other hue warp functions: h2hw()

Examples

h2hwOptions()
h2hw(60)

h2hwOptions(h1=c(0, 60,120,240,300,360),
   h2=c(0,120,180,240,280,360))
h2hw(300)


jmw86069/colorjam documentation built on March 18, 2024, 3:32 a.m.