1Color::RGB::Util(3)   User Contributed Perl Documentation  Color::RGB::Util(3)
2
3
4

NAME

6       Color::RGB::Util - Utilities related to RGB colors
7

VERSION

9       This document describes version 0.606 of Color::RGB::Util (from Perl
10       distribution Color-RGB-Util), released on 2021-08-06.
11

SYNOPSIS

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
34        say assign_rgb_color("foo");                    # 0b5d33
35        say assign_rgb_dark_color("foo");               # 0b5d33
36        say assign_rgb_light_color("foo");              # 85ae99
37
38        say int2rgb(0xffffff);                          # ffffff
39
40        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
43        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
47        say rand_rgb_color();
48        say rand_rgb_color('000000', '333333');         # limit range
49
50        say rand_rgb_colors(
51              {light_color => 1, avoid_colors=>[qw/ffffff ffcc00 ff00cc/],
52              3);                                       # ("e9f3d7", "e0bbcc", "63f88c")
53
54        say reverse_rgb_color('0033CC');                # => ffcc33
55
56        say rgb2grayscale('0033CC');                     # => 555555 # default 'average' algo
57        say rgb2grayscale('0033CC', 'weighted_average'); # => 353535
58
59        say rgb2int("ffffff");                          # 16777215 (which is 0xffffff)
60
61        say rgb2sepia('0033CC');                        # => 4d4535
62
63        say rgb_distance('000000', '000000')            # => 0
64        say rgb_distance('01f000', '04f400')            # => 5
65        say rgb_distance('ffff00', 'ffffff')            # => 255
66
67        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
74        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
79        say rgb_luminance('d090aa');                    # => ffcc33
80
81        say tint_rgb_color('#ff8800', '#0033cc');       # => b36e3c
82

DESCRIPTION

FUNCTIONS

85       None are exported by default, but they are exportable.
86
87   assign_rgb_color
88       Usage:
89
90        my $rgb = assign_rgb_color($str);
91
92       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
96       See also: "assign_rgb_dark_color" and "assign_rgb_light_color".
97
98   assign_rgb_dark_color
99       Like "assign_rgb_color" except that it will make sure the assigned
100       color is dark.
101
102   assign_rgb_light_color
103       Like "assign_rgb_color" except that it will make sure the assigned
104       color is light.
105
106   hsl2hsv
107       Usage:
108
109        my $hsl = hsl2hsv("0 1 0.5"); # => "0 1 1"
110
111       Convert HSL to HSV.
112
113       See also: "hsv2hsl".
114
115   hsl2rgb
116       Usage:
117
118        my $rgb = hsl2rgb("0 1 0.5"); # => ff0000
119
120       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
127       See also "rgb2hsl".
128
129   hsv2hsl
130       Usage:
131
132        my $hsl = hsv2hsl("0 1 1"); # => "0 1 0.5"
133
134       Convert HSV to HSL.
135
136       See also "hsl2hsv".
137
138   hsv2rgb
139       Usage:
140
141        my $rgb = hsv2rgb("0 1 1"); # => ff0000
142
143       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
149       See also "rgb2hsv".
150
151   int2rgb
152       Usage:
153
154        my $rgb = int2rgb(0xffffff); # => ffffff
155
156       Convert integer to RGB string.
157
158       See also "rgb2int".
159
160   mix_2_rgb_colors
161       Usage:
162
163        my $mixed_rgb = mix_2_rgb_colors($rgb1, $rgb2, $pct);
164
165       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
168       See also "mix_rgb_colors", "tint_rgb_color".
169
170   mix_rgb_colors
171       Usage:
172
173        my $mixed_rgb = mix_rgb_colors($color1, $weight1, $color2, $weight2, ...);
174
175       Mix several RGB colors.
176
177       See also "mix_2_rgb_colors".
178
179   rand_rgb_color
180       Usage:
181
182        my $rgb = rand_rgb_color([ $low_limit [ , $high_limit ] ]);
183
184       Generate a random RGB color. You can specify the limit. Otherwise, they
185       default to the full range (000000 to ffffff).
186
187       See also "rand_rgb_colors".
188
189   rand_rgb_colors
190       Usage:
191
192        my @rgbs = rand_rgb_colors([ \%opts ], $num=1);
193
194       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
198       Known options:
199
200       •   light_color
201
202           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
208       •   avoid_colors
209
210           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
214       •   max_attempts
215
216           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
220           When the number of attempts has been exceeded, the generated color
221           is used anyway.
222
223       •   hash_prefix
224
225           Whether to add hash prefix to produced color codes ("#123456") or
226           not ("123456").
227
228       See also "rand_rgb_color".
229
230   reverse_rgb_color
231       Usage:
232
233        my $reversed = reverse_rgb_color($rgb);
234
235       Reverse $rgb.
236
237   rgb2grayscale
238       Usage:
239
240        my $rgb_gs = rgb2grayscale($rgb [ , $algo ]);
241
242       Convert $rgb to grayscale RGB value. There are several algorithms
243       ($algo) to choose from:
244
245       •   average
246
247           The Average method takes the average value of R, G, and B as the
248           grayscale value.
249
250            Grayscale = (R + G + B ) / 3.
251
252           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
256       •   weighted_average
257
258           This method gives weights to each of red, green, blue elements to
259           take into account the sensitivity of human eyes.
260
261            Grayscale  = 0.299R + 0.587G + 0.114B
262
263       See also rgb2sepia.
264
265   rgb2hsl
266       Usage:
267
268        my $hsl = rgb2hsl($rgb); # example: "0 1 0.5"
269
270       Convert RGB (0-255) to HSL. The result is a space-separated H, S, L
271       values.
272
273       See also "hsl2rgb".
274
275   rgb2hsv
276       Usage:
277
278        my $hsv = rgb2hsv($rgb); # example: "0 1 255"
279
280       Convert RGB (0-255) to HSV. The result is a space-separated H, S, V
281       values.
282
283       See also "hsv2rgb".
284
285   rgb2int
286       Usage:
287
288        my $int = rgb2int("ffffff"); # => 16777216, which is 0xffffff
289
290       Convert RGB string to integer.
291
292       See also "int2rgb".
293
294   rgb2sepia
295       Usage:
296
297        my $rgb_sepia = rgb2sepia($rgb);
298
299       Convert $rgb to sepia tone RGB value.
300
301       See also rgb2grayscale.
302
303   rgb_diff
304       Usage:
305
306        my $dist = rgb_diff($rgb1, $rgb2[ , $algo ])
307
308       Calculate difference between two RGB colors, using one of several
309       algorithms.
310
311       •   euclidean
312
313           The default. It calculates the distance as:
314
315            ( (R1-R2)**2 + (G1-G2)**2 + (B1-B2)**2 )**0.5
316
317           which is the same as what "rgb_distance"() would produce.
318
319       •   approx1
320
321           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
327            ( 2*(R1-R2)**2 + 4*(G1-G2)**2 + 3*(B1-B2)**2 + Rm*((R1-R2)**2 - (B1-B2)**2)/256 )**0.5
328
329           where, Rm or "R mean" is (R1+R2)/2.
330
331       •   approx2
332
333           Like "approx1", but uses this formula:
334
335            ( 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
338       •   hsv_euclidean
339
340           Convert the RGB values to HSV, then calculate the HSV distance.
341           Please see source code for details.
342
343       •   hsv_hue1
344
345           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
351       TODO: redmean low-cost approximation, CMC l:c.
352
353       For more about color difference, try reading
354       <https://en.wikipedia.org/wiki/Color_difference>.
355
356       [1] https://www.compuphase.com/cmetric.htm
357
358       See also rgb_distance.
359
360   rgb_distance
361       Usage:
362
363        my $dist = rgb_distance($rgb1, $rgb2)
364
365       Calculate the euclidean RGB distance, using this formula:
366
367        ( (R1-R2)**2 + (G1-G2)**2 + (B1-B2)**2 )**0.5
368
369       For example, the distance between "000000" and "ffffff" is ~441.67,
370       while the distance between "ffff00" and "ffffff" is 255.
371
372       See also rgb_diff.
373
374   rgb_is_dark
375       Usage:
376
377        my $is_dark = rgb_is_dark($rgb)
378
379       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
382       See also "rgb_is_light".
383
384   rgb_is_light
385       Usage:
386
387        my $is_light = rgb_is_light($rgb)
388
389       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
392       See also "rgb_is_dark".
393
394   rgb_luminance
395       Usage:
396
397        my $luminance = rgb_luminance($rgb);
398
399       Calculate standard/objective luminance from RGB value using this
400       formula:
401
402        (0.2126*R) + (0.7152*G) + (0.0722*B)
403
404       where R, G, and B range from 0 to 1. Return a number from 0 to 1.
405
406   tint_rgb_color
407       Usage:
408
409        my $new_rgb = tint_rgb_color($rgb, $tint_rgb, $pct)
410
411       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
416       See also mix_2_rgb_colors, mix_rgb_colors.
417

HOMEPAGE

419       Please visit the project's homepage at
420       <https://metacpan.org/release/Color-RGB-Util>.
421

SOURCE

423       Source repository is at
424       <https://github.com/perlancar/perl-SHARYANTO-Color-Util>.
425

BUGS

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
430       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

SEE ALSO

434       Color::ANSI::Util
435

AUTHOR

437       perlancar <perlancar@cpan.org>
438

CONTRIBUTORS

440       •   ryosh2 (on pc-office) <ryosharyanto@gmail.com>
441
442       •   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
448       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.
450
451
452
453perl v5.38.0                      2023-07-20               Color::RGB::Util(3)
Impressum