pth_distance_euclid: Color distance calculations

In ijlyttle/colorpath: Build Color Paths

Color distance calculations

Description

There are two ways to make a color-distance calculation: pth_distance_euclid(), which calculates a Euclidean distance within a color space, or pth_distance_metric(), which uses a color metric in farver::compare_colour() to calculate the distance. Note that distances calculated using pth_distance_metric() may not follow the triangle inequality.

Usage

pth_distance_euclid(
  color_a,
  color_b = NULL,
  transformer = NULL,
  non_luminance_weight = 1,
  ...
)

pth_distance_metric(
  color_a,
  color_b = NULL,
  method = c("cie2000", "cie94", "cie1976", "cmc")
)

Arguments

color_a, color_b	Objects that can be coerced into colors, i.e. pth_hex or pth_mat.
transformer	function used to transform the colors to new color space, e.g. pth_to_cieluv.
non_luminance_weight	numeric used to "discount" the effects of chroma and hue in the distance calculation.
...	additional arguments passed on to transformer.
method	character metric used by farver::compare_colour().

Details

For both of these functions, you can specify two sets of colors: color_a and color_b. Each of these has to be a vector of hex codes (character or pth_hex), or a matrix-based collection of colors (pth_mat) using a specific color space, e.g. cieluv.

For both functions, the number of colors in each of color_a and color_b determines the distance measurements that are returned:

• If color_b is NULL, it returns the distances between consecutive colors in color_a. The length of the returned vector will be one less than the number of colors in color_a.

• If color_b has only one color, it returns the distances between each color in color_a and the one color in color_b. The length of the returned vector will be equal to the number of colors in color_a.

• If color_a and color_b have equal numbers of colors, it returns the pairwise distances between each color in color_a and color_b. The length of the returned vector will be equal to the number of colors in color_a (and color_b).

• For any other arrangement, an error will be thrown.

For pth_distance_euclid(), you can specify the color space in which you wish to make the distance calculation by specifying a function that converts to that color space. For example, if you want to use the Jzazbz-100 color space, set transformer to pth_to_jzazbz100. You can use the ... to provide additional arguments to the transformer function.

The default behavior of transformer depends on color_a and color_b:

• If color_a and color_b are both hex codes, default is to use pth_to_cieluv.

• If color_a and color_b are both specified using the same color space, the default is to use the that color space.

• If color_a and color_b use difference color spaces or representations, the default is not determined; you have to specify a transformer or an error is thrown.

At present, the argument non_luminance_weight is an experiment. This gives you a way to weight the perceptual distances to favor luminance. For example, if you set non_luminance_weight to zero, it will return the differences in luminance in the given color space.

The pth_distance_metric() uses farver::compare_colour() to calculate the distance between colors. These methods use metric functions; the triangle inequality is not necessarily satisfied. You can specify the method; this is passed on to farver::compare_colour().

Value

double one value representing distance for each color comparison.

Examples

hex <- c("#000000", "#663399", "#ffffff")
luv <- pth_to_cieluv(hex)

# calculates distances between consecutive elements of `hex`,
# when providing `pth_hex`, the default is to use `cieluv` color space:
pth_distance_euclid(hex)

# if we provide a matrix that has a color space, the distances are
# calculated using that color space; in this case we expect the same
# distances as above:
pth_distance_euclid(luv)

# we can calculate both using a different color space by specifying a
# `transformer`; we will get a different set of distances from above,
# but they remain internally consistent:
pth_distance_euclid(hex, transformer = pth_to_cam02ucs)
pth_distance_euclid(luv, transformer = pth_to_cam02ucs)

# to calculate pairwise distances, specify `color_a` and `color_b`,
# each with the same length:
pth_distance_euclid(hex[1:2], hex[2:3])

# to calculate distances from a reference, set `color_b` to the reference:
pth_distance_euclid(hex, hex[1])

# using a metric follows the same principles; the calculation uses
# farver::compare_colour(), you can specify the `method`:
pth_distance_metric(hex, method = "cie94")

# calculate distance for adjacent colors:
pth_distance_metric(hex)

# calculate pairwise distances:
pth_distance_metric(hex[1:2], hex[2:3])

# calculate distance from reference:
pth_distance_metric(hex, hex[1])

ijlyttle/colorpath documentation built on Sept. 13, 2022, 7:44 p.m.