.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Color::RGB::Util 3pm" .TH Color::RGB::Util 3pm "2021-08-23" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Color::RGB::Util \- Utilities related to RGB colors .SH "VERSION" .IX Header "VERSION" This document describes version 0.606 of Color::RGB::Util (from Perl distribution Color-RGB-Util), released on 2021\-08\-06. .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 10 \& 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(\*(Aq#ff0000\*(Aq, \*(Aq#ffffff\*(Aq); # pink (red + white) \& say mix_2_rgb_colors(\*(Aqff0000\*(Aq, \*(Aqffffff\*(Aq, 0.75); # pink with a whiter shade \& \& say mix_rgb_colors(\*(Aqff0000\*(Aq, 1, \*(Aqffffff\*(Aq, 1); # pink (red + white 1 : 1) \& say mix_rgb_colors(\*(Aqff0000\*(Aq, 1, \*(Aqffffff\*(Aq, 3); # pink with a whiter shade (red + white 1 : 3) \& say mix_rgb_colors(\*(Aqff0000\*(Aq, 1, \*(Aqffffff\*(Aq, 1, \*(Aq0000ff\*(Aq, 0.5); # bluish pink \& \& say rand_rgb_color(); \& say rand_rgb_color(\*(Aq000000\*(Aq, \*(Aq333333\*(Aq); # limit range \& \& say rand_rgb_colors( \& {light_color => 1, avoid_colors=>[qw/ffffff ffcc00 ff00cc/], \& 3); # ("e9f3d7", "e0bbcc", "63f88c") \& \& say reverse_rgb_color(\*(Aq0033CC\*(Aq); # => ffcc33 \& \& say rgb2grayscale(\*(Aq0033CC\*(Aq); # => 555555 # default \*(Aqaverage\*(Aq algo \& say rgb2grayscale(\*(Aq0033CC\*(Aq, \*(Aqweighted_average\*(Aq); # => 353535 \& \& say rgb2int("ffffff"); # 16777215 (which is 0xffffff) \& \& say rgb2sepia(\*(Aq0033CC\*(Aq); # => 4d4535 \& \& say rgb_distance(\*(Aq000000\*(Aq, \*(Aq000000\*(Aq) # => 0 \& say rgb_distance(\*(Aq01f000\*(Aq, \*(Aq04f400\*(Aq) # => 5 \& say rgb_distance(\*(Aqffff00\*(Aq, \*(Aqffffff\*(Aq) # => 255 \& \& say rgb_diff(\*(Aq000000\*(Aq, \*(Aq000000\*(Aq); # => 0 \& say rgb_diff(\*(Aq01f000\*(Aq, \*(Aq04f400\*(Aq); # => 5 \& say rgb_diff(\*(Aqffff00\*(Aq, \*(Aqffffff\*(Aq); # => 255 \& say rgb_diff(\*(Aq000000\*(Aq, \*(Aq000000\*(Aq, \*(Aqapprox1\*(Aq); # => 0 \& say rgb_diff(\*(Aq01f000\*(Aq, \*(Aq04f400\*(Aq, \*(Aqapprox1\*(Aq); # => 9.06 \& say rgb_diff(\*(Aqffff00\*(Aq, \*(Aqffffff\*(Aq, \*(Aqapprox1\*(Aq); # => 360.98 \& \& say rgb_is_dark(\*(Aq404040\*(Aq); # => 1 \& say rgb_is_dark(\*(Aqa0a0a0\*(Aq); # => 0 \& say rgb_is_light(\*(Aq404040\*(Aq); # => 0 \& say rgb_is_light(\*(Aqa0a0a0\*(Aq); # => 1 \& \& say rgb_luminance(\*(Aqd090aa\*(Aq); # => ffcc33 \& \& say tint_rgb_color(\*(Aq#ff8800\*(Aq, \*(Aq#0033cc\*(Aq); # => b36e3c .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" .SH "FUNCTIONS" .IX Header "FUNCTIONS" None are exported by default, but they are exportable. .SS "assign_rgb_color" .IX Subsection "assign_rgb_color" Usage: .PP .Vb 1 \& my $rgb = assign_rgb_color($str); .Ve .PP Map a string to an \s-1RGB\s0 color. This is done by producing \s-1SHA\-1\s0 digest (160bit, 20 bytes) of the string, then taking the first, 10th, and last byte to become the \&\s-1RGB\s0 color. .PP See also: \*(L"assign_rgb_dark_color\*(R" and \*(L"assign_rgb_light_color\*(R". .SS "assign_rgb_dark_color" .IX Subsection "assign_rgb_dark_color" Like \*(L"assign_rgb_color\*(R" except that it will make sure the assigned color is dark. .SS "assign_rgb_light_color" .IX Subsection "assign_rgb_light_color" Like \*(L"assign_rgb_color\*(R" except that it will make sure the assigned color is light. .SS "hsl2hsv" .IX Subsection "hsl2hsv" Usage: .PP .Vb 1 \& my $hsl = hsl2hsv("0 1 0.5"); # => "0 1 1" .Ve .PP Convert \s-1HSL\s0 to \s-1HSV.\s0 .PP See also: \*(L"hsv2hsl\*(R". .SS "hsl2rgb" .IX Subsection "hsl2rgb" Usage: .PP .Vb 1 \& my $rgb = hsl2rgb("0 1 0.5"); # => ff0000 .Ve .PP Convert \s-1HSL\s0 to \s-1RGB. HSL\s0 should be given in a whitespace-separated H,S,L values e.g. \*(L"0 1 0.5\*(R". 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. .PP See also \*(L"rgb2hsl\*(R". .SS "hsv2hsl" .IX Subsection "hsv2hsl" Usage: .PP .Vb 1 \& my $hsl = hsv2hsl("0 1 1"); # => "0 1 0.5" .Ve .PP Convert \s-1HSV\s0 to \s-1HSL.\s0 .PP See also \*(L"hsl2hsv\*(R". .SS "hsv2rgb" .IX Subsection "hsv2rgb" Usage: .PP .Vb 1 \& my $rgb = hsv2rgb("0 1 1"); # => ff0000 .Ve .PP Convert \s-1HSV\s0 to \s-1RGB. HSV\s0 should be given in a whitespace-separated H,S,V values e.g. \*(L"0 1 1\*(R". 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. .PP See also \*(L"rgb2hsv\*(R". .SS "int2rgb" .IX Subsection "int2rgb" Usage: .PP .Vb 1 \& my $rgb = int2rgb(0xffffff); # => ffffff .Ve .PP Convert integer to \s-1RGB\s0 string. .PP See also \*(L"rgb2int\*(R". .SS "mix_2_rgb_colors" .IX Subsection "mix_2_rgb_colors" Usage: .PP .Vb 1 \& my $mixed_rgb = mix_2_rgb_colors($rgb1, $rgb2, $pct); .Ve .PP Mix 2 \s-1RGB\s0 colors. \f(CW$pct\fR is a number between 0 and 1, by default 0.5 (halfway), the closer to 1 the closer the resulting color to \f(CW$rgb2\fR. .PP See also \*(L"mix_rgb_colors\*(R", \*(L"tint_rgb_color\*(R". .SS "mix_rgb_colors" .IX Subsection "mix_rgb_colors" Usage: .PP .Vb 1 \& my $mixed_rgb = mix_rgb_colors($color1, $weight1, $color2, $weight2, ...); .Ve .PP Mix several \s-1RGB\s0 colors. .PP See also \*(L"mix_2_rgb_colors\*(R". .SS "rand_rgb_color" .IX Subsection "rand_rgb_color" Usage: .PP .Vb 1 \& my $rgb = rand_rgb_color([ $low_limit [ , $high_limit ] ]); .Ve .PP Generate a random \s-1RGB\s0 color. You can specify the limit. Otherwise, they default to the full range (000000 to ffffff). .PP See also \*(L"rand_rgb_colors\*(R". .SS "rand_rgb_colors" .IX Subsection "rand_rgb_colors" Usage: .PP .Vb 1 \& my @rgbs = rand_rgb_colors([ \e%opts ], $num=1); .Ve .PP Produce \f(CW$num\fR random \s-1RGB\s0 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. .PP Known options: .IP "\(bu" 4 light_color .Sp Boolean, default true. By default, this function will create light \s-1RGB\s0 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. .IP "\(bu" 4 avoid_colors .Sp 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. .IP "\(bu" 4 max_attempts .Sp 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 \&\f(CW\*(C`avoid_colors\*(C'\fR. .Sp When the number of attempts has been exceeded, the generated color is used anyway. .IP "\(bu" 4 hash_prefix .Sp Whether to add hash prefix to produced color codes (\*(L"#123456\*(R") or not (\*(L"123456\*(R"). .PP See also \*(L"rand_rgb_color\*(R". .SS "reverse_rgb_color" .IX Subsection "reverse_rgb_color" Usage: .PP .Vb 1 \& my $reversed = reverse_rgb_color($rgb); .Ve .PP Reverse \f(CW$rgb\fR. .SS "rgb2grayscale" .IX Subsection "rgb2grayscale" Usage: .PP .Vb 1 \& my $rgb_gs = rgb2grayscale($rgb [ , $algo ]); .Ve .PP Convert \f(CW$rgb\fR to grayscale \s-1RGB\s0 value. There are several algorithms (\f(CW$algo\fR) to choose from: .IP "\(bu" 4 average .Sp The Average method takes the average value of R, G, and B as the grayscale value. .Sp .Vb 1 \& Grayscale = (R + G + B ) / 3. .Ve .Sp 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). .IP "\(bu" 4 weighted_average .Sp This method gives weights to each of red, green, blue elements to take into account the sensitivity of human eyes. .Sp .Vb 1 \& Grayscale = 0.299R + 0.587G + 0.114B .Ve .PP See also rgb2sepia. .SS "rgb2hsl" .IX Subsection "rgb2hsl" Usage: .PP .Vb 1 \& my $hsl = rgb2hsl($rgb); # example: "0 1 0.5" .Ve .PP Convert \s-1RGB\s0 (0\-255) to \s-1HSL.\s0 The result is a space-separated H, S, L values. .PP See also \*(L"hsl2rgb\*(R". .SS "rgb2hsv" .IX Subsection "rgb2hsv" Usage: .PP .Vb 1 \& my $hsv = rgb2hsv($rgb); # example: "0 1 255" .Ve .PP Convert \s-1RGB\s0 (0\-255) to \s-1HSV.\s0 The result is a space-separated H, S, V values. .PP See also \*(L"hsv2rgb\*(R". .SS "rgb2int" .IX Subsection "rgb2int" Usage: .PP .Vb 1 \& my $int = rgb2int("ffffff"); # => 16777216, which is 0xffffff .Ve .PP Convert \s-1RGB\s0 string to integer. .PP See also \*(L"int2rgb\*(R". .SS "rgb2sepia" .IX Subsection "rgb2sepia" Usage: .PP .Vb 1 \& my $rgb_sepia = rgb2sepia($rgb); .Ve .PP Convert \f(CW$rgb\fR to sepia tone \s-1RGB\s0 value. .PP See also rgb2grayscale. .SS "rgb_diff" .IX Subsection "rgb_diff" Usage: .PP .Vb 1 \& my $dist = rgb_diff($rgb1, $rgb2[ , $algo ]) .Ve .PP Calculate difference between two \s-1RGB\s0 colors, using one of several algorithms. .IP "\(bu" 4 euclidean .Sp The default. It calculates the distance as: .Sp .Vb 1 \& ( (R1\-R2)**2 + (G1\-G2)**2 + (B1\-B2)**2 )**0.5 .Ve .Sp which is the same as what \*(L"rgb_distance\*(R"() would produce. .IP "\(bu" 4 approx1 .Sp This algorithm, described in [1] as \*(L"a low cost approximation\*(R" and \*(L"a combination both weighted Euclidean distance functions, where the weight factors depend on how big the 'red' component of the colour is\*(R" with \*(L"results that are very close to L*u*v\*(R" and \*(L"a more stable algorithm\*(R", uses the following formula: .Sp .Vb 1 \& ( 2*(R1\-R2)**2 + 4*(G1\-G2)**2 + 3*(B1\-B2)**2 + Rm*((R1\-R2)**2 \- (B1\-B2)**2)/256 )**0.5 .Ve .Sp where, Rm or \*(L"R mean\*(R" is (R1+R2)/2. .IP "\(bu" 4 approx2 .Sp Like \f(CW\*(C`approx1\*(C'\fR, but uses this formula: .Sp .Vb 2 \& ( 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 .Ve .IP "\(bu" 4 hsv_euclidean .Sp Convert the \s-1RGB\s0 values to \s-1HSV,\s0 then calculate the \s-1HSV\s0 distance. Please see source code for details. .IP "\(bu" 4 hsv_hue1 .Sp Like \f(CW\*(C`hsv_euclidean\*(C'\fR but puts more emphasis on hue difference. This algorithm is used, for example, by Color::ANSI::Util when mapping \s-1RGB\s0 24bit color to the \*(L"closest\*(R" the \s-1ANSI\s0 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. .PP \&\s-1TODO:\s0 redmean low-cost approximation, \s-1CMC\s0 l:c. .PP For more about color difference, try reading . .PP [1] https://www.compuphase.com/cmetric.htm .PP See also rgb_distance. .SS "rgb_distance" .IX Subsection "rgb_distance" Usage: .PP .Vb 1 \& my $dist = rgb_distance($rgb1, $rgb2) .Ve .PP Calculate the euclidean \s-1RGB\s0 distance, using this formula: .PP .Vb 1 \& ( (R1\-R2)**2 + (G1\-G2)**2 + (B1\-B2)**2 )**0.5 .Ve .PP For example, the distance between \*(L"000000\*(R" and \*(L"ffffff\*(R" is ~441.67, while the distance between \*(L"ffff00\*(R" and \*(L"ffffff\*(R" is 255. .PP See also rgb_diff. .SS "rgb_is_dark" .IX Subsection "rgb_is_dark" Usage: .PP .Vb 1 \& my $is_dark = rgb_is_dark($rgb) .Ve .PP Return true if \f(CW$rgb\fR is a \*(L"dark\*(R" color, which is determined by checking if the \&\s-1RGB\s0 distance to \*(L"000000\*(R" is smaller than to \*(L"ffffff\*(R". .PP See also \*(L"rgb_is_light\*(R". .SS "rgb_is_light" .IX Subsection "rgb_is_light" Usage: .PP .Vb 1 \& my $is_light = rgb_is_light($rgb) .Ve .PP Return true if \f(CW$rgb\fR is a \*(L"light\*(R" color, which is determined by checking if the \s-1RGB\s0 distance to \*(L"000000\*(R" is larger than to \*(L"ffffff\*(R". .PP See also \*(L"rgb_is_dark\*(R". .SS "rgb_luminance" .IX Subsection "rgb_luminance" Usage: .PP .Vb 1 \& my $luminance = rgb_luminance($rgb); .Ve .PP Calculate standard/objective luminance from \s-1RGB\s0 value using this formula: .PP .Vb 1 \& (0.2126*R) + (0.7152*G) + (0.0722*B) .Ve .PP where R, G, and B range from 0 to 1. Return a number from 0 to 1. .SS "tint_rgb_color" .IX Subsection "tint_rgb_color" Usage: .PP .Vb 1 \& my $new_rgb = tint_rgb_color($rgb, $tint_rgb, $pct) .Ve .PP Tint \f(CW$rgb\fR with \f(CW$tint_rgb\fR. \f(CW$pct\fR 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. .PP See also mix_2_rgb_colors, mix_rgb_colors. .SH "HOMEPAGE" .IX Header "HOMEPAGE" Please visit the project's homepage at . .SH "SOURCE" .IX Header "SOURCE" Source repository is at . .SH "BUGS" .IX Header "BUGS" Please report any bugs or feature requests on the bugtracker website .PP 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. .SH "SEE ALSO" .IX Header "SEE ALSO" Color::ANSI::Util .SH "AUTHOR" .IX Header "AUTHOR" perlancar .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" .IP "\(bu" 4 ryosh2 (on pc-office) .IP "\(bu" 4 Steven Haryanto .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2021, 2020, 2019, 2018, 2015, 2014, 2013 by perlancar@cpan.org. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.