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