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

VERSION
    This document describes version 0.591 of Color::RGB::Util (from Perl
    distribution Color-RGB-Util), released on 2018-10-04.

SYNOPSIS
     use Color::RGB::Util qw(
         mix_2_rgb_colors
         rand_rgb_color
         rgb2grayscale
         rgb2sepia
         reverse_rgb_color
         rgb_luminance
         tint_rgb_color
         rgb_distance
         rgb_diff
         rgb_is_light
         rgb_is_dark
     );

     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 rand_rgb_color();
     say rand_rgb_color('000000', '333333');         # limit range

     say rgb2grayscale('0033CC');                    # => 555555

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

     say reverse_rgb_color('0033CC');                # => ffcc33

     say rgb_luminance('d090aa');                    # => ffcc33

     say tint_rgb_color('#ff8800', '#0033cc');       # => b36e3c

     say rgb_distance('000000', '000000')            # => 0
     say rgb_distance('01f000', '04f400')            # => 5
     say rgb_distance('ffff00', 'ffffff')            # => 255

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

DESCRIPTION
FUNCTIONS
    None are exported by default, but they are exportable.

  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.

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

  rgb2grayscale
    Usage:

     my $rgb_gs = rgb2grayscale($rgb);

    Convert $rgb to grayscale RGB value.

  rgb2sepia
    Usage:

     my $rgb_sepia = rgb2sepia($rgb);

    Convert $rgb to sepia tone RGB value.

  reverse_rgb_color
    Usage:

     my $reversed = reverse_rgb_color($rgb);

    Reverse $rgb.

  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.

  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_diff
    Usage:

     my $dist = rgb_diff($rgb1, $rgb2[ , $algo ])

    Calculate difference between two RGB colors, using one of several
    algorithms. The default ("euclidean") simply 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. Another
    algorithm ("approx1") 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.

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

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

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-SHARYANTO-Color-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) 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.

