Color::RGB::Util(3pm)

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.604 of Color::RGB::Util (from Perl
10       distribution Color-RGB-Util), released on 2021-01-19.
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
57
58        say rgb2int("ffffff");                          # 16777215 (which is 0xffffff)
59
60        say rgb2sepia('0033CC');                        # => 4d4535
61
62        say rgb_distance('000000', '000000')            # => 0
63        say rgb_distance('01f000', '04f400')            # => 5
64        say rgb_distance('ffff00', 'ffffff')            # => 255
65
66        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
73        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
78        say rgb_luminance('d090aa');                    # => ffcc33
79
80        say tint_rgb_color('#ff8800', '#0033cc');       # => b36e3c
81

DESCRIPTION

FUNCTIONS

84       None are exported by default, but they are exportable.
85
86   assign_rgb_color
87       Usage:
88
89        my $rgb = assign_rgb_color($str);
90
91       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
95   assign_rgb_dark_color
96       Like "assign_rgb_color" except that it will make sure the assigned
97       color is dark.
98
99   assign_rgb_light_color
100       Like "assign_rgb_color" except that it will make sure the assigned
101       color is light.
102
103   hsl2hsv
104       Usage:
105
106        my $hsl = hsl2hsv("0 1 0.5"); # => "0 1 1"
107
108       Convert HSL to HSV.
109
110   hsl2rgb
111       Usage:
112
113        my $rgb = hsl2rgb("0 1 0.5"); # => ff0000
114
115       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
122   hsv2hsl
123       Usage:
124
125        my $hsl = hsv2hsl("0 1 1"); # => "0 1 0.5"
126
127       Convert HSV to HSL.
128
129   hsv2rgb
130       Usage:
131
132        my $rgb = hsv2rgb("0 1 1"); # => ff0000
133
134       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
141   int2rgb
142       Usage:
143
144        my $rgb = int2rgb(0xffffff); # => ffffff
145
146       Convert integer to RGB string.
147
148   mix_2_rgb_colors
149       Usage:
150
151        my $mixed_rgb = mix_2_rgb_colors($rgb1, $rgb2, $pct);
152
153       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
156   mix_rgb_colors
157       Usage:
158
159        my $mixed_rgb = mix_rgb_colors($color1, $weight1, $color2, $weight2, ...);
160
161       Mix several RGB colors.
162
163   rand_rgb_color
164       Usage:
165
166        my $rgb = rand_rgb_color([ $low_limit [ , $high_limit ] ]);
167
168       Generate a random RGB color. You can specify the limit. Otherwise, they
169       default to the full range (000000 to ffffff).
170
171   rand_rgb_colors
172       Usage:
173
174        my @rgbs = rand_rgb_colors([ \%opts ], $num=1);
175
176       Produce $num random RGB colors, with some options. It does not (yet)
177       create a palette of optimally distinct colors, but will make reasonable
178       attempt to make the colors different from one another.
179
180       Known options:
181
182       •   light_color
183
184           Boolean, default true. By default, this function will create light
185           RGB colors, assuming the background color is dark, which is often
186           the case in terminal. If this option is set to false, will create
187           dark colors instead, If this option is set to undef, will create
188           both dark and light colors.
189
190       •   avoid_colors
191
192           Arrayref or hashref. List of colors to be avoided. You can put, for
193           example, colors that you've already assigned/picked for your
194           palette and don't want to use again.
195
196       •   max_attempts
197
198           Uint, default 1000. Number of attempts to try generating the next
199           random color if the generated color is rejected because it is
200           light/dark, or because it's in "avoid_colors".
201
202           When the number of attempts has been exceeded, the generated color
203           is used anyway.
204
205       •   hash_prefix
206
207           Whether to add hash prefix to produced color codes ("#123456") or
208           not ("123456").
209
210   reverse_rgb_color
211       Usage:
212
213        my $reversed = reverse_rgb_color($rgb);
214
215       Reverse $rgb.
216
217   rgb2grayscale
218       Usage:
219
220        my $rgb_gs = rgb2grayscale($rgb);
221
222       Convert $rgb to grayscale RGB value.
223
224   rgb2hsl
225       Usage:
226
227        my $hsl = rgb2hsl($rgb); # example: "0 1 0.5"
228
229       Convert RGB (0-255) to HSL. The result is a space-separated H, S, L
230       values.
231
232   rgb2hsv
233       Usage:
234
235        my $hsv = rgb2hsv($rgb); # example: "0 1 255"
236
237       Convert RGB (0-255) to HSV. The result is a space-separated H, S, V
238       values. See
239
240   rgb2int
241       Usage:
242
243        my $int = rgb2int("ffffff"); # => 16777216, which is 0xffffff
244
245       Convert RGB string to integer.
246
247   rgb2sepia
248       Usage:
249
250        my $rgb_sepia = rgb2sepia($rgb);
251
252       Convert $rgb to sepia tone RGB value.
253
254   rgb_diff
255       Usage:
256
257        my $dist = rgb_diff($rgb1, $rgb2[ , $algo ])
258
259       Calculate difference between two RGB colors, using one of several
260       algorithms.
261
262       •   euclidean
263
264           The default. It calculates the distance as:
265
266            ( (R1-R2)**2 + (G1-G2)**2 + (B1-B2)**2 )**0.5
267
268           which is the same as what "rgb_distance"() would produce.
269
270       •   approx1
271
272           This algorithm, described in [1] as "a low cost approximation" and
273           "a combination both weighted Euclidean distance functions, where
274           the weight factors depend on how big the 'red' component of the
275           colour is" with "results that are very close to L*u*v" and "a more
276           stable algorithm", uses the following formula:
277
278            ( 2*(R1-R2)**2 + 4*(G1-G2)**2 + 3*(B1-B2)**2 + Rm*((R1-R2)**2 - (B1-B2)**2)/256 )**0.5
279
280           where, Rm or "R mean" is (R1+R2)/2.
281
282       •   approx2
283
284           Like "approx1", but uses this formula:
285
286            ( 2*(R1-R2)**2 + 4*(G1-G2)**2 + 3*(B1-B2)**2 )**0.5  # if Rm < 128
287            ( 3*(R1-R2)**2 + 4*(G1-G2)**2 + 2*(B1-B2)**2 )**0.5  # otherwise
288
289       •   hsv_euclidean
290
291           Convert the RGB values to HSV, then calculate the HSV distance.
292           Please see source code for details.
293
294       •   hsv_hue1
295
296           Like "hsv_euclidean" but puts more emphasis on hue difference. This
297           algorithm is used, for example, by Color::ANSI::Util when mapping
298           RGB 24bit color to the "closest" the ANSI 256-color or 16-color.
299           This algorithm tends to choose the hued colors instead of favoring
300           to fallback on white/gray, which is more preferred.
301
302       TODO: redmean low-cost approximation, CMC l:c.
303
304       For more about color difference, try reading
305       <https://en.wikipedia.org/wiki/Color_difference>.
306
307       [1] https://www.compuphase.com/cmetric.htm
308
309   rgb_distance
310       Usage:
311
312        my $dist = rgb_distance($rgb1, $rgb2)
313
314       Calculate the euclidean RGB distance, using this formula:
315
316        ( (R1-R2)**2 + (G1-G2)**2 + (B1-B2)**2 )**0.5
317
318       For example, the distance between "000000" and "ffffff" is ~441.67,
319       while the distance between "ffff00" and "ffffff" is 255.
320
321   rgb_is_dark
322       Usage:
323
324        my $is_dark = rgb_is_dark($rgb)
325
326       Return true if $rgb is a "dark" color, which is determined by checking
327       if the RGB distance to "000000" is smaller than to "ffffff".
328
329   rgb_is_light
330       Usage:
331
332        my $is_light = rgb_is_light($rgb)
333
334       Return true if $rgb is a "light" color, which is determined by checking
335       if the RGB distance to "000000" is larger than to "ffffff".
336
337   rgb_luminance
338       Usage:
339
340        my $luminance = rgb_luminance($rgb);
341
342       Calculate standard/objective luminance from RGB value using this
343       formula:
344
345        (0.2126*R) + (0.7152*G) + (0.0722*B)
346
347       where R, G, and B range from 0 to 1. Return a number from 0 to 1.
348
349   tint_rgb_color
350       Usage:
351
352        my $new_rgb = tint_rgb_color($rgb, $tint_rgb, $pct)
353
354       Tint $rgb with $tint_rgb. $pct is by default 0.5. It is similar to
355       mixing, but the less luminance the color is the less it is tinted with
356       the tint color.  This has the effect of black color still being black
357       instead of becoming tinted.
358

HOMEPAGE

360       Please visit the project's homepage at
361       <https://metacpan.org/release/Color-RGB-Util>.
362

SOURCE

364       Source repository is at
365       <https://github.com/perlancar/perl-Color-RGB-Util>.
366

BUGS

368       Please report any bugs or feature requests on the bugtracker website
369       <https://github.com/perlancar/perl-Color-RGB-Util/issues>
370
371       When submitting a bug or request, please include a test-file or a patch
372       to an existing test-file that illustrates the bug or desired feature.
373

AUTHOR

378       perlancar <perlancar@cpan.org>
379

COPYRIGHT AND LICENSE

381       This software is copyright (c) 2021, 2020, 2019, 2018, 2015, 2014, 2013
382       by perlancar@cpan.org.
383
384       This is free software; you can redistribute it and/or modify it under
385       the same terms as the Perl 5 programming language system itself.
386
387
388
389perl v5.32.1                      2021-03-24               Color::RGB::Util(3)