{"id":16411813,"url":"https://github.com/ijlyttle/colorio","last_synced_at":"2026-05-13T01:34:43.063Z","repository":{"id":48767961,"uuid":"305543997","full_name":"ijlyttle/colorio","owner":"ijlyttle","description":"Interface to 'colorio'","archived":false,"fork":false,"pushed_at":"2021-07-12T22:51:23.000Z","size":94,"stargazers_count":3,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-03-31T16:48:10.673Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://ijlyttle.github.io/colorio/","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ijlyttle.png","metadata":{"files":{"readme":"README.Rmd","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-10-20T00:12:47.000Z","updated_at":"2023-08-31T19:53:37.000Z","dependencies_parsed_at":"2022-08-26T20:45:48.573Z","dependency_job_id":null,"html_url":"https://github.com/ijlyttle/colorio","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ijlyttle/colorio","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ijlyttle%2Fcolorio","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ijlyttle%2Fcolorio/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ijlyttle%2Fcolorio/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ijlyttle%2Fcolorio/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ijlyttle","download_url":"https://codeload.github.com/ijlyttle/colorio/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ijlyttle%2Fcolorio/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32964052,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-12T23:30:32.555Z","status":"ssl_error","status_checked_at":"2026-05-12T23:30:18.191Z","response_time":102,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-11T06:46:41.211Z","updated_at":"2026-05-13T01:34:43.042Z","avatar_url":"https://github.com/ijlyttle.png","language":"R","funding_links":[],"categories":[],"sub_categories":[],"readme":"---\noutput: github_document\n---\n\n\u003c!-- README.md is generated from README.Rmd. Please edit that file --\u003e\n\n```{r, include = FALSE}\nknitr::opts_chunk$set(\n  collapse = TRUE,\n  comment = \"#\u003e\",\n  fig.path = \"man/figures/README-\",\n  out.width = \"100%\"\n)\n```\n\n# colorio\n\n\u003c!-- badges: start --\u003e\n[![R build status](https://github.com/ijlyttle/colorio/workflows/R-CMD-check/badge.svg)](https://github.com/ijlyttle/colorio/actions)\n[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://www.tidyverse.org/lifecycle/#experimental)\n\u003c!-- badges: end --\u003e\n\nThe goal of colorio is to provide low-level access to the [**colorio** Python package](https://github.com/nschloe/colorio), developed by Nico Schlömer; this package makes conversions between different color spaces and provides color-distance calculations. \nIt includes some of the more-recent color spaces, such as [CAM02-UCS](https://en.wikipedia.org/wiki/CIECAM02), [CAM16-UCS](https://en.wikipedia.org/wiki/Color_appearance_model#CAM16), and [Jzazbz](https://doi.org/10.1364/OE.25.015131).\n\nThere's a lot to the colorio Python package; the goal of this README is to highlight those parts that concern conversion among color spaces, and distance calculations within a color space.\n\n## Installation\n\nYou can install the development version of colorio from [GitHub](https://github.com/) with:\n\n``` r\n# install.packages(\"devtools\")\ndevtools::install_github(\"ijlyttle/colorio\")\n```\n\nBecause this package uses the colorio Python package, you may need to follow a few steps. \nMy recommendations are to: \n\n- use (or create) a Conda installation. \n- use (or create) a Python environment called `r-reticulate`.\n- install the colorio Python package.\n\n```r\nreticulate::install_miniconda()\nreticulate::conda_create(\"r-reticulate\")\ncolorio::install_colorio()\n```\n\nIf you use Python virtual environments, or if you use an environment not named `r-reticulate`, you can use the `method` and `envname` options in `install_colorio()`.\n\nTo confirm everything is working, you can call `check_colorio()`:\n\n```{r}\ncolorio::check_colorio()\n```\n\n## Example\n\n```{r example}\nlibrary(\"colorio\")\n```\n\nIn colorio, the basic unit of analysis is the color, expressed as three numbers - one for each dimension of a **color space**. \nThis package has functions to create color-space objects; those objects will have methods we can call to convert to and from the \"central\" color-space: XYZ100, the [CIE 1931 XYZ color space](https://en.wikipedia.org/wiki/CIE_1931_color_space) with dimensions normalized to 100.\n\nTo convert values from one color space to another, we create each of the color-space objects - then use the `to_xyz100()` method from one of the color spaces, then the `from_xyz100()`  method from the other.\n\n### Conversion to/from LUV\n\nTo help demonstrate, we can use the [**farver**](https://farver.data-imaginist.com/) package, which has capabilities that overlap with this package.\n\n```{r}\nhex_codes \u003c- c(\"#112233\", \"#336699\")\n\nfarver_xyz100 \u003c- farver::decode_colour(hex_codes, to = \"xyz\")\nfarver_xyz100\n```\n\nThe `farver::decode_colour()` function returns a matrix with a color in each row, and each column named for a dimension.\nWe can convert these colors to the LUV color space:\n\n```{r}\nfarver_luv \u003c- farver::convert_colour(farver_xyz100, from = \"xyz\", to = \"luv\")\nfarver_luv\n```\n\nAgain, we get a matrix with a color in each row.\n\nWe can make analogous calculations using colorio; the first step is to create an instance of the LUV color space: \n\n```{r}\nLUV \u003c- colorio$CIELUV()\n```\n\nThis color space (as do all colorio color spaces) has a `from_xyz100()` method. Because Python is row-based and R is column-based, we have to use the transpose function, `t()`:\n\n```{r}\ncolorio_luv \u003c- LUV$from_xyz100(t(farver_xyz100))\nt(colorio_luv)\n```\n\nWe get essentially the same result; we can use the `to_xyz100()` method to go back:\n\n```{r}\ncolorio_xyz100 \u003c- LUV$to_xyz100(colorio_luv)\nt(colorio_xyz100)\n```\n\nWe can use the [**waldo**](https://waldo.r-lib.org/) package to compare the sets of LUV coordinates:\n\n```{r}\nwaldo::compare(farver_luv, t(colorio_luv))\n```\n\nWe see that colorio does not return dimension-names (we knew that), and that numerical differences are on the order of `1.e-6`.\nGiven that a visible difference is on the order of `1.0`, we are not concerned with differences in the sixth decimal place. \n\nInstead, we are encouraged that we can get the \"same\" answer using two different implementations.\n\n### Conversion to other colorspaces\n\nThe reason I find the colorio Python package so compelling is the wide range of color spaces it offers, including the CAM02-UCS color space, and its successor CAM16-UCS. You may remember the CAM02-UCS color space was used by Stéfan van der Walt and Nathaniel Smith to [design the viridis palette](https://www.youtube.com/watch?v=xAoljeRJ3lU).\n\nTo create a CAM16UCS color space (as well as for any of the CAM02 and CAM16 family), we have to supply some additional options. \nThese options are contained in a helper function `cam_options()`, which can be used in conjunction with `do.call()`:\n\n```{r}\nCAM16UCS \u003c- do.call(colorio$CAM16UCS, cam_options())\n```\n\nTo get the coordinates for these colors in the CAM16-UCS color space, use its `from_xyz100()` method:\n\n```{r}\ncolorio_cam16ucs \u003c- CAM16UCS$from_xyz100(colorio_xyz100)\nt(colorio_cam16ucs)\n```\n\n### Color-difference calculation\n\nIf the colorspace is Cartesian (not polar), you can get a useful distance-calculation using the `colorio$delta()` function.\n\nKeep in mind that this calculates the sum-of-squares of differences between two color spaces. \nIf you want the Euclidean distance, take the square root.\n\n```{r}\n# expect a couple of zeroes\ncolorio$delta(colorio_cam16ucs, colorio_cam16ucs)\n\n# expect a single non-zero number.\ncolorio$delta(\n  colorio_cam16ucs[, 1, drop = FALSE], \n  colorio_cam16ucs[, 2, drop = FALSE]\n)\n```\n\nThere is nothing stopping you from providing non-Cartesian coordinates, other than your vigilance.\n\n## Other resources\n\n- R package [farver](https://farver.data-imaginist.com/), by Thomas Lin Pedersen\n- R package [colorspace](http://hclwizard.org/r-colorspace/), by Achim Zeileis et al.\n- Python package [colorspacious](https://github.com/njsmith/colorspacious), by Nathaniel Smith\n\n## Code of Conduct\n\nPlease note that the colorio project is released with a [Contributor Code of Conduct](https://contributor-covenant.org/version/2/0/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fijlyttle%2Fcolorio","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fijlyttle%2Fcolorio","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fijlyttle%2Fcolorio/lists"}