Provided by: libcolor-rgb-util-perl_0.599-2_all bug

NAME

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

VERSION

       This document describes version 0.599 of Color::RGB::Util (from Perl distribution Color-
       RGB-Util), released on 2019-08-20.

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

        say rgb2int("ffffff");                          # 16777215 (which is 0xffffff)

        say rgb2sepia('0033CC');                        # => 4d4535

        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.

   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.

   int2rgb
       Usage:

        my $rgb = int2rgb(0xffffff); # => ffffff

       Convert integer to RGB string.

   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.

   mix_rgb_colors
       Usage:

        my $mixed_rgb = mix_rgb_colors($color1, $weight1, $color2, $weight2, ...);

       Mix several 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).

   rand_rgb_colors
       Usage:

        my @rgbs = rand_rgb_colors([ \%opts ], $num=1);

       Produce $num random RGB colors, with some options. Will make reasonable attempt to make
       the colors different from one another.

       Known options:

       ·   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.

   reverse_rgb_color
       Usage:

        my $reversed = reverse_rgb_color($rgb);

       Reverse $rgb.

   rgb2grayscale
       Usage:

        my $rgb_gs = rgb2grayscale($rgb);

       Convert $rgb to grayscale RGB value.

   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.

   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.

   rgb2int
       Usage:

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

       Convert RGB string to integer.

   rgb2sepia
       Usage:

        my $rgb_sepia = rgb2sepia($rgb);

       Convert $rgb to sepia tone RGB value.

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

       For more details about color difference, refer to
       <https://en.wikipedia.org/wiki/Color_difference>.

   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.

   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".

   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".

   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.

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

BUGS

       Please report any bugs or feature requests on the bugtracker website
       <https://rt.cpan.org/Public/Dist/Display.html?Name=Color-RGB-Util>

       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.

SEE ALSO

       Color::ANSI::Util

AUTHOR

       perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2019, 2018, 2015, 2014, 2013 by 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.