Color::RGB::Util(3pm)

📦
version 0.609 · 7 versions
, in debian trixie, ubuntu resolute, ubuntu stonking

✨ NAME ✨

okay so bestie, welcome to Color::RGB::Util — the (3pm) Perl manpage — and it is literally just utilities related to RGB colors. that's the whole vibe. 🎨💖

🦋 VERSION 🦋

This document describes version 0.609 of Color::RGB::Util (from Perl distribution Color-RGB-Util), released on 2025-03-19. ✨

🌸 SYNOPSIS 🌸

okay so here's the entire squad getting imported, no cap — nineteen functions, all of them showing up to the party: 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. 🫶

and then every single one of them doing its little demo, exactly like this:

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

like… the range?? immaculate. 🌈✨

🎀 DESCRIPTION 🎀

okay bestie so, real talk: in the original page this section is literally empty — nothing here yet. the whole page is really the SYNOPSIS and then the sections that come after, so hold that thought. 💀🫶

and that's part 1, we are not done yet — more parts are coming, so don't go anywhere. 💅

✨ FUNCTIONS ✨

okay so none of these are exported by default, bestie — not a single one. but they're all exportable, so you can totally just ask for them by name. 💅

🎀 assign_rgb_color

Usage:

my $rgb = assign_rgb_color($str);

Map a string to an RGB color. how? it produces a SHA-1 digest (160bit, 20 bytes) of the string, then grabs the first, 10th, and last byte and those become the RGB color. that's it, that's the whole vibe. deterministic color assignment, slay. ✨

See also: "assign_rgb_dark_color" and "assign_rgb_light_color".

🌙 assign_rgb_dark_color

Like "assign_rgb_color" except it makes sure the assigned color is dark. so moody, so mysterious. 🖤

☀️ assign_rgb_light_color

Like "assign_rgb_color" except it makes sure the assigned color is light. main character energy, always glowing. ✨

🦋 hsl2hsv

Usage:

my $hsl = hsl2hsv("0 1 0.5"); # => "0 1 1"

Convert HSL to HSV. glow up but for color spaces fr fr.

See also: "hsv2hsl".

🌈 hsl2rgb

Usage:

my $rgb = hsl2rgb("0 1 0.5"); # => ff0000

Convert HSL to RGB. here's the tea on the input — HSL should be given as whitespace-separated H,S,L values, like "0 1 0.5".

  • H (hue degree) ranges from 0-360, where 0 is red, 120 is green, 240 is blue, and 360 is back to red again (full circle, iconic).
  • S (saturation) ranges from 0-1, where 0 is gray and 1 is a fully saturated hue.
  • L (lumination) ranges from 0-1, where 0 is fully black, 0.5 is 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. the reverse pipeline, we love a round trip. 🫶

See also "hsl2hsv".

🔥 hsv2rgb

Usage:

my $rgb = hsv2rgb("0 1 1"); # => ff0000

Convert HSV to RGB. input goes in as 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 an integer to an RGB string. numbers to colors, it's giving alchemy. 🧚

See also "rgb2int".

🎨 mix_2_rgb_colors

Usage:

my $mixed_rgb = mix_2_rgb_colors($rgb1, $rgb2, $pct);

Mix 2 RGB colors together. $pct is a number between 0 and 1, and by default it's 0.5 (halfway, dead center). the closer to 1 it is, the closer the resulting color lands to $rgb2. so $pct is basically "how much do we commit to color number two". 💅

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 at once. not just two — go wild, add as many color/weight pairs as you want. 👑

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 if you want. otherwise they default to the full range (000000 to ffffff). chaos mode: enabled. 🔥

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. heads up: it does not (yet) create a palette of optimally distinct colors, but it will make a reasonable attempt to make the colors different from one another. so like, best effort, not perfection. 🙈

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 creates light RGB colors, assuming the background color is dark (which is often the case in a terminal). If this option is set to false, it'll create dark colors instead. If this option is set to undef, it'll create both dark and light colors.
  • avoid_colors — Arrayref or hashref. List of colors to be avoided. put, like, the colors you've already assigned or picked for your palette so you don't get them again. no repeats bestie.
  • max_attempts — Uint, default 1000. Number of attempts to try generating the next random color if the generated color gets rejected for being light/dark, or because it's sitting in "avoid_colors".
⚠️ when the number of attempts has been exceeded, the generated color is used anyway. so it's a vibe-check limit, not a hard guarantee.
  • hash_prefix — Whether to add a 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. flip it and reverse it. 🔁

🩶 rgb2grayscale

Usage:

my $rgb_gs = rgb2grayscale($rgb [ , $algo ]);

Convert $rgb to a 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). biology said nope. 😭

  • weighted_average — This method gives weights to each of the 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 comes back as 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 comes back as space-separated H, S, V values.

See also "hsv2rgb".

🔟 rgb2int

Usage:

my $int = rgb2int("ffffff"); # => 16777216, which is 0xffffff

Convert an RGB string to an integer.

See also "int2rgb".

📸 rgb2sepia

Usage:

my $rgb_sepia = rgb2sepia($rgb);

Convert $rgb to a sepia tone RGB value. instant vintage filter, no app required. ✨

See also rgb2grayscale.

👑 rgb_closest_to

Usage:

my $colorname = rgb_closest_to( [ \%opts , ] $color);

Return the primary color that $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 the 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 <https://en.wikipedia.org/wiki/Color_difference>.

[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. math is mathing. 🧮

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 the standard/objective luminance from an RGB value using this formula:

(0.2126*R) + (0.7152*G) + (0.0722*B)

where R, G, and B range from 0 to 1. Returns a number from 0 to 1. the actual brightness tea, no vibes-based guessing. ☀️

🍓 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's similar to mixing, but the less luminance the color is, the less it gets tinted with the tint color. This has the effect of black color still being black instead of becoming tinted. respect the darkness fr. 🖤

See also mix_2_rgb_colors, mix_rgb_colors.

🏠 HOMEPAGE

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

📦 SOURCE

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

👀 SEE ALSO

Color::ANSI::Util

✍️ AUTHOR

perlancar <perlancar@cpan.org>

🤝 CONTRIBUTOR

Steven Haryanto <stevenharyanto@gmail.com>

💖 CONTRIBUTING

To contribute, you can send patches by email/via RT, or send pull requests on GitHub. pick your fighter, both are valid. 🫶

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.

This software is copyright (c) 2025 by perlancar <perlancar@cpan.org>.

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 🐛

okay bestie, found a glitch? a little oopsie? a vibe that is Not Vibing? 💀 do not suffer in silence, tell the devs!!

and listen, this is the part where you go from "person with a problem" to "person with a solution" ✨

  • 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.
fr fr, a test-file or a patch is the love language here 💖 it shows the bug in its natural habitat, or shows the feature doing its thing, and it makes everyone's life like a thousand times easier. no cap. 🎀

and that's the whole page, bestie!! you made it to the end 🎉💅 this little gem is perl v5.40.1, dated 2025-03-22, and it lives its best life as Color::RGB::Util(3pm) in the User Contributed Perl Documentation. go forth and color the world, you absolute icon 👑🦋🌈

📦 where this page comes from