getHistList {colordistance}

Generate a list of cluster sets for multiple images

Description

Applies getImageHist to every image in a provided set of image paths and/or directories containing images.

Usage

getHistList(
  images,
  bins = 3,
  bin.avg = TRUE,
  lower = c(0, 0.55, 0),
  upper = c(0.24, 1, 0.24),
  alpha.channel = TRUE,
  norm.pix = FALSE,
  plotting = FALSE,
  pausing = TRUE,
  hsv = FALSE,
  title = "path",
  img.type = FALSE,
  bounds = c(0, 1)
)

Arguments

images

Character vector of directories, image paths, or both.

bins

Number of bins for each channel OR a vector of length 3 with bins for each channel. Bins=3 will result in 3^3 = 27 bins; bins=c(2, 2, 3) will result in 2*2*3=12 bins (2 red, 2 green, 3 blue), etc.

bin.avg

Logical. Should the returned color clusters be the average of the pixels in that bin (bin.avg=TRUE) or the center of the bin (FALSE)? If a bin is empty, the center of the bin is returned as the cluster color regardless.

lower

RGB or HSV triplet specifying the lower bounds for background pixels. Default upper and lower bounds are set to values that work well for a bright green background (RGB [0, 1, 0]).

upper

RGB or HSV triplet specifying the upper bounds for background pixels. Default upper and lower bounds are set to values that work well for a bright green background (RGB [0, 1, 0]). Determining these bounds may take some trial and error, but the following bounds may work for certain common background colors:

• Black: lower=c(0, 0, 0); upper=c(0.1, 0.1, 0.1)

• White: lower=c(0.8, 0.8, 0.8); upper=c(1, 1, 1)

• Green: lower=c(0, 0.55, 0); upper=c(0.24, 1, 0.24)

• Blue: lower=c(0, 0, 0.55); upper=c(0.24, 0.24, 1)

If no background filtering is needed, set bounds to some non-numeric value (NULL, FALSE, "off", etc); any non-numeric value is interpreted as NULL.

alpha.channel

Logical. If available, should alpha channel transparency be used to mask background? See removeBackground for more details.

norm.pix

Logical. Should RGB or HSV cluster values be normalized using normalizeRGB?

plotting

Logical. Should the histogram generated for each image be displayed?

pausing

Logical. If plotting=T, should the function pause between graphing and wait for user to hit [enter] before continuing? Useful for data/histogram inspection.

hsv

Logical. Should HSV be used instead of RGB?

title

String for what the title the plots if plotting is on; defaults to the image name.

img.type

Logical. Should the file extension for the images be retained when naming the output list elements? If FALSE, just the image name is used (so "Heliconius_01.png" becomes "Heliconius_01").

bounds

Upper and lower limits for the channels; R reads in images with intensities on a 0-1 scale, but 0-255 is common.

Value

A list of getImageHist dataframes, 1 per image, named by image name.

Note

For every image, the pixels are binned according to the specified bin breaks. By providing the bounds for the bins rather than letting an algorithm select centers (as in getKMeansList), clusters of nearly redundant colors are avoided.

So you don't end up with, say, 3 nearly-identical yellow clusters which are treated as unrelated just because there's a lot of yellow in your image; you just get a very large yellow cluster and empty non-yellow bins.

Examples

## Not run: 
# Takes >10 seconds if you run all examples
clusterList <- colordistance::getHistList(system.file("extdata",
"Heliconius/Heliconius_B", package="colordistance"), upper = rep(1, 3),
lower = rep(0.8, 3))

clusterList <- colordistance::getHistList(c(system.file("extdata",
"Heliconius/Heliconius_B", package="colordistance"), system.file("extdata",
"Heliconius/Heliconius_A", package="colordistance")), pausing = FALSE,
upper = rep(1, 3), lower = rep(0.8, 3))

clusterList <- colordistance::getHistList(system.file("extdata",
"Heliconius/Heliconius_B", package = "colordistance"), plotting = TRUE,
upper = rep(1, 3), lower = rep(0.8, 3))

## End(Not run)