Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Color::RGB::Util(3)   User Contributed Perl Documentation  Color::RGB::Util(3)

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

VERSION
       This document describes version 0.601 of	Color::RGB::Util (from Perl
       distribution Color-RGB-Util), released on 2020-06-08.

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.

   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.	See also "rgb2hsl".

   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. See also
       "rgb2hsv".

   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:

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

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

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

   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.

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

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

       o   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

       o   hsv_euclidean

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

       o   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	about color difference,	try reading
       <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-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) 2020, 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.

perl v5.32.1			  2020-06-08		   Color::RGB::Util(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | FUNCTIONS | HOMEPAGE | SOURCE | BUGS | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Color::RGB::Util&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help