focal (3) Color::RGB::Util.3pm.gz
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.