getImageHist: Generate a 3D histogram based on color distribution in an...

In colordistance: Distance Metrics for Image Color Similarity

Description

Computes a histogram in either RGB or HSV colorspace by sorting pixels into a specified number of bins.

Usage

getImageHist(
  image,
  bins = 3,
  bin.avg = TRUE,
  defaultClusters = NULL,
  lower = c(0, 0.55, 0),
  upper = c(0.24, 1, 0.24),
  as.vec = FALSE,
  alpha.channel = TRUE,
  norm.pix = FALSE,
  plotting = TRUE,
  hsv = FALSE,
  title = "path",
  bounds = c(0, 1),
  ...
)

Arguments

image	Path to a valid image (PNG or JPG) or a loadImage object.
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.
defaultClusters	Optional dataframe of default color clusters to be returned when a bin is empty. If NULL, the geometric centers of the bins are used.
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.
as.vec	Logical. Should the bin sizes just be returned as a vector? Much faster if only using chisqDistance for comparison metric.
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 a histogram of the bin colors and sizes be plotted?
hsv	Logical. Should HSV be used instead of RGB?
title	String for what to title the plots if plotting is on; defaults to the image name.
bounds	Upper and lower limits for the channels; R reads in images with intensities on a 0-1 scale, but 0-255 is common.
...	Optional arguments passed to the barplot function.

Details

If you choose 2 bins for each color channel, then each of R, G, and B will be divided into 2 bins each, for a total of 2^3 = 8 bins.

Once all pixels have been binned, the function will return either the size of each bin, either in number of pixels or fraction of total pixels, and the color of each bin, either as the geometric center of the bin or as the average color of all pixels assigned to it.

For example, if you input an image of a red square and used 8 bins, all red pixels (RGB triplet of [1, 0, 0]) would be assigned to the bin with R bounds (0.5, 1], G bounds [0, 0.5) and B bounds [0, 0.5). The average color of the bin would be [0.75, 0.25, 0.25], but the average color of the pixels assigned to that bin would be [1, 0, 0]. The latter option is obviously more informative, but takes longer (about 1.5-2x longer depending on the images).

Value

A vector or dataframe (depending on whether as.vec=T) of bin sizes and color values.

Examples

# generate HSV histogram for a single image
colordistance::getImageHist(system.file("extdata",
"Heliconius/Heliconius_B/Heliconius_07.jpeg", package="colordistance"),
upper=rep(1, 3), lower=rep(0.8, 3), bins=c(8, 3, 3), hsv=TRUE, plotting=TRUE)

# generate RGB histogram
colordistance::getImageHist(system.file("extdata",
"Heliconius/Heliconius_B/Heliconius_07.jpeg", package="colordistance"),
upper=rep(1, 3), lower=rep(0.8, 3), bins=2)

Example output

RGB and HSV are device-dependent, perceptually non-uniform color spaces. See 'Color spaces' vignette for more information.


Using 8*3*3 = 72 bins
            h          s         v          Pct
