--- name: "Color::RGB::Util" section: "3pm" platform: "linux" package: "libcolor-rgb-util-perl" version: "0.609-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Color::RGB::Util" --- # Color::RGB::Util(3pm) Utilities related to RGB colors ## NAME Color::RGB::Util - Utilities related to RGB colors ## VERSION This document describes version 0.609 of Color::RGB::Util (from Perl distribution Color-RGB-Util), released on 2025-03-19. ## SYNOPSIS ``` use Color::RGB::Util qw( assign_rgb_color assign_rgb_dark_color assign_rgb_light_color int2rgb mix_2_rgb_colors mix_rgb_colors rand_rgb_color rand_rgb_colors reverse_rgb_color rgb2grayscale rgb2int rgb2sepia rgb_closest_to rgb_diff rgb_distance rgb_is_dark rgb_is_light rgb_luminance tint_rgb_color ); say assign_rgb_color("foo"); # 0b5d33 say assign_rgb_dark_color("foo"); # 0b5d33 say assign_rgb_light_color("foo"); # 85ae99 say int2rgb(0xffffff); # ffffff say mix_2_rgb_colors('#ff0000', '#ffffff'); # pink (red + white) say mix_2_rgb_colors('ff0000', 'ffffff', 0.75); # pink with a whiter shade say mix_rgb_colors('ff0000', 1, 'ffffff', 1); # pink (red + white 1 : 1) say mix_rgb_colors('ff0000', 1, 'ffffff', 3); # pink with a whiter shade (red + white 1 : 3) say mix_rgb_colors('ff0000', 1, 'ffffff', 1, '0000ff', 0.5); # bluish pink say rand_rgb_color(); say rand_rgb_color('000000', '333333'); # limit range say rand_rgb_colors( {light_color => 1, avoid_colors=>[qw/ffffff ffcc00 ff00cc/], 3); # ("e9f3d7", "e0bbcc", "63f88c") say reverse_rgb_color('0033CC'); # => ffcc33 say rgb2grayscale('0033CC'); # => 555555 # default 'average' algo say rgb2grayscale('0033CC', 'weighted_average'); # => 353535 say rgb2int("ffffff"); # 16777215 (which is 0xffffff) say rgb2sepia('0033CC'); # => 4d4535 say rgb_closest_to('cc211e'); # => "red" say rgb_distance('000000', '000000') # => 0 say rgb_distance('01f000', '04f400') # => 5 say rgb_distance('ffff00', 'ffffff') # => 255 say rgb_diff('000000', '000000'); # => 0 say rgb_diff('01f000', '04f400'); # => 5 say rgb_diff('ffff00', 'ffffff'); # => 255 say rgb_diff('000000', '000000', 'approx1'); # => 0 say rgb_diff('01f000', '04f400', 'approx1'); # => 9.06 say rgb_diff('ffff00', 'ffffff', 'approx1'); # => 360.98 say rgb_is_dark('404040'); # => 1 say rgb_is_dark('a0a0a0'); # => 0 say rgb_is_light('404040'); # => 0 say rgb_is_light('a0a0a0'); # => 1 say rgb_luminance('d090aa'); # => ffcc33 say tint_rgb_color('#ff8800', '#0033cc'); # => b36e3c ``` ## DESCRIPTION ## FUNCTIONS None are exported by default, but they are exportable. ### assign\_rgb\_color Usage: ``` my $rgb = assign_rgb_color($str); ``` Map a string to an RGB color. This is done by producing SHA-1 digest (160bit, 20 bytes) of the string, then taking the first, 10th, and last byte to become the RGB color. See also: "assign\_rgb\_dark\_color" and "assign\_rgb\_light\_color". ### assign\_rgb\_dark\_color Like "assign\_rgb\_color" except that it will make sure the assigned color is dark. ### assign\_rgb\_light\_color Like "assign\_rgb\_color" except that it will make sure the assigned color is light. ### hsl2hsv Usage: ``` my $hsl = hsl2hsv("0 1 0.5"); # => "0 1 1" ``` Convert HSL to HSV. See also: "hsv2hsl". ### hsl2rgb Usage: ``` my $rgb = hsl2rgb("0 1 0.5"); # => ff0000 ``` Convert HSL to RGB. HSL should be given in a whitespace-separated H,S,L values e.g. "0 1 0.5". H (hue degree) has a range from 0-360 where 0 is red, 120 is green, 240 is blue and 360 is back to red. S (saturation) has a range from 0-1 where 0 is gray and 1 is fully saturated hue. L (lumination) has a range from 0-1 where 0 is fully black, 0.5 fully saturated, and 1 is fully white. See also "rgb2hsl". ### hsv2hsl Usage: ``` my $hsl = hsv2hsl("0 1 1"); # => "0 1 0.5" ``` Convert HSV to HSL. See also "hsl2hsv". ### hsv2rgb Usage: ``` my $rgb = hsv2rgb("0 1 1"); # => ff0000 ``` Convert HSV to RGB. HSV should be given in a whitespace-separated H,S,V values e.g. "0 1 1". H (hue degree) has a range from 0-360 where 0 is red, 120 is green, 240 is blue and 360 is back to red. S (saturation) has a range from 0-1 where 0 is gray and 1 is fully saturated hue. V (value) has a range from 0-1 where 0 is black and 1 is white. See also "rgb2hsv". ### int2rgb Usage: ``` my $rgb = int2rgb(0xffffff); # => ffffff ``` Convert integer to RGB string. See also "rgb2int". ### mix\_2\_rgb\_colors Usage: ``` my $mixed_rgb = mix_2_rgb_colors($rgb1, $rgb2, $pct); ``` Mix 2 RGB colors. `$pct` is a number between 0 and 1, by default 0.5 (halfway), the closer to 1 the closer the resulting color to `$rgb2`. See also "mix\_rgb\_colors", "tint\_rgb\_color". ### mix\_rgb\_colors Usage: ``` my $mixed_rgb = mix_rgb_colors($color1, $weight1, $color2, $weight2, ...); ``` Mix several RGB colors. See also "mix\_2\_rgb\_colors". ### rand\_rgb\_color Usage: ``` my $rgb = rand_rgb_color([ $low_limit [ , $high_limit ] ]); ``` Generate a random RGB color. You can specify the limit. Otherwise, they default to the full range (000000 to ffffff). See also "rand\_rgb\_colors". ### rand\_rgb\_colors Usage: ``` my @rgbs = rand_rgb_colors([ \%opts ], $num=1); ``` Produce `$num` random RGB colors, with some options. It does not (yet) create a palette of optimally distinct colors, but will make reasonable attempt to make the colors different from one another. Known options: - • from\_color RGB value, lower limit, optional. - • to\_color RGB value, high limit, optional. - • light\_color Boolean, default true. By default, this function will create light RGB colors, assuming the background color is dark, which is often the case in terminal. If this option is set to false, will create dark colors instead, If this option is set to undef, will create both dark and light colors. - • avoid\_colors Arrayref or hashref. List of colors to be avoided. You can put, for example, colors that you've already assigned/picked for your palette and don't want to use again. - • max\_attempts Uint, default 1000. Number of attempts to try generating the next random color if the generated color is rejected because it is light/dark, or because it's in `"avoid_colors"`. When the number of attempts has been exceeded, the generated color is used anyway. - • hash\_prefix Whether to add hash prefix to produced color codes ("#123456") or not ("123456"). See also "rand\_rgb\_color". ### reverse\_rgb\_color Usage: ``` my $reversed = reverse_rgb_color($rgb); ``` Reverse `$rgb`. ### rgb2grayscale Usage: ``` my $rgb_gs = rgb2grayscale($rgb [ , $algo ]); ``` Convert `$rgb` to grayscale RGB value. There are several algorithms (`$algo`) to choose from: - • average The Average method takes the average value of R, G, and B as the grayscale value. ``` Grayscale = (R + G + B ) / 3. ``` The average method is simple but does not take into account the non-linearity of human vision (eyes are most sensitive to green, less to red, least to blue). - • weighted\_average This method gives weights to each of red, green, blue elements to take into account the sensitivity of human eyes. ``` Grayscale = 0.299R + 0.587G + 0.114B ``` See also rgb2sepia. ### rgb2hsl Usage: ``` my $hsl = rgb2hsl($rgb); # example: "0 1 0.5" ``` Convert RGB (0-255) to HSL. The result is a space-separated H, S, L values. See also "hsl2rgb". ### rgb2hsv Usage: ``` my $hsv = rgb2hsv($rgb); # example: "0 1 255" ``` Convert RGB (0-255) to HSV. The result is a space-separated H, S, V values. See also "hsv2rgb". ### rgb2int Usage: ``` my $int = rgb2int("ffffff"); # => 16777216, which is 0xffffff ``` Convert RGB string to integer. See also "int2rgb". ### rgb2sepia Usage: ``` my $rgb_sepia = rgb2sepia($rgb); ``` Convert `$rgb` to sepia tone RGB value. See also rgb2grayscale. ### rgb\_closest\_to Usage: ``` my $colorname = rgb_closest_to( [ \%opts , ] $color); ``` Return the primary color `$color` is closest to. Options: - • colors A hash of color names and RGB values. If unspecified, the default is: ``` { black => "000000", blue => "0000ff", brown => "663333", cyan => "00ffff", # a.k.a. aqua green => "00ff00", grey => "808080", magenta => "ff00ff", # a.k.a. fuchsia orange => "ff8000", pink => "ffcccc", purple => "800080", # a.k.a. violet red => "ff0000", white => "ffffff", yellow => "ffff00", } ``` ### rgb\_diff Usage: ``` my $dist = rgb_diff($rgb1, $rgb2[ , $algo ]) ``` Calculate difference between two RGB colors, using one of several algorithms. - • euclidean The default. It calculates the distance as: ``` ( (R1-R2)**2 + (G1-G2)**2 + (B1-B2)**2 )**0.5 ``` which is the same as what "rgb\_distance"() would produce. - • approx1 This algorithm, described in \[1\] as "a low cost approximation" and "a combination both weighted Euclidean distance functions, where the weight factors depend on how big the 'red' component of the colour is" with "results that are very close to L\*u\*v" and "a more stable algorithm", uses the following formula: ``` ( 2*(R1-R2)**2 + 4*(G1-G2)**2 + 3*(B1-B2)**2 + Rm*((R1-R2)**2 - (B1-B2)**2)/256 )**0.5 ``` where, Rm or "R mean" is (R1+R2)/2. - • approx2 Like `"approx1"`, but uses this formula: ``` ( 2*(R1-R2)**2 + 4*(G1-G2)**2 + 3*(B1-B2)**2 )**0.5 # if Rm < 128 ( 3*(R1-R2)**2 + 4*(G1-G2)**2 + 2*(B1-B2)**2 )**0.5 # otherwise ``` - • hsv\_euclidean Convert the RGB values to HSV, then calculate the HSV distance. Please see source code for details. - • hsv\_hue1 Like `"hsv_euclidean"` but puts more emphasis on hue difference. This algorithm is used, for example, by Color::ANSI::Util when mapping RGB 24bit color to the "closest" the ANSI 256-color or 16-color. This algorithm tends to choose the hued colors instead of favoring to fallback on white/gray, which is more preferred. TODO: redmean low-cost approximation, CMC l:c. For more about color difference, try reading \. \[1\] https://www.compuphase.com/cmetric.htm See also rgb\_distance. ### rgb\_distance Usage: ``` my $dist = rgb_distance($rgb1, $rgb2) ``` Calculate the euclidean RGB distance, using this formula: ``` ( (R1-R2)**2 + (G1-G2)**2 + (B1-B2)**2 )**0.5 ``` For example, the distance between "000000" and "ffffff" is ~441.67, while the distance between "ffff00" and "ffffff" is 255. See also rgb\_diff. ### rgb\_is\_dark Usage: ``` my $is_dark = rgb_is_dark($rgb) ``` Return true if `$rgb` is a "dark" color, which is determined by checking if the RGB distance to "000000" is smaller than to "ffffff". See also "rgb\_is\_light". ### rgb\_is\_light Usage: ``` my $is_light = rgb_is_light($rgb) ``` Return true if `$rgb` is a "light" color, which is determined by checking if the RGB distance to "000000" is larger than to "ffffff". See also "rgb\_is\_dark". ### rgb\_luminance Usage: ``` my $luminance = rgb_luminance($rgb); ``` Calculate standard/objective luminance from RGB value using this formula: ``` (0.2126*R) + (0.7152*G) + (0.0722*B) ``` where R, G, and B range from 0 to 1. Return a number from 0 to 1. ### tint\_rgb\_color Usage: ``` my $new_rgb = tint_rgb_color($rgb, $tint_rgb, $pct) ``` Tint `$rgb` with `$tint_rgb`. `$pct` is by default 0.5. It is similar to mixing, but the less luminance the color is the less it is tinted with the tint color. This has the effect of black color still being black instead of becoming tinted. See also mix\_2\_rgb\_colors, mix\_rgb\_colors. ## HOMEPAGE Please visit the project's homepage at \. ## SOURCE Source repository is at \. ## SEE ALSO Color::ANSI::Util ## AUTHOR perlancar \ ## CONTRIBUTOR Steven Haryanto \ ## CONTRIBUTING To contribute, you can send patches by email/via RT, or send pull requests on GitHub. Most of the time, you don't need to build the distribution yourself. You can simply modify the code, then test via: ``` % prove -l ``` If you want to build the distribution (e.g. to try to install it locally on your system), you can install Dist::Zilla, Dist::Zilla::PluginBundle::Author::PERLANCAR, Pod::Weaver::PluginBundle::Author::PERLANCAR, and sometimes one or two other Dist::Zilla- and/or Pod::Weaver plugins. Any additional steps required beyond that are considered a bug and can be reported to me. ## COPYRIGHT AND LICENSE This software is copyright (c) 2025 by perlancar \. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. ## BUGS Please report any bugs or feature requests on the bugtracker website \ When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.