Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/thomasp85/farver

High Performance Colourspace Manipulation in R
https://github.com/thomasp85/farver

color-conversion rstats

Last synced: 3 months ago
JSON representation

High Performance Colourspace Manipulation in R

Lists

README 

        
---

output: github_document

---



# farver 



[![R-CMD-check](https://github.com/thomasp85/farver/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/thomasp85/farver/actions/workflows/R-CMD-check.yaml)

[![CRAN_Status_Badge](http://www.r-pkg.org/badges/version-ago/farver)](https://cran.r-project.org/package=farver)

[![CRAN_Download_Badge](http://cranlogs.r-pkg.org/badges/farver)](https://cran.r-project.org/package=farver)

[![Codecov test coverage](https://codecov.io/gh/thomasp85/farver/branch/main/graph/badge.svg)](https://app.codecov.io/gh/thomasp85/farver?branch=main)



```{r, echo = FALSE}

knitr::opts_chunk$set(

  collapse = TRUE,

  comment = "#>",

  fig.path = "man/figures/README-"

)

```



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, eval=FALSE}

# 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



spectrum <- decode_colour(codes)

spectrum



encode_colour(spectrum)

```



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



decode_colour(codes, to = 'lab')



encode_colour(spectrum_lab, from = 'lab')

```



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')



# Set a channel to a specific value

set_channel(codes, 'alpha', c(0.3, 0.7))



# Limit a channel to a given value

cap_channel(codes, 'r', 200)

```



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]

```



## 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, message=FALSE}

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, message=FALSE}

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.