1  0.09416127 0.26574929 0.2561224 7.665480e-03
2  0.17286307 0.25116198 0.2440936 1.037807e-02
3  0.28908211 0.26211872 0.1892624 5.086100e-04
4  0.41666667 0.03809869 0.2058824 2.421953e-05
5  0.56250000 0.16666667 0.1666667 0.000000e+00
6  0.68750000 0.16666667 0.1666667 0.000000e+00
7  0.81250000 0.16666667 0.1666667 0.000000e+00
8  0.97394180 0.28169105 0.1719888 8.476834e-05
9  0.09767884 0.56432547 0.2098153 1.885248e-01
10 0.14886561 0.49149347 0.1869100 6.747560e-02
11 0.27000717 0.38305739 0.1438655 4.238417e-04
12 0.43750000 0.50000000 0.1666667 0.000000e+00
13 0.56250000 0.50000000 0.1666667 0.000000e+00
14 0.68750000 0.50000000 0.1666667 0.000000e+00
15 0.81250000 0.50000000 0.1666667 0.000000e+00
16 0.95533101 0.48906478 0.1500980 4.843905e-04
17 0.09524623 0.80351611 0.1651286 4.021773e-01
18 0.14288820 0.87682287 0.1795227 3.413742e-02
19 0.31250000 0.83333333 0.1666667 0.000000e+00
20 0.43750000 0.83333333 0.1666667 0.000000e+00
21 0.56250000 0.83333333 0.1666667 0.000000e+00
22 0.68750000 0.83333333 0.1666667 0.000000e+00
23 0.81250000 0.83333333 0.1666667 0.000000e+00
24 0.99206349 0.72413793 0.2274510 2.421953e-05
25 0.09086812 0.17411625 0.4828986 1.209765e-02
26 0.16738746 0.16427701 0.4810913 8.694810e-03
27 0.28703704 0.03535287 0.4771242 3.632929e-05
28 0.41666667 0.01680672 0.4666667 3.632929e-05
29 0.61111111 0.02611111 0.4607843 2.421953e-05
30 0.63333333 0.03267974 0.6000000 3.632929e-05
31 0.81250000 0.16666667 0.5000000 0.000000e+00
32 0.98011364 0.12963074 0.5450980 7.265858e-05
33 0.10206875 0.49917803 0.4019091 8.731139e-03
34 0.15228143 0.52649148 0.4996972 6.272857e-03
35 0.31250000 0.50000000 0.5000000 0.000000e+00
36 0.43750000 0.50000000 0.5000000 0.000000e+00
37 0.56250000 0.50000000 0.5000000 0.000000e+00
38 0.68750000 0.50000000 0.5000000 0.000000e+00
39 0.81250000 0.50000000 0.5000000 0.000000e+00
40 0.93750000 0.50000000 0.5000000 0.000000e+00
41 0.06168235 0.87944238 0.5209685 3.196977e-02
42 0.15302311 0.78063842 0.4169399 4.432173e-03
43 0.31250000 0.83333333 0.5000000 0.000000e+00
44 0.43750000 0.83333333 0.5000000 0.000000e+00
45 0.56250000 0.83333333 0.5000000 0.000000e+00
46 0.68750000 0.83333333 0.5000000 0.000000e+00
47 0.81250000 0.83333333 0.5000000 0.000000e+00
48 0.93750000 0.83333333 0.5000000 0.000000e+00
49 0.06846646 0.07030174 0.7607403 7.556492e-03
50 0.16785114 0.10380471 0.7791879 4.613820e-03
51 0.30555556 0.02583333 0.7450980 2.421953e-05
52 0.41666667 0.01057583 0.7450980 2.421953e-05
53 0.61111111 0.01630435 0.7215686 3.632929e-05
54 0.65555556 0.01556609 0.7660131 3.632929e-05
55 0.81250000 0.16666667 0.8333333 0.000000e+00
56 0.96812865 0.06840959 0.7551821 8.476834e-05
57 0.08104302 0.59245430 0.8620448 6.781467e-04
58 0.17024333 0.49593071 0.9309966 6.430284e-02
59 0.31250000 0.50000000 0.8333333 0.000000e+00
60 0.43750000 0.50000000 0.8333333 0.000000e+00
61 0.56250000 0.50000000 0.8333333 0.000000e+00
62 0.68750000 0.50000000 0.8333333 0.000000e+00
63 0.81250000 0.50000000 0.8333333 0.000000e+00
64 0.93750000 0.50000000 0.8333333 0.000000e+00
65 0.06057450 0.89096617 0.8025115 1.381118e-01
66 0.16074356 0.68529963 0.8093137 2.906343e-04
67 0.31250000 0.83333333 0.8333333 0.000000e+00
68 0.43750000 0.83333333 0.8333333 0.000000e+00
69 0.56250000 0.83333333 0.8333333 0.000000e+00
70 0.68750000 0.83333333 0.8333333 0.000000e+00
71 0.81250000 0.83333333 0.8333333 0.000000e+00
72 0.93750000 0.83333333 0.8333333 0.000000e+00
RGB and HSV are device-dependent, perceptually non-uniform color spaces. See 'Color spaces' vignette for more information.


Using 2^3 = 8 total bins
          r         g          b          Pct
1 0.1935332 0.1429224 0.06450287 0.7524158977
2 0.7741384 0.3381754 0.08921268 0.1579113081
3 0.4947712 0.5078431 0.35424837 0.0001453172
4 0.8661239 0.8648741 0.42944387 0.0554748238
5 0.2500000 0.2500000 0.75000000 0.0000000000
6 0.7500000 0.2500000 0.75000000 0.0000000000
7 0.2500000 0.7500000 0.75000000 0.0000000000
8 0.8404722 0.8368798 0.59913257 0.0340526532

colordistance documentation built on March 21, 2021, 1:06 a.m.