License
@@ -130,31 +53,27 @@License
MIT License
@@ -134,31 +57,27 @@MIT License
Authors
+ +Citation
+ Source:DESCRIPTION
+ -
-
-
-
Matthew Leonawicz. Author, maintainer. -
-
-
Leonawicz M (2023). +imgpalr: Create Color Palettes from Images. +R package version 0.3.2, https://github.com/leonawicz/imgpalr. +
+@Manual{,
+ title = {imgpalr: Create Color Palettes from Images},
+ author = {Matthew Leonawicz},
+ year = {2023},
+ note = {R package version 0.3.2},
+ url = {https://github.com/leonawicz/imgpalr},
+}
Authors
-- - - + + @@ -83,14 +83,10 @@
- Choose the type of color palette to derive from an image: qualitative, sequential or divergent. @@ -98,154 +94,165 @@
- Near-black or near-white colors can be trimmed in RGB space independent of trimming brightness or saturation distributions in HSV space.
- Creating sequential palettes also offers control over the order of HSV color dimensions to sort by.
-imgpalr 
+
+
-Author: Matthew Leonawicz 
License: MIT
-
-
-
+
The imgpalr package makes it easy to create color palettes from image files.
-
-
-Installation
+
+Installation
+
Install the CRAN release of imgpalr with
-install.packages("imgpalr")
+install.packages("imgpalr")
Install the development version from GitHub with
-# install.packages("remotes")
-remotes::install_github("leonawicz/imgpalr")
+# install.packages("remotes")
+remotes::install_github("leonawicz/imgpalr")
-
-
-Examples
+
+Examples
+
The main function is image_pal. It accepts PNG, JPG, BMP or GIF (first frame) images either from disk or URL. It returns a vector of colors defining a palette based on the image and your other function arguments. You can also set plot = TRUE to plot a preview of the palette, which includes the source image thumbnail for visual reference.
The examples below offer some typical considerations to make when deriving a color palette from an arbitrary image.
-
-
-Three palette types
+
+Three palette types
+
In this first set of examples, divergent, qualitative and sequential palettes are generated from the same image and while varying some additional 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 palette
-image_pal(x[1], type = "div",
- saturation = c(0.75, 1), brightness = c(0.75, 1), plot = TRUE)
+library(imgpalr)
+
+set.seed(1)
+x <- paste0(system.file(package = "imgpalr"), "/",
+ c("blue-yellow", "purples", "colors"), ".jpg")
+
+# Three palette types, one image
+# A divergent palette
+image_pal(x[1], type = "div",
+ saturation = c(0.75, 1), brightness = c(0.75, 1), plot = TRUE)
+
+# A qualitative palette
+image_pal(x[1], type = "qual", bw = c(0.25, 0.9), plot = TRUE)
-
- # A sequential palette
-image_pal(x[1], type = "seq", k = 2, saturation = c(0.75, 1),
- brightness = c(0.75, 1), seq_by = "hsv", plot = TRUE)
+
+ # A sequential palette
+image_pal(x[1], type = "seq", k = 2, saturation = c(0.75, 1),
+ brightness = c(0.75, 1), seq_by = "hsv", plot = TRUE)
-
-
-A dominant hue
+
+A dominant hue
+
In this test image, hue varies over a narrow range. A sequential palette is sensible here, but not necessarily best sorted by hue. Doing so does still show a perceivable order to the colors, but it is much more difficult to discern. Sorting the palette first by saturation or brightness 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 = "hsv", plot = TRUE)
-image_pal(x[2], type = "seq", seq_by = "svh", plot = TRUE)
+image_pal(x[2], type = "seq", seq_by = "svh", plot = TRUE)
Author: Matthew Leonawicz
License: MIT
The imgpalr package makes it easy to create color palettes from image files.
-Installation
+Installation +
Install the CRAN release of imgpalr with
-install.packages("imgpalr")install.packages("imgpalr")Install the development version from GitHub with
-# install.packages("remotes")
-remotes::install_github("leonawicz/imgpalr")# install.packages("remotes")
+remotes::install_github("leonawicz/imgpalr")-Examples
+Examples +
The main function is image_pal. It accepts PNG, JPG, BMP or GIF (first frame) images either from disk or URL. It returns a vector of colors defining a palette based on the image and your other function arguments. You can also set plot = TRUE to plot a preview of the palette, which includes the source image thumbnail for visual reference.
The examples below offer some typical considerations to make when deriving a color palette from an arbitrary image.
--Three palette types
+Three palette types +
In this first set of examples, divergent, qualitative and sequential palettes are generated from the same image and while varying some additional 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 palette
-image_pal(x[1], type = "div",
- saturation = c(0.75, 1), brightness = c(0.75, 1), plot = TRUE)library(imgpalr)
+
+set.seed(1)
+x <- paste0(system.file(package = "imgpalr"), "/",
+ c("blue-yellow", "purples", "colors"), ".jpg")
+
+# Three palette types, one image
+# A divergent palette
+image_pal(x[1], type = "div",
+ saturation = c(0.75, 1), brightness = c(0.75, 1), plot = TRUE)
+# A qualitative palette
+image_pal(x[1], type = "qual", bw = c(0.25, 0.9), plot = TRUE)
-
- # A sequential palette
-image_pal(x[1], type = "seq", k = 2, saturation = c(0.75, 1),
- brightness = c(0.75, 1), seq_by = "hsv", plot = TRUE)
+ # A sequential palette
+image_pal(x[1], type = "seq", k = 2, saturation = c(0.75, 1),
+ brightness = c(0.75, 1), seq_by = "hsv", plot = TRUE)
-A dominant hue
+A dominant hue +
In this test image, hue varies over a narrow range. A sequential palette is sensible here, but not necessarily best sorted by hue. Doing so does still show a perceivable order to the colors, but it is much more difficult to discern. Sorting the palette first by saturation or brightness 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 = "hsv", plot = TRUE)
-image_pal(x[2], type = "seq", seq_by = "svh", plot = TRUE)image_pal(x[2], type = "seq", seq_by = "svh", plot = TRUE)
-image_pal(x[2], type = "seq", seq_by = "vsh", plot = TRUE)image_pal(x[2], type = "seq", seq_by = "vsh", plot = TRUE)
-Several hues
+Several hues +
Using an image with several prominent hues, a divergent palette is not sensible here. A sequential is likely best sorted by hue.
Note in the second image below, you can also set quantize = TRUE to show a color-quantized reference thumbnail image based on the derived palette. This makes use of the image_quantmap function. Rather than only quantizing the image, it does so while also mapping the colors of any image to an arbitrary color palette based on nearest distances in RGB 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)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 each time you call image_pal. If the palette you obtain does not feel right, even with fixed arguments you can run it again to obtain a different palette. Depending on the settings and the nature of the source image, it may change quite a bit. If you need a reproducible palette, set the seed argument. In the example above, the seed was set globally to avoid having to set it in each call to image_pal.
-Quantize and remap image colors
+Quantize and remap image colors +
You can quantize the colors in an image using image_quantmap directly. Choose any vector of colors. Each pixel has its color mapped to whichever of these colors it is closest to in RGB space. The RGB array 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)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 ...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 short distance away in RGB space, but if you want to also swap them out for very different colors, this should be a two step process. If you provide an equal-length vector of colors to the pal2 argument, these colors will replace those in pal after the initial quantization.
-pal2 <- c("darkred", "darkgreen", "tomato", "orange")
-a <- image_quantmap(x, pal, pal2, k = 7, plot = TRUE, show_pal = FALSE)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 large k and/or larger images.
Developers
+ + diff --git a/docs/news/index.html b/docs/news/index.html index b0a3ccb..bff5e2f 100644 --- a/docs/news/index.html +++ b/docs/news/index.html @@ -1,76 +1,12 @@ - - - - - - - --imgpalr 0.3.0 2019-11-28 -
--
-
- Updates to
image_quantmap.
+
+
+ - Updates to
image_quantmap. - Use
farverpackage internally in place ofgrDevicesfunctions. - Update documentation. -
- Corrected syntax error in example.
- Minor updates to documentation.
- Fixes unit test file writing issue. -
- Examples and unit tests updated for CRAN release.
- Added
kargument toimage_palandimage_quantmapfor control over the number of k-means clusters during initial image processing. - Added
div_centerso that an alternative color can be specified for the midpoint of divergent palettes.
- - Added
image_quantmapfunction and aquantizeargument toimage_palfor the preview thumbnail image.
+
imgpalr 0.3.02019-11-28
+imgpalr 0.2.22019-10-26
+imgpalr 0.2.12019-07-26
+-imgpalr 0.2.0 Unreleased -
--
-
Load PNG, JPG, BMP or GIF
Load PNG, JPG, BMP or GIF from disk or URL.
image_load(file)- -
Arguments
-| file | -character, file name. A local file or URL. Extension must be one of png, jpg, jpeg, bmp or gif. |
-
|---|
image_load(file)Value
+Arguments
+Value
+ +an RBG array
+Details
The function will prompt you of the need to install a format-specific package if not installed and needed for
the given file extension; png, bmp, magick (for GIF). jpeg is already imported for purpose of running examples.
Examples
-+x <- paste0(system.file(package = "imgpalr"), "/blue-yellow.", - c("jpg", "png", "bmp", "gif")) -str(image_load(x[1])) -#> num [1:317, 1:400, 1:3] 0.208 0.149 0.125 0.153 0.157 ...#>#> num [1:158, 1:200, 1:3] 0.153 0.122 0.137 0.133 0.208 ...#>#> Warning: there is no package called 'bmp'#>#> -#> -#>#> num [1:158, 1:200, 1:3] 0.129 0.102 0.114 0.129 0.196 ...
Examples
+x <- paste0(system.file(package = "imgpalr"), "/blue-yellow.",
+ c("jpg", "png", "bmp", "gif"))
+str(image_load(x[1]))
+#> num [1:317, 1:400, 1:3] 0.216 0.149 0.125 0.161 0.157 ...
+if(require(png)) str(image_load(x[2]))
+#> Loading required package: png
+#> num [1:158, 1:200, 1:3] 0.153 0.122 0.137 0.133 0.208 ...
+if(require(bmp)) str(image_load(x[3]))
+#> Loading required package: bmp
+#> num [1:158, 1:200, 1:3] 0.153 0.122 0.137 0.133 0.208 ...
+#> - attr(*, "header")=List of 13
+#> ..$ filesize : num 94854
+#> ..$ offset : num 54
+#> ..$ header_sz : num 40
+#> ..$ width : num 200
+#> ..$ height : num 158
+#> ..$ nplanes : int 1
+#> ..$ depth : int 24
+#> ..$ compress_type: num 0
+#> ..$ bmp_bytesz : num 94800
+#> ..$ hres : num 2835
+#> ..$ vres : num 2835
+#> ..$ ncolors : num 0
+#> ..$ nimpcolors : num 0
+if(require(magick)) str(image_load(x[4]))
+#> Loading required package: magick
+#> Linking to ImageMagick 6.9.12.93
+#> Enabled features: cairo, freetype, fftw, ghostscript, heic, lcms, pango, raw, rsvg, webp
+#> Disabled features: fontconfig, x11
+#> num [1:158, 1:200, 1:3] 0.129 0.102 0.114 0.129 0.196 ...
+Create a color palette from an image
Derive qualitative, sequential and divergent color palettes from an image on disk or at a URL.
image_pal( - file, - n = 9, - type = c("qual", "seq", "div"), - k = 100, - bw = c(0, 1), - brightness = c(0, 1), - saturation = c(0, 1), - seq_by = "hsv", - div_center = "#FFFFFF", - seed = NULL, - plot = FALSE, - labels = TRUE, - label_size = 1, - label_color = "#000000", - keep_asp = TRUE, - quantize = FALSE -)- -
Arguments
-| file | -character, file path or URL to an image. |
-
|---|---|
| n | -integer, number of colors. |
-
| type | -character, type of palette: qualitative, sequential or divergent ( |
-
| k | -integer, the number of k-means cluster centers to consider in the image. See details. |
-
| bw | -a numeric vector of length two giving the lower and upper quantiles to trim trim near-black and near-white colors in RGB space. |
-
| brightness | -as above, trim possible colors based on brightness in HSV space. |
-
| saturation | -as above, trim possible colors based on saturation in HSV space. |
-
| seq_by | -character, sort sequential palette by HSV dimensions in a specific order, e.g., |
-
| div_center | -character, color used for divergent palette center, defaults to white. |
-
| seed | -numeric, set the seed for reproducible results. |
-
| plot | -logical, plot the palette. |
-
| labels | -logical, show hex color values in plot. |
-
| label_size | -numeric, label size in plot. |
-
| label_color | -text label color. |
-
| keep_asp | -logical, adjust rectangles in plot to use the image aspect ratio. |
-
| quantize | -logical, quantize the reference thumbnail image in the plot using the derived color palette. See |
-
Value
- -character vector of hex colors, optionally draws a plot
-Details
+image_pal(
+ file,
+ n = 9,
+ type = c("qual", "seq", "div"),
+ k = 100,
+ bw = c(0, 1),
+ brightness = c(0, 1),
+ saturation = c(0, 1),
+ seq_by = "hsv",
+ div_center = "#FFFFFF",
+ seed = NULL,
+ plot = FALSE,
+ labels = TRUE,
+ label_size = 1,
+ label_color = "#000000",
+ keep_asp = TRUE,
+ quantize = FALSE
+)Arguments
+- file +
character, file path or URL to an image.
+
+
+- n +
integer, number of colors.
+
+
+- type +
character, type of palette: qualitative, sequential or divergent (
"qual","seq", or"div").
+
+
+- k +
integer, the number of k-means cluster centers to consider in the image. See details.
+
+- bw +
a numeric vector of length two giving the lower and upper quantiles to trim trim near-black and near-white colors in RGB space.
+
+
+- brightness +
as above, trim possible colors based on brightness in HSV space.
+
+
+- saturation +
as above, trim possible colors based on saturation in HSV space.
+
+
+- seq_by +
character, sort sequential palette by HSV dimensions in a specific order, e.g.,
"hsv","svh". See details.
+
+
+- div_center +
character, color used for divergent palette center, defaults to white.
+
+
+- seed +
numeric, set the seed for reproducible results.
+
+
+- plot +
logical, plot the palette.
+
+
+- labels +
logical, show hex color values in plot.
+
+
+- label_size +
numeric, label size in plot.
+
+
+- label_color +
text label color.
+
+
+- keep_asp +
logical, adjust rectangles in plot to use the image aspect ratio.
+
+
+- quantize +
logical, quantize the reference thumbnail image in the plot using the derived color palette. See
image_quantmap.
+
+
Value
+ + +character vector of hex colors, optionally draws a plot
+Details
Ordering colors is a challenging problem. There are many ways to do it; none are perfect. Color is a multi-dimensional property; any reduction to a a one dimensional color spectrum necessarily removes information.
Creating a sequential palette from an arbitrary image that contains several hues, at different saturation and brightness levels, and making a palette that looks sequential is particularly problematic. @@ -233,72 +157,78 @@
Details
This is different from n, the number of colors are desired in the derived palette. It is limited by the number of unique colors in the image.
Larger k may allow for better palette construction under some conditions, but takes longer to run.
k applies to sequential and qualitative palettes, but not divergent palettes.
- Trimming color distribution
-
+
Trimming color distribution
Some pre-processing can be done to limit undesirable colors from ending up in a palette.
bw specifically drops near-black and near-white colors as soon as the image is loaded by looking at the average values in RGB space.
brightness and saturation trimming are applied subsequently to trim lower and upper quantiles of the HSV value and saturation, respectively.
If you have already trimmed black and white, keep in mind these two arguments will trim further from what remains of the color distribution.
Choosing appropriate palette type
- +Choosing appropriate palette type
Keep in mind that many images simple do not make sense to try to derive sensible color palettes from.
For images that do lend themselves to a useful color palette derivation, some may only make sense to consider for a divergent palette, or an increasing/decreasing sequential palette,
or only a qualitative palette if there are too many colors that are difficult to order.
For divergent palettes in particular, it is recommended to trim white, e.g. bw = c(0, 0.9), depending on the white space of a given image, since the divergent palettes are centered on white.
Sorting sequential palettes
- +Sorting sequential palettes
seq_by = "hsv" orders the final palette by hue, then saturation, then value (brightness). This default is not meant to be ideal for all images.
It work better in cases where sequential palettes may contain several distinct hues, but not much variation in saturation or brightness.
However, for example, palettes derived from an image with relatively little variation in hue may appear more sorted to the human eye if ordered by hue last using "svh" or "vsh",
depending on whether you want the palette to appear to transition more from lower saturation or lower brightness to the predominant hue.
See also
- - - -Examples
-+set.seed(1) -x <- system.file("blue-yellow.jpg", package = "imgpalr") - -# Focus on bright, saturated colors for divergent palette: -image_pal(x, n = 3, type = "div", - saturation = c(0.75, 1), brightness = c(0.75, 1), plot = TRUE) -#> [1] "#4A66A2" "#FFFFFF" "#B4A337"-# \donttest{ -image_pal(x, n = 5, type = "seq", k = 2, saturation = c(0.5, 1), - brightness = c(0.25, 1), seq_by = "hsv") -#> [1] "#A8A44D" "#8E905A" "#747D68" "#596A76" "#405784"# } -
See also
+ +Examples
+set.seed(1)
+x <- system.file("blue-yellow.jpg", package = "imgpalr")
+
+# Focus on bright, saturated colors for divergent palette:
+image_pal(x, n = 3, type = "div",
+ saturation = c(0.75, 1), brightness = c(0.75, 1), plot = TRUE)
+
+#> [1] "#B5A335" "#FFFFFF" "#4966A3"
+
+# \donttest{
+image_pal(x, n = 5, type = "seq", k = 2, saturation = c(0.5, 1),
+ brightness = c(0.25, 1), seq_by = "hsv")
+#> [1] "#A6A34B" "#8C9059" "#737D67" "#596975" "#405784"
+# }
+Quantize an image using an existing color palette
- Source:R/quantize.R
+ Source: R/quantize.R
image_quantmap.RdQuantize an image using an existing color palette
Quantize image colors by mapping all pixels to the nearest color in RGB space, respectively, given an arbitrary palette.
image_quantmap( - file, - pal, - pal2 = NULL, - k = 100, - plot = FALSE, - show_pal = TRUE, - labels = TRUE, - label_size = 1, - label_color = "#000000", - keep_asp = TRUE -)- -
Arguments
-| file | -if character, file path or URL to an image. You can also provide an RGB array from an already loaded image file. |
-
|---|---|
| pal | -character, vector of hex colors, the color palette used to quantize the image colors. |
-
| pal2 | -character, optional vector of hex colors, same length as |
-
| k | -integer, the number of k-means cluster centers to consider in the image. See details. |
-
| plot | -logical, plot the palette with quantized image reference thumbnail. If |
-
| show_pal | -logical, show the palette like with |
-
| labels | -logical, show hex color values in plot. |
-
| label_size | -numeric, label size in plot. |
-
| label_color | -text label color. |
-
| keep_asp | -logical, adjust rectangles in plot to use the image aspect ratio. |
-
Value
- -an RGB array with values ranging from 0 to 1
-Details
+image_quantmap(
+ file,
+ pal,
+ pal2 = NULL,
+ k = 100,
+ plot = FALSE,
+ show_pal = TRUE,
+ labels = TRUE,
+ label_size = 1,
+ label_color = "#000000",
+ keep_asp = TRUE
+)Arguments
+- file +
if character, file path or URL to an image. You can also provide an RGB array from an already loaded image file.
+
+
+- pal +
character, vector of hex colors, the color palette used to quantize the image colors.
+
+
+- pal2 +
character, optional vector of hex colors, same length as
pal. +After quantizing image topal, you can subsequently remappaltopal2.
+
+
+- k +
integer, the number of k-means cluster centers to consider in the image. See details.
+
+
+- plot +
logical, plot the palette with quantized image reference thumbnail. If
FALSE, only return the RGB array.
+
+
+- show_pal +
logical, show the palette like with
image_pal. IfFALSE, plot only the image; all subsequent arguments ignored.
+
+
+- labels +
logical, show hex color values in plot.
+
+- label_size +
numeric, label size in plot.
+
+
+- label_color +
text label color.
+
+
+- keep_asp +
logical, adjust rectangles in plot to use the image aspect ratio.
+
+
Value
+ + +an RGB array with values ranging from 0 to 1
+Details
The palette pal does not need to be related to the image colors.
Each pixel will be assigned to whichever color in pal that it is nearest to in RGB space.
You can use pal2 to remap to arbitrary colors after quantizing.
@@ -201,45 +125,48 @@
Details
The number of k-means centers k is for binning image colors prior to mapping the palette pal.
It is limited by the number of unique colors in the image. Larger k provides more binned distances between image colors and palette colors,
but takes longer to run.
- See also
-
-
-
- Examples
- x <- system.file("blue-yellow.jpg", package = "imgpalr")
-pal <- c("black", "navyblue", "dodgerblue", "yellow")
-pal2 <- c("darkred", "darkgreen", "tomato", "orange")
+
+
+ See also
+
+
-a <- image_quantmap(x, pal, k = 7, plot = TRUE)
-
See also
+ +
Examples
+x <- system.file("blue-yellow.jpg", package = "imgpalr")
+pal <- c("black", "navyblue", "dodgerblue", "yellow")
+pal2 <- c("darkred", "darkgreen", "tomato", "orange")
+
+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 ...
+
+a <- image_quantmap(x, pal, pal2, k = 7, plot = TRUE)
+
+