1NAME
2 Color::RGB::Util - Utilities related to RGB colors
3
4VERSION
5 This document describes version 0.606 of Color::RGB::Util (from Perl
6 distribution Color-RGB-Util), released on 2021-08-06.
7
8SYNOPSIS
9 use Color::RGB::Util qw(
10 assign_rgb_color
11 assign_rgb_dark_color
12 assign_rgb_light_color
13 int2rgb
14 mix_2_rgb_colors
15 mix_rgb_colors
16 rand_rgb_color
17 rand_rgb_colors
18 reverse_rgb_color
19 rgb2grayscale
20 rgb2int
21 rgb2sepia
22 rgb_diff
23 rgb_distance
24 rgb_is_dark
25 rgb_is_light
26 rgb_luminance
27 tint_rgb_color
28 );
29
30 say assign_rgb_color("foo"); # 0b5d33
31 say assign_rgb_dark_color("foo"); # 0b5d33
32 say assign_rgb_light_color("foo"); # 85ae99
33
34 say int2rgb(0xffffff); # ffffff
35
36 say mix_2_rgb_colors('#ff0000', '#ffffff'); # pink (red + white)
37 say mix_2_rgb_colors('ff0000', 'ffffff', 0.75); # pink with a whiter shade
38
39 say mix_rgb_colors('ff0000', 1, 'ffffff', 1); # pink (red + white 1 : 1)
40 say mix_rgb_colors('ff0000', 1, 'ffffff', 3); # pink with a whiter shade (red + white 1 : 3)
41 say mix_rgb_colors('ff0000', 1, 'ffffff', 1, '0000ff', 0.5); # bluish pink
42
43 say rand_rgb_color();
44 say rand_rgb_color('000000', '333333'); # limit range
45
46 say rand_rgb_colors(
47 {light_color => 1, avoid_colors=>[qw/ffffff ffcc00 ff00cc/],
48 3); # ("e9f3d7", "e0bbcc", "63f88c")
49
50 say reverse_rgb_color('0033CC'); # => ffcc33
51
52 say rgb2grayscale('0033CC'); # => 555555 # default 'average' algo
53 say rgb2grayscale('0033CC', 'weighted_average'); # => 353535
54
55 say rgb2int("ffffff"); # 16777215 (which is 0xffffff)
56
57 say rgb2sepia('0033CC'); # => 4d4535
58
59 say rgb_distance('000000', '000000') # => 0
60 say rgb_distance('01f000', '04f400') # => 5
61 say rgb_distance('ffff00', 'ffffff') # => 255
62
63 say rgb_diff('000000', '000000'); # => 0
64 say rgb_diff('01f000', '04f400'); # => 5
65 say rgb_diff('ffff00', 'ffffff'); # => 255
66 say rgb_diff('000000', '000000', 'approx1'); # => 0
67 say rgb_diff('01f000', '04f400', 'approx1'); # => 9.06
68 say rgb_diff('ffff00', 'ffffff', 'approx1'); # => 360.98
69
70 say rgb_is_dark('404040'); # => 1
71 say rgb_is_dark('a0a0a0'); # => 0
72 say rgb_is_light('404040'); # => 0
73 say rgb_is_light('a0a0a0'); # => 1
74
75 say rgb_luminance('d090aa'); # => ffcc33
76
77 say tint_rgb_color('#ff8800', '#0033cc'); # => b36e3c
78
79DESCRIPTION
80FUNCTIONS
81 None are exported by default, but they are exportable.
82
83 assign_rgb_color
84 Usage:
85
86 my $rgb = assign_rgb_color($str);
87
88 Map a string to an RGB color. This is done by producing SHA-1 digest
89 (160bit, 20 bytes) of the string, then taking the first, 10th, and last
90 byte to become the RGB color.
91
92 See also: "assign_rgb_dark_color" and "assign_rgb_light_color".
93
94 assign_rgb_dark_color
95 Like "assign_rgb_color" except that it will make sure the assigned color
96 is dark.
97
98 assign_rgb_light_color
99 Like "assign_rgb_color" except that it will make sure the assigned color
100 is light.
101
102 hsl2hsv
103 Usage:
104
105 my $hsl = hsl2hsv("0 1 0.5"); # => "0 1 1"
106
107 Convert HSL to HSV.
108
109 See also: "hsv2hsl".
110
111 hsl2rgb
112 Usage:
113
114 my $rgb = hsl2rgb("0 1 0.5"); # => ff0000
115
116 Convert HSL to RGB. HSL should be given in a whitespace-separated H,S,L
117 values e.g. "0 1 0.5". H (hue degree) has a range from 0-360 where 0 is
118 red, 120 is green, 240 is blue and 360 is back to red. S (saturation)
119 has a range from 0-1 where 0 is gray and 1 is fully saturated hue. L
120 (lumination) has a range from 0-1 where 0 is fully black, 0.5 fully
121 saturated, and 1 is fully white.
122
123 See also "rgb2hsl".
124
125 hsv2hsl
126 Usage:
127
128 my $hsl = hsv2hsl("0 1 1"); # => "0 1 0.5"
129
130 Convert HSV to HSL.
131
132 See also "hsl2hsv".
133
134 hsv2rgb
135 Usage:
136
137 my $rgb = hsv2rgb("0 1 1"); # => ff0000
138
139 Convert HSV to RGB. HSV should be given in a whitespace-separated H,S,V
140 values e.g. "0 1 1". H (hue degree) has a range from 0-360 where 0 is
141 red, 120 is green, 240 is blue and 360 is back to red. S (saturation)
142 has a range from 0-1 where 0 is gray and 1 is fully saturated hue. V
143 (value) has a range from 0-1 where 0 is black and 1 is white.
144
145 See also "rgb2hsv".
146
147 int2rgb
148 Usage:
149
150 my $rgb = int2rgb(0xffffff); # => ffffff
151
152 Convert integer to RGB string.
153
154 See also "rgb2int".
155
156 mix_2_rgb_colors
157 Usage:
158
159 my $mixed_rgb = mix_2_rgb_colors($rgb1, $rgb2, $pct);
160
161 Mix 2 RGB colors. $pct is a number between 0 and 1, by default 0.5
162 (halfway), the closer to 1 the closer the resulting color to $rgb2.
163
164 See also "mix_rgb_colors", "tint_rgb_color".
165
166 mix_rgb_colors
167 Usage:
168
169 my $mixed_rgb = mix_rgb_colors($color1, $weight1, $color2, $weight2, ...);
170
171 Mix several RGB colors.
172
173 See also "mix_2_rgb_colors".
174
175 rand_rgb_color
176 Usage:
177
178 my $rgb = rand_rgb_color([ $low_limit [ , $high_limit ] ]);
179
180 Generate a random RGB color. You can specify the limit. Otherwise, they
181 default to the full range (000000 to ffffff).
182
183 See also "rand_rgb_colors".
184
185 rand_rgb_colors
186 Usage:
187
188 my @rgbs = rand_rgb_colors([ \%opts ], $num=1);
189
190 Produce $num random RGB colors, with some options. It does not (yet)
191 create a palette of optimally distinct colors, but will make reasonable
192 attempt to make the colors different from one another.
193
194 Known options:
195
196 * light_color
197
198 Boolean, default true. By default, this function will create light
199 RGB colors, assuming the background color is dark, which is often
200 the case in terminal. If this option is set to false, will create
201 dark colors instead, If this option is set to undef, will create
202 both dark and light colors.
203
204 * avoid_colors
205
206 Arrayref or hashref. List of colors to be avoided. You can put, for
207 example, colors that you've already assigned/picked for your palette
208 and don't want to use again.
209
210 * max_attempts
211
212 Uint, default 1000. Number of attempts to try generating the next
213 random color if the generated color is rejected because it is
214 light/dark, or because it's in "avoid_colors".
215
216 When the number of attempts has been exceeded, the generated color
217 is used anyway.
218
219 * hash_prefix
220
221 Whether to add hash prefix to produced color codes ("#123456") or
222 not ("123456").
223
224 See also "rand_rgb_color".
225
226 reverse_rgb_color
227 Usage:
228
229 my $reversed = reverse_rgb_color($rgb);
230
231 Reverse $rgb.
232
233 rgb2grayscale
234 Usage:
235
236 my $rgb_gs = rgb2grayscale($rgb [ , $algo ]);
237
238 Convert $rgb to grayscale RGB value. There are several algorithms
239 ($algo) to choose from:
240
241 * average
242
243 The Average method takes the average value of R, G, and B as the
244 grayscale value.
245
246 Grayscale = (R + G + B ) / 3.
247
248 The average method is simple but does not take into account the
249 non-linearity of human vision (eyes are most sensitive to green,
250 less to red, least to blue).
251
252 * weighted_average
253
254 This method gives weights to each of red, green, blue elements to
255 take into account the sensitivity of human eyes.
256
257 Grayscale = 0.299R + 0.587G + 0.114B
258
259 See also rgb2sepia.
260
261 rgb2hsl
262 Usage:
263
264 my $hsl = rgb2hsl($rgb); # example: "0 1 0.5"
265
266 Convert RGB (0-255) to HSL. The result is a space-separated H, S, L
267 values.
268
269 See also "hsl2rgb".
270
271 rgb2hsv
272 Usage:
273
274 my $hsv = rgb2hsv($rgb); # example: "0 1 255"
275
276 Convert RGB (0-255) to HSV. The result is a space-separated H, S, V
277 values.
278
279 See also "hsv2rgb".
280
281 rgb2int
282 Usage:
283
284 my $int = rgb2int("ffffff"); # => 16777216, which is 0xffffff
285
286 Convert RGB string to integer.
287
288 See also "int2rgb".
289
290 rgb2sepia
291 Usage:
292
293 my $rgb_sepia = rgb2sepia($rgb);
294
295 Convert $rgb to sepia tone RGB value.
296
297 See also rgb2grayscale.
298
299 rgb_diff
300 Usage:
301
302 my $dist = rgb_diff($rgb1, $rgb2[ , $algo ])
303
304 Calculate difference between two RGB colors, using one of several
305 algorithms.
306
307 * euclidean
308
309 The default. It calculates the distance as:
310
311 ( (R1-R2)**2 + (G1-G2)**2 + (B1-B2)**2 )**0.5
312
313 which is the same as what "rgb_distance"() would produce.
314
315 * approx1
316
317 This algorithm, described in [1] as "a low cost approximation" and
318 "a combination both weighted Euclidean distance functions, where the
319 weight factors depend on how big the 'red' component of the colour
320 is" with "results that are very close to L*u*v" and "a more stable
321 algorithm", uses the following formula:
322
323 ( 2*(R1-R2)**2 + 4*(G1-G2)**2 + 3*(B1-B2)**2 + Rm*((R1-R2)**2 - (B1-B2)**2)/256 )**0.5
324
325 where, Rm or "R mean" is (R1+R2)/2.
326
327 * approx2
328
329 Like "approx1", but uses this formula:
330
331 ( 2*(R1-R2)**2 + 4*(G1-G2)**2 + 3*(B1-B2)**2 )**0.5 # if Rm < 128
332 ( 3*(R1-R2)**2 + 4*(G1-G2)**2 + 2*(B1-B2)**2 )**0.5 # otherwise
333
334 * hsv_euclidean
335
336 Convert the RGB values to HSV, then calculate the HSV distance.
337 Please see source code for details.
338
339 * hsv_hue1
340
341 Like "hsv_euclidean" but puts more emphasis on hue difference. This
342 algorithm is used, for example, by Color::ANSI::Util when mapping
343 RGB 24bit color to the "closest" the ANSI 256-color or 16-color.
344 This algorithm tends to choose the hued colors instead of favoring
345 to fallback on white/gray, which is more preferred.
346
347 TODO: redmean low-cost approximation, CMC l:c.
348
349 For more about color difference, try reading
350 <https://en.wikipedia.org/wiki/Color_difference>.
351
352 [1] https://www.compuphase.com/cmetric.htm
353
354 See also rgb_distance.
355
356 rgb_distance
357 Usage:
358
359 my $dist = rgb_distance($rgb1, $rgb2)
360
361 Calculate the euclidean RGB distance, using this formula:
362
363 ( (R1-R2)**2 + (G1-G2)**2 + (B1-B2)**2 )**0.5
364
365 For example, the distance between "000000" and "ffffff" is ~441.67,
366 while the distance between "ffff00" and "ffffff" is 255.
367
368 See also rgb_diff.
369
370 rgb_is_dark
371 Usage:
372
373 my $is_dark = rgb_is_dark($rgb)
374
375 Return true if $rgb is a "dark" color, which is determined by checking
376 if the RGB distance to "000000" is smaller than to "ffffff".
377
378 See also "rgb_is_light".
379
380 rgb_is_light
381 Usage:
382
383 my $is_light = rgb_is_light($rgb)
384
385 Return true if $rgb is a "light" color, which is determined by checking
386 if the RGB distance to "000000" is larger than to "ffffff".
387
388 See also "rgb_is_dark".
389
390 rgb_luminance
391 Usage:
392
393 my $luminance = rgb_luminance($rgb);
394
395 Calculate standard/objective luminance from RGB value using this
396 formula:
397
398 (0.2126*R) + (0.7152*G) + (0.0722*B)
399
400 where R, G, and B range from 0 to 1. Return a number from 0 to 1.
401
402 tint_rgb_color
403 Usage:
404
405 my $new_rgb = tint_rgb_color($rgb, $tint_rgb, $pct)
406
407 Tint $rgb with $tint_rgb. $pct is by default 0.5. It is similar to
408 mixing, but the less luminance the color is the less it is tinted with
409 the tint color. This has the effect of black color still being black
410 instead of becoming tinted.
411
412 See also mix_2_rgb_colors, mix_rgb_colors.
413
414HOMEPAGE
415 Please visit the project's homepage at
416 <https://metacpan.org/release/Color-RGB-Util>.
417
418SOURCE
419 Source repository is at
420 <https://github.com/perlancar/perl-SHARYANTO-Color-Util>.
421
422BUGS
423 Please report any bugs or feature requests on the bugtracker website
424 <https://rt.cpan.org/Public/Dist/Display.html?Name=Color-RGB-Util>
425
426 When submitting a bug or request, please include a test-file or a patch
427 to an existing test-file that illustrates the bug or desired feature.
428
429SEE ALSO
430 Color::ANSI::Util
431
432AUTHOR
433 perlancar <perlancar@cpan.org>
434
435CONTRIBUTORS
436 * ryosh2 (on pc-office) <ryosharyanto@gmail.com>
437
438 * Steven Haryanto <sharyanto@cpan.org>
439
440COPYRIGHT AND LICENSE
441 This software is copyright (c) 2021, 2020, 2019, 2018, 2015, 2014, 2013
442 by perlancar@cpan.org.
443
444 This is free software; you can redistribute it and/or modify it under
445 the same terms as the Perl 5 programming language system itself.
446
447