view release on metacpan or  search on metacpan

lib/Color/RGB/Util.pm  view on Meta::CPAN

Convert C<$rgb> to sepia tone RGB value.

See also L<rgb2grayscale>.

=head2 rgb_closest_to

Usage:

 my $colorname = rgb_closest_to( [ \%opts , ] $color);

Return the primary color C<$color> is closest to. Options:

=over

=item * 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",
 }

=back

=head2 rgb_diff

Usage:

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

Calculate difference between two RGB colors, using one of several algorithms.

=over

=item * 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 L</"rgb_distance">() would produce.

=item * 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.

=item * approx2

Like C<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

=item * hsv_euclidean

Convert the RGB values to HSV, then calculate the HSV distance. Please see
source code for details.

=item * hsv_hue1

Like C<hsv_euclidean> but puts more emphasis on hue difference. This algorithm
is used, for example, by L<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.

=back

TODO: redmean low-cost approximation, CMC l:c.

For more about color difference, try reading
L<https://en.wikipedia.org/wiki/Color_difference>.

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

See also L<rgb_distance>.

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

See also L<rgb_diff>.

=head2 rgb_is_dark

Usage:

 my $is_dark = rgb_is_dark($rgb)

Return true if C<$rgb> is a "dark" color, which is determined by checking if the
RGB distance to "000000" is smaller than to "ffffff".

See also L</rgb_is_light>.

=head2 rgb_is_light

Usage:

 my $is_light = rgb_is_light($rgb)

Return true if C<$rgb> is a "light" color, which is determined by checking if
the RGB distance to "000000" is larger than to "ffffff".

See also L</rgb_is_dark>.

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

=head2 tint_rgb_color

Usage:

 my $new_rgb = tint_rgb_color($rgb, $tint_rgb, $pct)

Tint C<$rgb> with C<$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.

See also L<mix_2_rgb_colors>, L<mix_rgb_colors>.

=head1 HOMEPAGE

Please visit the project's homepage at L<https://metacpan.org/release/Color-RGB-Util>.

=head1 SOURCE

Source repository is at L<https://github.com/perlancar/perl-Color-RGB-Util>.

=head1 SEE ALSO

L<Color::ANSI::Util>

=head1 AUTHOR

perlancar <perlancar@cpan.org>

=head1 CONTRIBUTOR

=for stopwords Steven Haryanto

Steven Haryanto <stevenharyanto@gmail.com>

=head1 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 L<Dist::Zilla>,
L<Dist::Zilla::PluginBundle::Author::PERLANCAR>,
L<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.

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2023, 2021, 2020, 2019, 2018, 2015, 2014, 2013 by perlancar <perlancar@cpan.org>.