Introduction to the colouR Package

Welcome to the colouR package, a useful tool for analyzing and utilizing the colors in images, as well as providing color palettes inspired by Radiohead and Taylor Swift album covers. Whether you are a designer looking for inspiration, a data analyst searching for unique ways to visualize data, or a music lover wanting to incorporate your favorite album colors into your projects, this package is for you. It is recommended to view this instructional guide via the GitHub page: https://alaninglis.github.io/colouR/articles/colouR.html

Package Overview

The colouR package provides a set of functions that allows you to:

Extract color values from an image (either JPG or PNG).
Obtain the top \(n\) colors in the image based on their frequency.
Group and average colors in the image.
Utilize color palettes inspired by Radiohead and Taylor Swift album covers.
These functionalities make the colouR package a versatile and easy-to-use tool for exploring and working with colors in images.

Key Functions

Some of the main functions included in the colouR package are:

getTopCol(): Extracts the top n colors from an image, with options to exclude black and white shades, and to group and average colors.
colPalette(): Creates a color palette based on a specified album cover from either Radiohead or Taylor Swift discography.
scaleColor(): Provides a ggplot2-compatible color scale based on the selected album cover palette, for both discrete and continuous data.
scaleFill(): Provides a ggplot2-compatible fill scale based on the selected album cover palette, for both discrete and continuous data.
groupCols: This function takes a vector of hex color values and groups them using k-means clustering in the RGB color space.
avgHex: This function takes a data frame with two columns: one for the hex color values and another for the group labels. It calculates the average color for each group and returns a data frame with the group labels and their corresponding average hex colors.
img2pal: Creates a Colour Palette from an input image.
plotPalette: This function takes a data frame with a column of colors and plots the colors as a color palette.

In addition, we provide several utility functions, all of which are demonstrated in this document.

Getting Started

To begin using the colouR package, simply install it from GitHub, load it into your R session, and start exploring the world of colors in images.

# install.packages("devtools")
#devtools::install_github("AlanInglis/colouR")

# Load the package
library(colouR)

# Load ggplot2 for making some plots
library(ggplot2)

Get the top n colours in an image

The first function we demonstrate is the getTopCol function. This function reads an image file, extracts the colors, and returns the top n colors based on their frequency in the image. Optionally, black and white shades can be excluded, and the colors can be grouped and averaged (more on colour averaging later!). This function can take in a .jpg, .jpeg, or .png or a url pointing to an image using any of these formats, via the path argument and returns the top n colours used in the image.

Function Arguments

The arguments for this function are:

path Character, the path to the image file (either jpg or png).
n Integer, the number of top colors to return. If NULL (default), return all colors.
exclude Logical, whether to exclude black and white shades. Default is TRUE.
sig Integer, the number of decimal places for the color percentage. Default is 4.
avgCols Logical, whether to average the colors by groups. Default is TRUE.
n_clusters Integer, the number of clusters to use for grouping colors. Default is 5.
customExclude Character vector. Optional vector of custom color codes in HEX format to be excluded.

Input Image

To begin, lets first take a look at a raw image:

knitr::include_graphics("https://raw.githubusercontent.com/AlanInglis/colouR/master/images/bender.png")