farver/ 0000755 0001762 0000144 00000000000 14620357125 011544 5 ustar ligges users farver/NAMESPACE 0000644 0001762 0000144 00000000563 14616657233 012777 0 ustar ligges users # Generated by roxygen2: do not edit by hand
export(add_to_channel)
export(as_white_ref)
export(cap_channel)
export(compare_colour)
export(convert_colour)
export(decode_colour)
export(decode_native)
export(encode_colour)
export(encode_native)
export(get_channel)
export(multiply_channel)
export(raise_channel)
export(set_channel)
useDynLib(farver, .registration = TRUE)
farver/LICENSE.note 0000644 0001762 0000144 00000002450 14616657233 013526 0 ustar ligges users This package contains the C++ library ColorSpace developed by Berendea Nicholae
and released under the MIT license. The full license for this is reproduced
below.
________________________________________________________________________________
MIT License
Copyright (c) 2017 Berendea Nicolae
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
farver/LICENSE 0000644 0001762 0000144 00000000061 14616657233 012556 0 ustar ligges users YEAR: 2018
COPYRIGHT HOLDER: Thomas Lin Pedersen
farver/README.md 0000644 0001762 0000144 00000016207 14616707636 013044 0 ustar ligges users
# farver
[](https://github.com/thomasp85/farver/actions/workflows/R-CMD-check.yaml)
[](https://cran.r-project.org/package=farver)
[](https://cran.r-project.org/package=farver)
[](https://app.codecov.io/gh/thomasp85/farver?branch=main)
The goal of farver is to provide very fast, vectorised functions for
conversion of colours between different colour spaces, colour
comparisons (distance between colours), encoding/decoding, and channel
manipulation in colour strings. To this end it provides an interface to
a modified version of the
[ColorSpace](https://github.com/berendeanicolae/ColorSpace) C++ library
developed by Berendea Nicolae.
## Installation
farver can be installed from CRAN using `install.packages('farver')`.
The development version can be installed from Github using `devtools`:
``` r
# install.packages('devtools')
devtools::install_github('thomasp85/farver')
```
## Use
farver provides an alternative to the `grDevices::rgb()` and
`grDevices::col2rgb()` for encoding and decoding colours strings. The
farver functions are superficially equivalent but provides a uniform
output format, and the option to encode and decode directly from/to
other colour spaces.
``` r
library(farver)
codes <- rainbow(10)
codes
#> [1] "#FF0000" "#FF9900" "#CCFF00" "#33FF00" "#00FF66" "#00FFFF" "#0066FF"
#> [8] "#3300FF" "#CC00FF" "#FF0099"
spectrum <- decode_colour(codes)
spectrum
#> r g b
#> [1,] 255 0 0
#> [2,] 255 153 0
#> [3,] 204 255 0
#> [4,] 51 255 0
#> [5,] 0 255 102
#> [6,] 0 255 255
#> [7,] 0 102 255
#> [8,] 51 0 255
#> [9,] 204 0 255
#> [10,] 255 0 153
encode_colour(spectrum)
#> [1] "#FF0000" "#FF9900" "#CCFF00" "#33FF00" "#00FF66" "#00FFFF" "#0066FF"
#> [8] "#3300FF" "#CC00FF" "#FF0099"
```
It also provides an alternative to `grDevices::convertColor()` to switch
between colours spaces. If the origin is a colour string it is possible
to decode directly into the given colour space. Conversely, if the
endpoint is a colour string it is also possible to encode directly from
a given colour space.
``` r
spectrum_lab <- convert_colour(spectrum, 'rgb', 'lab')
spectrum_lab
#> l a b
#> [1,] 53.24079 80.09796 67.20432
#> [2,] 72.26072 30.17136 77.22610
#> [3,] 93.60533 -41.93879 90.27635
#> [4,] 88.07403 -83.10282 83.59544
#> [5,] 88.19634 -80.27407 57.92961
#> [6,] 91.11322 -48.08151 -14.12690
#> [7,] 47.90478 35.20130 -82.00196
#> [8,] 33.81896 79.70472 -105.27489
#> [9,] 51.90416 91.00028 -74.83009
#> [10,] 55.65103 86.53436 -9.71618
decode_colour(codes, to = 'lab')
#> l a b
#> [1,] 53.24079 80.09796 67.20432
#> [2,] 72.26072 30.17136 77.22610
#> [3,] 93.60533 -41.93879 90.27635
#> [4,] 88.07403 -83.10282 83.59544
#> [5,] 88.19634 -80.27407 57.92961
#> [6,] 91.11322 -48.08151 -14.12690
#> [7,] 47.90478 35.20130 -82.00196
#> [8,] 33.81896 79.70472 -105.27489
#> [9,] 51.90416 91.00028 -74.83009
#> [10,] 55.65103 86.53436 -9.71618
encode_colour(spectrum_lab, from = 'lab')
#> [1] "#FF0000" "#FF9900" "#CCFF00" "#33FF00" "#00FF66" "#00FFFF" "#0066FF"
#> [8] "#3300FF" "#CC00FF" "#FF0099"
```
If colours are given as strings, manipulation of channels will normally
require decoding, conversion to the correct colour space, manipulation
of the given channel, converting back to rgb and the encoding to string.
farver provides a range of functions that allow you to change any
channel in the supported spaces directly in colour strings:
``` r
# Add a value to the channel
add_to_channel(codes, channel = 'l', value = 1:10, space = 'lab')
#> [1] "#FF0C03" "#FF9E0E" "#D5FF1C" "#48FF20" "#33FF74" "#3CFFFF" "#3D77FF"
#> [8] "#5A25FF" "#E839FF" "#FF41B4"
# Set a channel to a specific value
set_channel(codes, 'alpha', c(0.3, 0.7))
#> [1] "#FF00004C" "#FF9900B2" "#CCFF004C" "#33FF00B2" "#00FF664C" "#00FFFFB2"
#> [7] "#0066FF4C" "#3300FFB2" "#CC00FF4C" "#FF0099B2"
# Limit a channel to a given value
cap_channel(codes, 'r', 200)
#> [1] "#C80000" "#C89900" "#C8FF00" "#33FF00" "#00FF66" "#00FFFF" "#0066FF"
#> [8] "#3300FF" "#C800FF" "#C80099"
```
Lastly, farver also provides utilities for calculating the distance
between colours, based on a range of different measures
``` r
spectrum2 <- t(col2rgb(heat.colors(10)))
compare_colour(spectrum, spectrum2, 'rgb', method = 'cie2000')[1:6, 1:6]
#> [,1] [,2] [,3] [,4] [,5] [,6]
#> [1,] 0.00000 1.95065 7.130898 15.53837 27.08237 39.88958
#> [2,] 29.50083 27.56585 22.402612 13.98117 2.41602 10.31341
#> [3,] 72.33606 70.32974 64.926436 55.98592 43.59987 30.24747
#> [4,] 85.84698 83.68842 77.854648 68.19997 55.06314 41.59064
#> [5,] 85.92110 83.79762 78.073545 68.67184 56.07682 43.42965
#> [6,] 70.95853 69.55274 65.907013 60.35739 53.72218 47.94387
```
## Supported colour spaces
`farver` currently supports the following colour spaces:
- CMY
- CMYK
- HSL
- HSB
- HSV
- CIE L\*AB
- Hunter LAB
- OK LAB
- LCH(ab)
- LCH(uv)
- LCH(OK)
- LUV
- RGB
- XYZ
- YXY
## Supported distance measures
`farver` supports the following colour distance metrics
- Euclidean
- CIE1976
- CIE94
- CIE2000
- CMC
## White References
`farver` allows you to set the white point for relative colour spaces,
either based on a standard illuminant (A-F series supported) or by
specifying chromaticity coordinates or tristimulus values directly
## Benchmark
`farver` is faster than its `grDevices` counterpart but less so than it
was at its first release, as the colour conversion in grDevices has been
improved since.
``` r
library(ggplot2)
test <- matrix(runif(300000, min = 0, max = 255), ncol = 3)
timing <- bench::mark(
farver = convert_colour(test, 'rgb', 'lab'),
grDevices = convertColor(test, 'sRGB', 'Lab', scale.in = 255),
check = FALSE,
min_iterations = 100
)
#> Warning: Some expressions had a GC in every iteration; so filtering is disabled.
plot(timing, type = 'ridge')
```

Still, if the start- and/or endpoint are colour strings the ability to
decode and encode directly from/to any colour space will give a huge
speed up.
``` r
colour_strings <- colours()
timing <- bench::mark(
farver = decode_colour(colour_strings, to = 'lab'),
grDevices = convertColor(t(col2rgb(colour_strings)), 'sRGB', 'Lab', scale.in = 255),
check = FALSE,
min_iterations = 100
)
plot(timing, type = 'ridge')
```

## Code of Conduct
Please note that the ‘farver’ project is released with a [Contributor
Code of
Conduct](https://farver.data-imaginist.com/CODE_OF_CONDUCT.html). By
contributing to this project, you agree to abide by its terms.
farver/man/ 0000755 0001762 0000144 00000000000 14616657233 012327 5 ustar ligges users farver/man/decode_colour.Rd 0000644 0001762 0000144 00000006146 14616657233 015433 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/decode.R
\name{decode_colour}
\alias{decode_colour}
\title{Decode RGB hex-strings into colour values}
\usage{
decode_colour(colour, alpha = FALSE, to = "rgb", white = "D65", na_value = NA)
}
\arguments{
\item{colour}{A character vector of hex-encoded values or a valid colour name
as given in \code{\link[grDevices:colors]{grDevices::colours()}}.}
\item{alpha}{If \code{TRUE} the alpha channel will be returned as well (scaled
between 0 and 1). If no alpha channel exists in the colour it will be
assumed 1. If \code{FALSE} any alpha channel is ignored.}
\item{to}{The output colour space. Allowed values are: \code{"cmy"},
\code{"cmyk"}, \code{"hsl"}, \code{"hsb"}, \code{"hsv"}, \code{"lab"} (CIE L*ab), \code{"hunterlab"}
(Hunter Lab), \code{"oklab"}, \code{"lch"} (CIE Lch(ab) / polarLAB), \code{"luv"},
\code{"rgb"} (sRGB), \code{"xyz"}, \code{"yxy"} (CIE xyY), \code{"hcl"} (CIE Lch(uv) / polarLuv),
or \code{"oklch"} (Polar form of oklab)}
\item{white}{The white reference of the output colour space. Will only have
an effect for relative colour spaces such as Lab and luv. Any value accepted
by \code{\link[=as_white_ref]{as_white_ref()}} allowed.}
\item{na_value}{A valid colour string or \code{NA} to use when \code{colour} contains
\code{NA} elements. The general approach in farver is to carry \code{NA} values over,
but if you want to mimick \code{\link[=col2rgb]{col2rgb()}} you should set
\code{na_value = 'transparent'}, i.e. treat \code{NA} as transparent white.}
}
\value{
A numeric matrix with a row for each element in \code{colour} and either
3, 4, or 5 columns depending on the value of \code{alpha} and \code{to}.
}
\description{
This is a version of \code{\link[grDevices:col2rgb]{grDevices::col2rgb()}} that returns the colour values in
the standard form expected by farver (matrix with a row per colour). As with
\code{\link[=encode_colour]{encode_colour()}} it can do colour conversion on the fly, meaning that you can
decode a hex string directly into any of the supported colour spaces.
}
\section{Handling of non-finite and out of bounds values}{
\code{NA}, \code{NaN}, \code{-Inf}, and \code{Inf} are treated as invalid input and will result
in \code{NA} values for the colour. If a given colourspace has finite bounds in
some of their channels, the input will be capped before conversion, and the
output will be capped before returning, so that both input and output colours
are valid colours in their respective space. This means that converting back
and forth between two colourspaces may result in a change in the colour if
the gamut of one of the spaces is less than the other.
}
\examples{
# basic use
decode_colour(c('#43e1f6', 'steelblue', '#67ce9fe4'))
# Return alpha as well (no alpha value is interpreted as 1)
decode_colour(c('#43e1f6', 'steelblue', '#67ce9fe4'), alpha = TRUE)
# Decode directly into specific colour space
decode_colour(c('#43e1f6', 'steelblue', '#67ce9fe4'), to = 'lch')
}
\seealso{
Other encoding and decoding functions:
\code{\link{encode_colour}()},
\code{\link{manip_channel}}
}
\concept{encoding and decoding functions}
farver/man/farver-package.Rd 0000644 0001762 0000144 00000002601 14620347561 015466 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/farver-package.R
\docType{package}
\name{farver-package}
\alias{farver}
\alias{farver-package}
\title{farver: High Performance Colour Space Manipulation}
\description{
\if{html}{\figure{logo.png}{options: style='float: right' alt='logo' width='120'}}
The encoding of colour can be handled in many different ways, using different colour spaces. As different colour spaces have different uses, efficient conversion between these representations are important. The 'farver' package provides a set of functions that gives access to very fast colour space conversion and comparisons implemented in C++, and offers speed improvements over the 'convertColor' function in the 'grDevices' package.
}
\seealso{
Useful links:
\itemize{
\item \url{https://farver.data-imaginist.com}
\item \url{https://github.com/thomasp85/farver}
\item Report bugs at \url{https://github.com/thomasp85/farver/issues}
}
}
\author{
\strong{Maintainer}: Thomas Lin Pedersen \email{thomas.pedersen@posit.co} (\href{https://orcid.org/0000-0002-5147-4711}{ORCID})
Authors:
\itemize{
\item Berendea Nicolae (Author of the ColorSpace C++ library)
\item Romain François \email{romain@purrple.cat} (\href{https://orcid.org/0000-0002-2444-4226}{ORCID})
}
Other contributors:
\itemize{
\item Posit, PBC [copyright holder, funder]
}
}
\keyword{internal}
farver/man/encode_colour.Rd 0000644 0001762 0000144 00000005376 14616657233 015451 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/encode.R
\name{encode_colour}
\alias{encode_colour}
\title{Encode colours into RGB hex-strings}
\usage{
encode_colour(colour, alpha = NULL, from = "rgb", white = "D65")
}
\arguments{
\item{colour}{A numeric matrix (or an object coercible to one) with colours
encoded in the rows and the different colour space values in the columns. For
all colourspaces except \code{'cmyk'} this will mean a matrix with three columns -
for \code{'cmyk'} it means four columns.}
\item{alpha}{A numeric vector between 0 and 1. Will be recycled to the number
of rows in \code{colour}. If \code{NULL} or a single \code{NA} it will be ignored.}
\item{from}{The input colour space. Allowed values are: \code{"cmy"},
\code{"cmyk"}, \code{"hsl"}, \code{"hsb"}, \code{"hsv"}, \code{"lab"} (CIE L*ab), \code{"hunterlab"}
(Hunter Lab), \code{"oklab"}, \code{"lch"} (CIE Lch(ab) / polarLAB), \code{"luv"},
\code{"rgb"} (sRGB), \code{"xyz"}, \code{"yxy"} (CIE xyY), \code{"hcl"} (CIE Lch(uv) / polarLuv),
or \code{"oklch"} (Polar form of oklab)}
\item{white}{The white reference of the input colour space. Will only have an
effect for relative colour spaces such as Lab and luv. Any value accepted by
\code{\link[=as_white_ref]{as_white_ref()}} allowed.}
}
\value{
A character vector with colours encoded as \verb{#RRGGBB(AA)}
}
\description{
This is a version of \code{\link[grDevices:rgb]{grDevices::rgb()}} that works with the standard colour
format used in farver (matrix or data.frame with colours in rows). It further
support taking input from any colour space.
}
\note{
The output may differ slightly from that of \code{\link[grDevices:rgb]{grDevices::rgb()}} since
\code{rgb()} doesn't round numeric values correctly.
}
\section{Handling of non-finite and out of bounds values}{
\code{NA}, \code{NaN}, \code{-Inf}, and \code{Inf} are treated as invalid input and will result
in \code{NA} values for the colour. If a given colourspace has finite bounds in
some of their channels, the input will be capped before conversion, and the
output will be capped before returning, so that both input and output colours
are valid colours in their respective space. This means that converting back
and forth between two colourspaces may result in a change in the colour if
the gamut of one of the spaces is less than the other.
}
\examples{
spectrum <- decode_colour(rainbow(10))
encode_colour(spectrum)
# Attach alpha values
encode_colour(spectrum, alpha = c(0.5, 1))
# Encode from a different colour space
spectrum_hcl <- convert_colour(spectrum, 'rgb', 'hcl')
encode_colour(spectrum_hcl, from = 'hcl')
}
\seealso{
Other encoding and decoding functions:
\code{\link{decode_colour}()},
\code{\link{manip_channel}}
}
\concept{encoding and decoding functions}
farver/man/native_encoding.Rd 0000644 0001762 0000144 00000003266 14616702521 015750 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/native.R
\name{native-encoding}
\alias{native-encoding}
\alias{encode_native}
\alias{decode_native}
\title{Convert to and from the R native colour representation}
\usage{
encode_native(colour, ...)
decode_native(colour)
}
\arguments{
\item{colour}{For \code{encode_native} either a vector of hex-encoded
colours/colour names or a matrix encoding colours in any of the supported
colour spaces. If the latter, the colours will be encoded to a hex string
using \code{\link[=encode_colour]{encode_colour()}} first. For \code{decode_native} it is a vector of
integers.}
\item{...}{Arguments passed on to \code{\link[=encode_colour]{encode_colour()}}}
}
\value{
\code{encode_native()} returns an integer vector and \code{decode_native()}
returns a character vector, both matching the length of the input.
}
\description{
Colours in R are internally encoded as integers when they are passed around
to graphics devices. The encoding splits the 32 bit in the integer between
red, green, blue, and alpha, so that each get 8 bit, equivalent to 256
values. It is very seldom that an R user is subjected to this representation,
but it is present in the \code{nativeRaster} format which can be obtained from
e.g. capturing the content of a graphic device (using \code{dev.capture()}) or reading
in PNG files using \code{png::readPNG(native = TRUE)}. It is very rare that you
might need to convert back and forth between this format, but it is provided
here for completeness.
}
\examples{
# Get native representation of navyblue and #228B22
native_col <- encode_native(c('navyblue', '#228B22'))
native_col
# Convert back
decode_native(native_col)
}
farver/man/figures/ 0000755 0001762 0000144 00000000000 14616707636 013776 5 ustar ligges users farver/man/figures/README-unnamed-chunk-7-1.png 0000644 0001762 0000144 00000063475 14616707636 020515 0 ustar ligges users PNG
IHDR z4 iCCPkCGColorSpaceGenericRGB 8U]hU>+$Ԧ5lRфem,lAݝi&3i)>A['!j-P(G 3k~s,[%,-:t}
}-+*&¿ gPG݅ج8"e Ų]A b ;l õ Wϙ2_E,(ۈ#Zsێ<5)"E6N#ӽEkۃO0}*rUt.iei # ]r
>cU{t7+ԙg߃xu