NAME

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

VERSION

This document describes version 0.607 of Color::RGB::Util (from Perl distribution Color-RGB-Util), released on 2023-12-12.

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.

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.

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.

hsv2hsl

Usage:

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

Convert HSV to HSL.

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.

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

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

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

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_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 https://en.wikipedia.org/wiki/Color_difference.

[1] https://www.compuphase.com/cmetric.htm

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.

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.

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

To install Color::RGB::Util, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Color::RGB::Util

CPAN shell

perl -MCPAN -e shell
install Color::RGB::Util

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

FUNCTIONS

assign_rgb_color

assign_rgb_dark_color

assign_rgb_light_color

hsl2hsv

hsl2rgb

hsv2hsl

hsv2rgb

int2rgb

mix_2_rgb_colors

mix_rgb_colors

rand_rgb_color

rand_rgb_colors

reverse_rgb_color

rgb2grayscale

rgb2hsl

rgb2hsv

rgb2int

rgb2sepia

rgb_closest_to

rgb_diff

rgb_distance

rgb_is_dark

rgb_is_light

rgb_luminance

tint_rgb_color

HOMEPAGE

SOURCE

SEE ALSO

AUTHOR

CONTRIBUTOR

CONTRIBUTING

COPYRIGHT AND LICENSE

BUGS

Module Install Instructions