Repository files navigation

Theimgpalr package makes it easy to create color palettes from imagefiles.

• Choose the type of color palette to derive from an image: qualitative,sequential or divergent.
• Quantiles of an image color distribution can be trimmed.
• Near-black or near-white colors can be trimmed in RGB spaceindependent of trimming brightness or saturation distributions in HSVspace.
• Creating sequential palettes also offers control over the order of HSVcolor dimensions to sort by.

Install the CRAN release ofimgpalr with

install.packages("imgpalr")

Install the development version from GitHub with

# install.packages("remotes")remotes::install_github("leonawicz/imgpalr")

The main function isimage_pal(). It accepts PNG, JPG, BMP or GIF(first frame) images either from disk or URL. It returns a vector ofcolors defining a palette based on the image and your other functionarguments. You can also setplot = TRUE to plot a preview of thepalette, which includes the source image thumbnail for visual reference.

The examples below offer some typical considerations to make whenderiving a color palette from an arbitrary image.

In this first set of examples, divergent, qualitative and sequentialpalettes are generated from the same image and while varying someadditional settings.

library(imgpalr)set.seed(1)x<- paste0(system.file(package="imgpalr"),"/",  c("blue-yellow","purples","colors"),".jpg")# Three palette types, one image# A divergent paletteimage_pal(x[1],type="div",saturation= c(0.75,1),brightness= c(0.75,1),plot=TRUE)

# A qualitative paletteimage_pal(x[1],type="qual",bw= c(0.25,0.9),plot=TRUE)

# A sequential paletteimage_pal(x[1],type="seq",k=2,saturation= c(0.75,1),brightness= c(0.75,1),seq_by="hsv",plot=TRUE)

In this test image, hue varies over a narrow range. A sequential paletteis sensible here, but not necessarily best sorted by hue. Doing so doesstill show a perceivable order to the colors, but it is much moredifficult to discern. Sorting the palette first by saturation orbrightness makes a much better sequential palette in this case.

image_pal(x[2],type="seq",seq_by="hsv",plot=TRUE)

image_pal(x[2],type="seq",seq_by="svh",plot=TRUE)

image_pal(x[2],type="seq",seq_by="vsh",plot=TRUE)

Using an image with several prominent hues, a divergent palette is notsensible here. A sequential is likely best sorted by hue.

Note in the second image below, you can also setquantize = TRUE toshow a color-quantized reference thumbnail image based on the derivedpalette. This makes use of theimage_quantmap() function. Rather thanonly quantizing the image, it does so while also mapping the colors ofany image to an arbitrary color palette based on nearest distances inRGB space.

image_pal(x[3],type="qual",brightness= c(0.4,1),plot=TRUE)

image_pal(x[3],type="seq",bw= c(0.2,1),saturation= c(0.2,1),plot=TRUE,quantize=TRUE)

Palette generation uses k-means clustering; results are different eachtime you callimage_pal(). If the palette you obtain does not feelright, even with fixed arguments you can run it again to obtain adifferent palette. Depending on the settings and the nature of thesource image, it may change quite a bit. If you need a reproduciblepalette, set theseed argument. In the example above, the seed was setglobally to avoid having to set it in each call toimage_pal().

You can quantize the colors in an image usingimage_quantmap()directly. Choose any vector of colors. Each pixel has its color mappedto whichever of these colors it is closest to in RGB space. The RGBarray is returned. You can plot the image with the palette.

x<- system.file("blue-yellow.jpg",package="imgpalr")pal<- c("black","navyblue","dodgerblue","yellow")a<- image_quantmap(x,pal,k=7,plot=TRUE)

str(a)#>  num [1:317, 1:400, 1:3] 0 0 0 0 0 0 0 0 0 0 ...

This works well if you want to quantize the colors to colors a shortdistance away in RGB space, but if you want to also swap them out forvery different colors, this should be a two step process. If you providean equal-length vector of colors to thepal2 argument, these colorswill replace those inpal after the initial quantization.

pal2<- c("darkred","darkgreen","tomato","orange")a<- image_quantmap(x,pal,pal2,k=7,plot=TRUE,show_pal=FALSE)

Note: This function can be very slow for largek and/or larger images.

There is also theRImagePalettepackage on CRAN, which uses the median cut algorithm for finding theydominant colors in an image.

imgpalr was originally inspired by thepaletter package onGitHub. Both packages use k-means clustering to find key image colors,but take some different approaches in methods for assembling colorpalettes.

The palette preview (without the thumbnail addition) is based off ofscales::show_col(), which is a convenient function for plottingpalettes. You can also usepals::pal.bands() to do the same using adifferent visual layout.

If you want to directly manipulate the color properties of an image forits own sake rather than derive color palettes for other purposes, youcan do so using themagickpackage, which provides bindings to the ImageMagick library.

Matthew Leonawicz (2024). imgpalr: Create Color Palettes from Images. Rpackage version 0.4.0.https://CRAN.R-project.org/package=imgpalr

Contributions are welcome. Contribute through GitHub via pull request.Please create an issue first if it is regarding any substantive featureadd or change.

Please note that theimgpalr project is released with aContributorCode ofConduct.By contributing to this project, you agree to abide by its terms.