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.
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")
)Objects that can be coerced into colors,
i.e. pth_hex or pth_mat.
function used to transform the colors to new
color space, e.g. pth_to_cieluv.
numeric used to "discount" the effects of
chroma and hue in the distance calculation.
additional arguments passed on to transformer.
character metric used by farver::compare_colour().
double one value representing distance for each color comparison.
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().
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)
#> [1] 76.43105 96.23520
# 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)
#> [1] 76.43105 96.23520
# 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)
#> [1] 45.02476 70.13767
pth_distance_euclid(luv, transformer = pth_to_cam02ucs)
#> [1] 45.02475 70.13767
# to calculate pairwise distances, specify `color_a` and `color_b`,
# each with the same length:
pth_distance_euclid(hex[1:2], hex[2:3])
#> [1] 76.43105 96.23520
# to calculate distances from a reference, set `color_b` to the reference:
pth_distance_euclid(hex, hex[1])
#> [1] 0.00000 76.43105 100.00000
# using a metric follows the same principles; the calculation uses
# farver::compare_colour(), you can specify the `method`:
pth_distance_metric(hex, method = "cie94")
#> [1] 71.72568 69.09217
# calculate distance for adjacent colors:
pth_distance_metric(hex)
#> [1] 34.31985 60.27277
# calculate pairwise distances:
pth_distance_metric(hex[1:2], hex[2:3])
#> [1] 34.31985 60.27277
# calculate distance from reference:
pth_distance_metric(hex, hex[1])
#> [1] 0.00000 34.31985 100.00001