Overview
The lterpalettefinder package (LTER + Palette + Finder)
was initially developed simply to house hexadecimal code color palettes
manually extracted from photos taken at Long Term Ecological Research
sites. During its development its purpose expanded to include a set of
tools for automatically extracting those colors and visualizing the
derived palettes.
This vignette describes the main functions of
lterpalettefinder and demonstrates one possible use of its
workflow from the extraction of a palette from a picture to the
visualization of that palette.
library(lterpalettefinder)Start with a Picture
The lterpalettefinder workflow begins with a picture
from which you’d like to extract hexadecimal codes for the main colors
(“main” is defined later). This vignette will use this picture of a
prescribed fire in Iowa in 2018 (credit: Nick J Lyon) to allow for easy
visual comparison between the source photo and the palette returned by
the functions described below.
Extracting the Palette
The primary function of this package is platte_extract
which accepts the name and/or path to the image file in your working
directory. This function also includes an optional progress bar that is
switched off in the example below
fire_palette <- palette_extract(image = "lyon_fire.png", progress_bar = FALSE)The returned palette always contains the 25 most different colors (as identified by k-means clustering on the red, green, blue bands extracted from the image) stored as hexadecimal codes.
fire_palette
#> [1] "#7b8893" "#998a7b" "#a69686" "#56585c" "#c07b5f" "#6396d3" "#55473d"
#> [8] "#6a6a6c" "#615347" "#a16651" "#869eb2" "#8f7f70" "#e1946a" "#827568"
#> [15] "#d5c8b4" "#424449" "#6d5f52" "#c1b4a2" "#91afd0" "#9ec5f0" "#804f40"
#> [22] "#7b6a5a" "#7baeec" "#483931" "#b3a493"Viewing the Palette
In our experience, few people can look at a string of hex codes and
instinctively interpret those as colors, so this package includes
palette_demo and palette_ggdemo to demonstrate
the extracted palettes. While there are some aesthetic differences
between the plots produced by the two functions the fundamental
difference is that ...demo creates a base R plot while
...ggdemo produces a ggplot2 plot.
Additionally, palette_demo includes built in export options
if desired
palette_demo(palette = fire_palette, export = FALSE)
palette_ggdemo(palette = fire_palette)
Organizing the Palette
You can also organize the colors into an order that approximates how
human eyes instinctively group colors using palette_sort.
The sorting isn’t perfect, but it is far easier to view similar colors
than the random order returned by palette_extract
fire_sort <- palette_sort(palette = fire_palette)
palette_ggdemo(palette = fire_sort)
If desired, palette_extract does include a
sort argument (defaults to “FALSE”) that can be activated.
That said, it does take marginally longer to compute (~0.5 seconds) the
sorting so if running palette_extract iteratively it will
be faster to leave sort = FALSE until color sorting is
necessary.
Simplifying a Palette
It may be the case that you’d want fewer than 25 colors from a given
image but don’t want to have to go through and manually select the ones
you want. palette_subsample randomly selects the desired
number of colors from a vector of hexadecimal codes for just such an
occasion! It also allows you to se the random seed internally for
reproducibility
fire_sub <- palette_subsample(palette = fire_palette, wanted = 5, random_seed = 42)
palette_ggdemo(palette = fire_sub)
Using a Pre-Built Palette
The original impetus for lterpalettefinder was to allow
users to select pre-set palettes and while the package has evolved
beyond that, palette_find does serve this purpose.
palette_find allows users to specify the site, number of
colors, type of palette (e.g., sequential, diverging, etc.), and–if
known–the name of the palette to identify and return an official
palette.
official_palette <- palette_find(name = "hike")
#> Exactly one palette identified. Output cropped to only HEX codes for ease of plotting
palette_ggdemo(palette = official_palette)
Looking Ahead
If you have ideas for other functions that
lterpalettefinder could contain, post them as a GitHub
Issue and we’ll review them as soon as possible!