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.601 of Color::RGB::Util (from Perl
10 distribution Color-RGB-Util), released on 2020-06-08.
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
57 say rgb2int("ffffff"); # 16777215 (which is 0xffffff)
59 say rgb2sepia('0033CC'); # => 4d4535
61 say rgb_distance('000000', '000000') # => 0
63 say rgb_distance('01f000', '04f400') # => 5
64 say rgb_distance('ffff00', 'ffffff') # => 255
65 say rgb_diff('000000', '000000'); # => 0
67 say rgb_diff('01f000', '04f400'); # => 5
68 say rgb_diff('ffff00', 'ffffff'); # => 255
69 say rgb_diff('000000', '000000', 'approx1'); # => 0
70 say rgb_diff('01f000', '04f400', 'approx1'); # => 9.06
71 say rgb_diff('ffff00', 'ffffff', 'approx1'); # => 360.98
72 say rgb_is_dark('404040'); # => 1
74 say rgb_is_dark('a0a0a0'); # => 0
75 say rgb_is_light('404040'); # => 0
76 say rgb_is_light('a0a0a0'); # => 1
77 say rgb_luminance('d090aa'); # => ffcc33
79 say tint_rgb_color('#ff8800', '#0033cc'); # => b36e3c
81
84 None are exported by default, but they are exportable.
85 assign_rgb_color
87 Usage:
88 my $rgb = assign_rgb_color($str);
90 Map a string to an RGB color. This is done by producing SHA-1 digest
92 (160bit, 20 bytes) of the string, then taking the first, 10th, and last
93 byte to become the RGB color.
94 assign_rgb_dark_color
96 Like "assign_rgb_color" except that it will make sure the assigned
97 color is dark.
98 assign_rgb_light_color
100 Like "assign_rgb_color" except that it will make sure the assigned
101 color is light.
102 hsl2hsv
104 Usage:
105 my $hsl = hsl2hsv("0 1 0.5"); # => "0 1 1"
107 Convert HSL to HSV.
109 hsl2rgb
111 Usage:
112 my $rgb = hsl2rgb("0 1 0.5"); # => ff0000
114 Convert HSL to RGB. HSL should be given in a whitespace-separated H,S,L
116 values e.g. "0 1 0.5". H (hue degree) has a range from 0-360 where 0 is
117 red, 120 is green, 240 is blue and 360 is back to red. S (saturation)
118 has a range from 0-1 where 0 is gray and 1 is fully saturated hue. L
119 (lumination) has a range from 0-1 where 0 is fully black, 0.5 fully
120 saturated, and 1 is fully white. See also "rgb2hsl".
121 hsv2hsl
123 Usage:
124 my $hsl = hsv2hsl("0 1 1"); # => "0 1 0.5"
126 Convert HSV to HSL.
128 hsv2rgb
130 Usage:
131 my $rgb = hsv2rgb("0 1 1"); # => ff0000
133 Convert HSV to RGB. HSV should be given in a whitespace-separated H,S,V
135 values e.g. "0 1 1". H (hue degree) has a range from 0-360 where 0 is
136 red, 120 is green, 240 is blue and 360 is back to red. S (saturation)
137 has a range from 0-1 where 0 is gray and 1 is fully saturated hue. V
138 (value) has a range from 0-1 where 0 is black and 1 is white. See also
139 "rgb2hsv".
140 int2rgb
142 Usage:
143 my $rgb = int2rgb(0xffffff); # => ffffff
145 Convert integer to RGB string.
147 mix_2_rgb_colors
149 Usage:
150 my $mixed_rgb = mix_2_rgb_colors($rgb1, $rgb2, $pct);
152 Mix 2 RGB colors. $pct is a number between 0 and 1, by default 0.5
154 (halfway), the closer to 1 the closer the resulting color to $rgb2.
155 mix_rgb_colors
157 Usage:
158 my $mixed_rgb = mix_rgb_colors($color1, $weight1, $color2, $weight2, ...);
160 Mix several RGB colors.
162 rand_rgb_color
164 Usage:
165 my $rgb = rand_rgb_color([ $low_limit [ , $high_limit ] ]);
167 Generate a random RGB color. You can specify the limit. Otherwise, they
169 default to the full range (000000 to ffffff).
170 rand_rgb_colors
172 Usage:
173 my @rgbs = rand_rgb_colors([ \%opts ], $num=1);
175 Produce $num random RGB colors, with some options. Will make reasonable
177 attempt to make the colors different from one another.
178 Known options:
180 · light_color
182 Boolean, default true. By default, this function will create light
184 RGB colors, assuming the background color is dark, which is often
185 the case in terminal. If this option is set to false, will create
186 dark colors instead, If this option is set to undef, will create
187 both dark and light colors.
188 · avoid_colors
190 Arrayref or hashref. List of colors to be avoided. You can put, for
192 example, colors that you've already assigned/picked for your
193 palette and don't want to use again.
194 · max_attempts
196 Uint, default 1000. Number of attempts to try generating the next
198 random color if the generated color is rejected because it is
199 light/dark, or because it's in "avoid_colors".
200 When the number of attempts has been exceeded, the generated color
202 is used anyway.
203 reverse_rgb_color
205 Usage:
206 my $reversed = reverse_rgb_color($rgb);
208 Reverse $rgb.
210 rgb2grayscale
212 Usage:
213 my $rgb_gs = rgb2grayscale($rgb);
215 Convert $rgb to grayscale RGB value.
217 rgb2hsl
219 Usage:
220 my $hsl = rgb2hsl($rgb); # example: "0 1 0.5"
222 Convert RGB (0-255) to HSL. The result is a space-separated H, S, L
224 values.
225 rgb2hsv
227 Usage:
228 my $hsv = rgb2hsv($rgb); # example: "0 1 255"
230 Convert RGB (0-255) to HSV. The result is a space-separated H, S, V
232 values. See
233 rgb2int
235 Usage:
236 my $int = rgb2int("ffffff"); # => 16777216, which is 0xffffff
238 Convert RGB string to integer.
240 rgb2sepia
242 Usage:
243 my $rgb_sepia = rgb2sepia($rgb);
245 Convert $rgb to sepia tone RGB value.
247 rgb_diff
249 Usage:
250 my $dist = rgb_diff($rgb1, $rgb2[ , $algo ])
252 Calculate difference between two RGB colors, using one of several
254 algorithms.
255 · euclidean
257 The default. It calculates the distance as:
259 ( (R1-R2)**2 + (G1-G2)**2 + (B1-B2)**2 )**0.5
261 which is the same as what "rgb_distance"() would produce.
263 · approx1
265 This algorithm uses the following formula:
267 ( 2*(R1-R2)**2 + 4*(G1-G2)**2 + 3*(B1-B2)**2 + Rm*((R1-R2)**2 - (B1-B2)**2)/256 )**0.5
269 where, Rm or "R mean" is (R1+R2)/2.
271 · approx2
273 Like "approx1", but uses this formula:
275 ( 2*(R1-R2)**2 + 4*(G1-G2)**2 + 3*(B1-B2)**2 )**0.5 # if Rm < 128
277 ( 3*(R1-R2)**2 + 4*(G1-G2)**2 + 2*(B1-B2)**2 )**0.5 # otherwise
278 · hsv_euclidean
280 Convert the RGB values to HSV, then calculate the HSV distance.
282 Please see source code for details.
283 · hsv_hue1
285 Like "hsv_euclidean" but puts more emphasis on hue difference. This
287 algorithm is used, for example, by Color::ANSI::Util when mapping
288 RGB 24bit color to the "closest" the ANSI 256-color or 16-color.
289 This algorithm tends to choose the hued colors instead of favoring
290 to fallback on white/gray, which is more preferred.
291 For more about color difference, try reading
293 <https://en.wikipedia.org/wiki/Color_difference>.
294 rgb_distance
296 Usage:
297 my $dist = rgb_distance($rgb1, $rgb2)
299 Calculate the euclidean RGB distance, using this formula:
301 ( (R1-R2)**2 + (G1-G2)**2 + (B1-B2)**2 )**0.5
303 For example, the distance between "000000" and "ffffff" is ~441.67,
305 while the distance between "ffff00" and "ffffff" is 255.
306 rgb_is_dark
308 Usage:
309 my $is_dark = rgb_is_dark($rgb)
311 Return true if $rgb is a "dark" color, which is determined by checking
313 if the RGB distance to "000000" is smaller than to "ffffff".
314 rgb_is_light
316 Usage:
317 my $is_light = rgb_is_light($rgb)
319 Return true if $rgb is a "light" color, which is determined by checking
321 if the RGB distance to "000000" is larger than to "ffffff".
322 rgb_luminance
324 Usage:
325 my $luminance = rgb_luminance($rgb);
327 Calculate standard/objective luminance from RGB value using this
329 formula:
330 (0.2126*R) + (0.7152*G) + (0.0722*B)
332 where R, G, and B range from 0 to 1. Return a number from 0 to 1.
334 tint_rgb_color
336 Usage:
337 my $new_rgb = tint_rgb_color($rgb, $tint_rgb, $pct)
339 Tint $rgb with $tint_rgb. $pct is by default 0.5. It is similar to
341 mixing, but the less luminance the color is the less it is tinted with
342 the tint color. This has the effect of black color still being black
343 instead of becoming tinted.
344
346 Please visit the project's homepage at
347 <https://metacpan.org/release/Color-RGB-Util>.
348
350 Source repository is at
351 <https://github.com/perlancar/perl-SHARYANTO-Color-Util>.
352
354 Please report any bugs or feature requests on the bugtracker website
355 <https://rt.cpan.org/Public/Dist/Display.html?Name=Color-RGB-Util>
356 When submitting a bug or request, please include a test-file or a patch
358 to an existing test-file that illustrates the bug or desired feature.
359
361 Color::ANSI::Util
362
364 perlancar <perlancar@cpan.org>
365
367 This software is copyright (c) 2020, 2019, 2018, 2015, 2014, 2013 by
368 perlancar@cpan.org.
369 This is free software; you can redistribute it and/or modify it under
371 the same terms as the Perl 5 programming language system itself.
372perl v5.32.0 2020-07-28 Color::RGB::Util(3)