[Rd] undocumented 'offset' argument in src/library/grDevices/man/adjustcolor.Rd

[Wollschlaeger, Daniel]

One might say that adjustcolor() performs affine color transformation. Argument 'offset' defines the shift in color space after the linear transformation defined by argument 'transform'. In other words, 'offset' represents additive color mixing (in the sense of adding lights, not paints) after linear transformation.

> red <- rgb(1, 0, 0)
> green <- c(0, 0.9, 0, 1)
> adjustcolor(red, 1, 0.9, 0.9, 0.9, offset=green)
[1] "#E6E600FF"

("red + green = yellow")

However, the implementation of adjustcolor() is a bit inconsistent with this description as it does not force 'offset' to be a color by using col2rgb(offset, alpha=TRUE)/255. The help page already gives an example for using 'offset' for the purpose of adding white light.
________________________________________
Von: R-devel <r-devel-bounces using r-project.org> im Auftrag von Martin Maechler <maechler using stat.math.ethz.ch>
Gesendet: Mittwoch, 2. Dezember 2020 09:45:27
An: Ben Bolker
Cc: r-devel using r-project.org
Betreff: Re: [Rd] undocumented 'offset' argument in src/library/grDevices/man/adjustcolor.Rd

>>>>> Ben Bolker
>>>>>     on Mon, 30 Nov 2020 16:33:23 -0500 writes:

    > The 'offset' argument description is blank ...
    > maybe 'additive adjustment to each of the (red, green, blue, alpha)
    > values defining the colors, after adjustment by the corresponding
    > \code{.f} factor' ...?

Thank you, Ben.   I'm using adjustcolor() very often, and I had
also wondered about the documentation "FIXME" there.

As I've not been a real expert in color space transformations, I
hadn't dared to describe it myself,  but your description above
is clearly better than the emptyness ...

Maybe someone can add something, or contribute some example(s)
on how using offset != 0  makes sense ?

    > This is the relevant code:

>      x <- col2rgb(col, alpha = TRUE)/255
>      x[] <- pmax(0, pmin(1,
>                          transform %*% x +
>                          matrix(offset, nrow = 4L, ncol = ncol(x))))
>      rgb(x[1L,], x[2L,], x[3L,], x[4L,])

______________________________________________
R-devel using r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel