farver/ 0000755 0001762 0000144 00000000000 13610063667 011547 5 ustar ligges users farver/NAMESPACE 0000644 0001762 0000144 00000000461 13607317435 012770 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(encode_colour)
export(get_channel)
export(multiply_channel)
export(raise_channel)
export(set_channel)
useDynLib(farver)
farver/LICENSE.note 0000644 0001762 0000144 00000002450 13562215674 013524 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 13562215674 012554 0 ustar ligges users YEAR: 2018
COPYRIGHT HOLDER: Thomas Lin Pedersen
farver/README.md 0000644 0001762 0000144 00000016346 13562774421 013043 0 ustar ligges users
# farver
[](https://travis-ci.org/thomasp85/farver)
[](https://ci.appveyor.com/project/thomasp85/farver)
[](https://cran.r-project.org/package=farver)
[](https://cran.r-project.org/package=farver)
[](https://codecov.io/github/thomasp85/farver?branch=master)
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] "#FF0000FF" "#FF9900FF" "#CCFF00FF" "#33FF00FF" "#00FF66FF"
#> [6] "#00FFFFFF" "#0066FFFF" "#3300FFFF" "#CC00FFFF" "#FF0099FF"
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.09246 67.203197
#> [2,] 72.26072 30.16539 77.224482
#> [3,] 93.60533 -41.94504 90.274226
#> [4,] 88.07403 -83.10813 83.593379
#> [5,] 88.19634 -80.27943 57.926987
#> [6,] 91.11322 -48.08753 -14.131186
#> [7,] 47.90478 35.19678 -82.006104
#> [8,] 33.81896 79.70044 -105.279006
#> [9,] 51.90416 90.99470 -74.834222
#> [10,] 55.65103 86.52861 -9.719051
decode_colour(codes, to = 'lab')
#> l a b
#> [1,] 53.24079 80.09246 67.203197
#> [2,] 72.26072 30.16539 77.224482
#> [3,] 93.60533 -41.94504 90.274226
#> [4,] 88.07403 -83.10813 83.593379
#> [5,] 88.19634 -80.27943 57.926987
#> [6,] 91.11322 -48.08753 -14.131186
#> [7,] 47.90478 35.19678 -82.006104
#> [8,] 33.81896 79.70044 -105.279006
#> [9,] 51.90416 90.99470 -74.834222
#> [10,] 55.65103 86.52861 -9.719051
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] "#FF0C03FF" "#FF9E0EFF" "#D5FF1CFF" "#48FF20FF" "#33FF74FF"
#> [6] "#3CFFFFFF" "#3D77FFFF" "#5A25FFFF" "#E839FFFF" "#FF41B4FF"
# Set a channel to a specific value
set_channel(codes, 'alpha', c(0.3, 0.7))
#> [1] "#FF00004C" "#FF9900B2" "#CCFF004C" "#33FF00B2" "#00FF664C"
#> [6] "#00FFFFB2" "#0066FF4C" "#3300FFB2" "#CC00FF4C" "#FF0099B2"
# Limit a channel to a given value
cap_channel(codes, 'r', 200)
#> [1] "#C80000FF" "#C89900FF" "#C8FF00FF" "#33FF00FF" "#00FF66FF"
#> [6] "#00FFFFFF" "#0066FFFF" "#3300FFFF" "#C800FFFF" "#C80099FF"
```
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
- LCH(ab)
- LCH(uv)
- 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
)
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 13562472166 012326 5 ustar ligges users farver/man/decode_colour.Rd 0000644 0001762 0000144 00000006061 13607061751 015420 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:colours]{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{"lch"} (CIE Lch(ab) / polarLAB), \code{"luv"}, \code{"rgb"} (sRGB),
\code{"xyz"}, \code{"yxy"} (CIE xyY), or \code{"hcl"} (CIE Lch(uv) / polarLuv)}
\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 00000002501 13607061751 015463 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: align='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{thomasp85@gmail.com} (\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})
}
}
\keyword{internal}
farver/man/encode_colour.Rd 0000644 0001762 0000144 00000005310 13607061751 015426 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{"lch"} (CIE Lch(ab) / polarLAB), \code{"luv"}, \code{"rgb"} (sRGB),
\code{"xyz"}, \code{"yxy"} (CIE xyY), or \code{"hcl"} (CIE Lch(uv) / polarLuv)}
\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/figures/ 0000755 0001762 0000144 00000000000 13562622625 013767 5 ustar ligges users farver/man/figures/README-unnamed-chunk-7-1.png 0000644 0001762 0000144 00000071410 13562622624 020471 0 ustar ligges users PNG
IHDR z4 iCCPkCGColorSpaceGenericRGB 8U]h U>sg#$Sl4t?
%
V46nI6"dΘ83OEP|1Ŀ (>/
% (>P苦;3ie|{g蹪X-2s=+WQ +]L6O w[C{_F q b Uvz ?Z b1@/zcs>~if,ӈUSjF 1_Mjbuݠpamhmçϙ>a\+5%QKFkm} ۖ?ޚD\!~6,-7SثŜvķ5Z;[rmS5{yDyH}r9|-ăFAJjI.[/]mK 7 KRDrYQO-Q||6
(0
MXd(@h2_f<:_δ*d>e\c?~,7?& ك^2Iq2"y@ g|U\ @ IDATx_z&HGz.EQwc"JD1FFcKb" Ҥ)R)Hrm|>s̞3Nm&#A @ OJ @ # D @ +h^qS @ s @ yMa @ P@ ("^تUlӦM2-[6nM㒰*/_vlْ`;lѢEΈ5kڅ^hݺu3 ר|:|
p rdɒVD w~ XgYL6~W[m -M_H|nذ!9w+V4=@5ի͛#]| tA_ly=vG+b x`l uK$k 7fp
TR=o9A G믷kڵ^k5zW_m-[s=ז,Y:S!@ m[, L0}];SF۩.]uۿy@ &L |&p}Y:uW^;Dk};}@ U g϶aÆ1 cRXݻկ_¾f (jb 0` $ۯ%L;8mĉE E -@ `W_ =zUo}5ezGۍ d 4+@|g?[Ϟ=wY9s9CmРAx] 2! ̈́ B 0Y͚5Kx/RR t @%q L@+ɛٵkW'*jʕݪHdh h&8@@ (%@SI p6nܸTc_@ )@! '|bZO+ ڷooUV7x#@J)bg@ ڶm[Vt*5VH}W7> @. @sA?~URԩq-:wls̱> @"h"
C 9`ԼyX!2$+ #+ ظqM<F)ivsbvСȎ< l' ݎ7 M`ڴi&-* ;vtׯ_ n8 h@ Hĉ]y&MϤ߰ay
|G@ i@ W_}e
4rer7ʕ+ó'A @r@ y@%=?䓈P @ Ah @ CWo֚6maN; .:k,[d_@i@@ A#0i$W\ Pe>rȠM} @6 DSLҥK[Æ
7g}5nݺge%?2 HH{}駹Ț)! N[Β7|Ӛ7o"F^{ζmR!@g'2 kM{@ I@&R%qF7Kcǎo\)So
69s)a6'NL{@ I@&R%0n8[no~a)S>xG@KpJ {W[T\9Ɓz@x R" M ;'K@"RJִihۑif3}beK*e͚5C&B= 4hҨ1&Lpc?Kk۶aO@4KpVSj|嗶u¾f " ܍/ M(kE&9cƌ2do@`~y?fl| T @SžIXhXY7n4iRRy P8/Sg\(| B
-M760h
^z,͙Iv@-[,7VZbEA@%WD 4ʭm~آVgv (!/֩Ny?h0px]' ymҤ͜9Ӎ
$O@ҥK[ݺu?(G{*,\0G%- E(6}7Ez?U5Mؼy sU) $ H4^nx[!.pW(j;obh f
=TA# 5jH 4J4K,ETFիW7M^J.$@ 5=Û!knxƁ&= +]hmjW! P A 5~mڴ8唽%@5.u˔ H@Fyoܹs]k.puk" H@f{5 ݶm[+ @w) Zb/`y@-ݲeKq P; =3Znm͘1#ub@0 @+W.){qF[hQRL@|@N@E?6
@PB1 v+/\@ӡ1q#ôpCg{m`7Fz@x $ -
_J@v}T 42v1u+Y~
4zh%A ( H4|*u"@+Ud*T@
cI@Tm29^?۬Y\ML sDŋ[S2Ix@SB1%0y{?4j QbR
$C %%+VUPR3 %^v9[bj|eГ7~ _) te9Ȝ#~PP!hӦJ< d @F`JZj)UG P ٽ$@paʂmۚzEMVAl bO S ; 4S) ħ'`Sr@h~[UV
aZI5}g/ O ,Q]^|z(t0;C &&Mw5
J?bĈfB @J %j&/oN%A ;$`jҤ_xǎ &'T
'Q+V TAʕҝШؓ-vZkڴiK>ڵs˼G!@ @^h!|? $@&},Y h90$@5VJ*V 6lXMe! @sKQ˗/0LB)q?~|=s;t`ӧO7/JW@ P h͛7͘$@`G7nt45k!$D7|HjB y բ.]LK7F (P̊+ڞ{s
˗wovdl@ }q/_8 @9 =iBE)6sL %H@nOl Pfg zkRЀΝ;xA 3G 6Ϫ%jY h͛m۶!}UV(|w[ƍMQ[4?mH(Qd!LL)r| 943M8 ! ({u^MСA/grJ'{Ap\fcZjF_8fƈ#܍RvQL
Jx
ڵkMĦ 7o|ɶxb;ìQF /&ʱ
4un $I PAr %A`Æ
6|p$8={K86cc~̝;>;McK ZR%馛ۍr@ q~Z| :h lhBb+U4l}I?wBI'd j hX.'_&@D(؝J+AY͚5MqHfp8/r <5jKTVP!R5&nݺnf|RSV @1IHQj< vO{eZ*Q HHB. ?ގ=t>}c6D x P-ř$4[4' }]7]!㘴4bŊMcHH>zunn8[nM; L 49NUy@uPEbjR q /Z֭wZ%{6jn=x.Y+&ۇ ~~jBQ&I^ Iñ&YK:0y@9I4Tr#i L:uz]ۿ PMycf9f3%4Qz-۴iSX͠y$1w>s! 4oS#} .w} s1xkOmHE=k55.[urC U5F&ۓ'c@x 3f͚TfÇSwM>R Z
Ы~ڵs yo% .
T3T[lk<ꨣbe{~G 19Y`1O+g^z3Z&vʔ)6gΜqn lW7R.<͠q84 xwC;s )TLT 805nys_~LW~ٲeahF=[O ^^Qg}
Hf
_8 i1cX^rC;vhovNˉkи|v{]ϰq8
