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

FreeBSD Manual Pages

  
 
  

home | help
Graphics::ColorUtils(3User Contributed Perl DocumentatiGraphics::ColorUtils(3)

NAME
       Graphics::ColorUtils - Easy-to-use color	space conversions and more.

SYNOPSIS
	 use Graphics::ColorUtils;

	 ( $y, $i, $q )	= rgb2yiq( $r, $g, $b );
	 ( $r, $g, $b )	= yiq2rgb( $y, $i, $q );
	 $hex_string	= yiq2rgb( $y, $i, $q );

	 ( $c, $m, $y )	= rgb2cmy( $r, $g, $b );
	 ( $r, $g, $b )	= cmy2rgb( $c, $m, $y );
	 $hex_string	= cmy2rgb( $c, $m, $y );

	 ( $h, $l, $s )	= rgb2hls( $r, $g, $b );
	 ( $r, $g, $b )	= hls2rgb( $h, $l, $s );
	 $hex_string	= hls2rgb( $h, $l, $s );

	 ( $h, $s, $v )	= rgb2hsv( $r, $g, $b );
	 ( $r, $g, $b )	= hsv2rgb( $h, $s, $v );
	 $hex_string	= hsv2rgb( $h, $s, $v );

	 # -----

	 use Graphics::ColorUtils qw( :gradients );

	 ( $r, $g, $b )	= grad2rgb( $name, $f );  # where 0.0 <= $f < 1.0
	 $hex_string	= grad2rgb( $name, $f );

	 %color_count_for_gradient_name	= available_gradients();
	 $array_ref_of_rgb_triples	= gradient( $name );
	 $array_ref_old_grad		= register_gradient( $name, $array_ref_of_rgb_triples );

	 # -----

	 use Graphics::ColorUtils qw( :names );

	 ( $r, $g, $b )	= name2rgb( $name );
	 $hex_string	= name2rgb( $name );

	 $hash_ref_rgb_triples_for_name	= available_names();
	 ( $old_r, $old_g, $old_b )	= register_name( $name,	$r, $g,	$b );
	 $old_hex_string		= register_name( $name,	$r, $g,	$b );
	 $default_ns			= get_default_namespace();
	 $old_ns			= set_default_namespace( $new_ns );

DESCRIPTION
       This modules provides some utility functions to handle colors and color
       space conversions.

       The interface has been kept simple, so that most	functions can be
       called "inline" when making calls to graphics libraries such as GD, Tk,
       or when generating HTML/CSS. (E.g. for GD: "$c =	$img->colorAllocate(
       hsv2rgb(	270, 0.5, 0.3 )	);".)

       Features:

       Color Space Conversions
	   Color space conversions, in particular between the "intuitive"
	   color spaces	HSV (Hue/Saturation/Value) and HLS
	   (Hue/Lightness/Saturation) to and from RGB (Red/Green/Blue).

       Color Lookup
	   Color lookup	by name	for three standard sets	of colors: WWW/CSS,
	   SVG,	and X11.

       Color Gradients
	   Management of color gradients, which	can be indexed by a floating
	   point number	in the range 0..1. (Mostly intended for	false-color
	   data	visualization.)

CONVENTIONS
       Legal values:

	 Y, I, Q: 0..1
	 C, M, Y: 0..1

	 R, G, B: 0..255 (may be float on input, guaranteed int	on output)

	 H:	  0..360 (red=0->yellow->green=120->cyan->blue=240->magenta steps of 60)
	 S, V:	  0..1
	 L, S:	  0..1

       All "...2rgb" functions return a	three-element array in list context,
       and a string formatted according	to "#%02x%02x%02x" (e.g. '#ff3a18') in
       scalar context.

METHODS
   Color Space Conversions
       YIQ "rgb2yiq( $r, $g, $b	)" and "yiq2rgb( $y, $i, $q)"

       CMY "rgb2cmy( $r, $g, $b	)" and "cmy2rgb( $c, $m, $y)"

       HSV "rgb2hsv( $r, $g, $b	)" and "hsv2rgb( $h, $s, $v)"

       HLS "rgb2hls( $r, $g, $b	)" and "hls2rgb( $h, $l, $s)"

       All these methods take a	triple of values and return a triple of
       converted values. However, in scalar context the	"...2rgb" methods
       return a	string formatted according to "#%02x%02x%02x" (e.g.
       '#ff3a18'). This	format is appropriate e.g. for calls to	Tk routines:
       "$mw->widget( -color =" hls2rgb(	180, 0.2, 0.1 )	);>, etc.

   Color Names
       Names can be arbitrary strings. If names	contain	a colon	(':'), the
       part of the name	before the colon is considered a "namespace"
       specification. Namespaces allow to have multiple	color values
       corresponding to	the same name and to control the priority in which
       those values will be retrieved.

       "name2rgb( $name	)"
	   Returns a triple "( $r, $g, $b )" in	list context or	a a hex-string
	   in scalar context if	the name has been found, "undef" otherwise.

	   The name is normalized before lookup	is attempted. Normalization
	   consists of:	lowercasing and	elimination of whitespace. Also,
	   "gray" is replaced with "grey".

	   If the name is prefixed with	a namespace (separated by colon	a
	   ':'), only this namespace is	searched. If no	namespace is
	   specified, then the lookup occurs first in the global namespace,
	   then	in the default namespace.

       "available_names()"
	   Returns a reference to a hash, the keys of which are	the color
	   names, and the values are references	to three-element arrays	of RGB
	   values.

       "register_name( $name, $r, $g, $b )"
	   Takes a name	and an RGB triple. Stores the triple for the given
	   name.  The name will	be normalized (lowercased, whitespace
	   eliminated, 'gray' replaced by 'grey') before assignment is made.

	   If the name is not prefixed by a namespace, the color will be
	   entered into	the global namespace.

	   Returns the old value for the name, if the name already exists,
	   "undef" otherwise.

       "get_default_namespace()"
	   Returns the current value of	the default namespace. Note that the
	   empty string	'' corresponds to the global namespace.

       "set_default_namespace()"
	   Sets	the default namespace. Returns the previous value.

	   Giving an empty string as argument makes the	global namespace the
	   default.  Note that the global namespace is initially empty.

	   (On startup,	the default namespace is 'x11'.)

   Color Gradients
       "grad2rgb( $name, $f )"
	   Given the name of a gradient	and a floating point number between 0
	   and 1, returns the color (as	RGB triple or formatted	hex-string)
	   corresponding to the	position in the	gradient given by $f.  Returns
	   "undef" when	gradient not found or $f outside valid range.

       "available_gradients()"
	   Returns a hash, the keys of which are the names of the known
	   gradients and the values being the number of	colors in the
	   corresponding gradient.

       "gradient( $name	)"
	   Given the name of a gradient, returns a reference to	an array of
	   RGB triples or "undef" if the gradient is not found.

       "register_gradient( $name, $array_ref )"
	   Takes the name of a (possibly new) gradient and a reference to an
	   array of RGB	triples. Stores	the array as gradient for that name.
	   If the gradient name	already	existed, returns a reference to	the
	   old array, "undef" otherwise.

       An introduction,	together with a	large number of	sample gradients can
       be found	at Paul	Bourke's webpage:
       http://local.wasp.uwa.edu.au/~pbourke/texture_colour/colourramp/

EXPORT
       Exports by default:

	 rgb2yiq(), yiq2rgb()
	 rgb2cmy(), cmy2rgb()
	 rgb2hls(), hls2rgb()
	 rgb2hsv(), hsv2rgb()

       Using the export	tag ":names", exports the following additional
       methods:

	 name2rgb()
	 available_names()
	 register_name()
	 set_default_namespace()
	 get_default_namespace()

       Using the export	tag ":gradients", exports the following	additional
       methods:

	 gradient()
	 grad2rgb()
	 available_gradients()
	 register_gradient()

BUGS
       Input parameter validation
	   Most	methods	do not explicitly validate that	their arguments	lie in
	   the valid range.

       Multiple	namespaces
	   Names containing multiple colons may	not be handled correctly.

       Hue wrap-around
	   While hue should be restricted to 0..360, both "hsv2rgb()" and
	   "hls2rgb()" tolerate	"moderate" violation of	this constraint	(up to
	   +/- 359).

TODO
       Perl Versions
	   This	module has only	been explicitly	tested with Perl 5.8, but
	   nothing (should) prevent it from running fine with other versions
	   of Perl.

       Additional color	space conversions
	   For instance	to and from XYZ, CIE, Luv; if desired!.

       Additional pre-defined gradients
	   Suggestions welcome!

SEE ALSO
   Related Modules
       Color::Rgb
	   Lookup of color values for names. Similar to	the "names" methods in
	   this	module.	Requires X11/rgb.txt.

       Graphics::ColorNames
	   Lookup of color values for names. Similar to	the "names" methods in
	   this	module.	Does not require X11/rgb.txt. Comes with several sets
	   of predefined color names (similar to this module).

       Graphics::ColorObject
	   Color space conversions, including conversions to and from XYZ and
	   Luv.	Object-oriented	interface requires instantiation of a "color-
	   object" for each color, which can then provide a representation of
	   itself in all color spaces.

       Color::Scheme
	   Generates pleasant color schemes (sets of colors).

   Standard Color Sets
       WWW/CSS
	   The 16 (or 17, including "orange") colors defined by	the W3:
	   http://www.w3.org/TR/css3-color

       SVG The 138 unique named	colors (140 normalized unique names) defined
	   for SVG by the W3:
	   http://www.w3.org/TR/SVG/types.html#ColorKeywords

       X11 The 502 unique named	colors (549 normalized unique names) defined
	   by the X11 libraries	in /usr/lib/X11/rgb.txt	on an X11 system

   Websites
       o   Poynton's Color FAQ:	http://www.poynton.com/ColorFAQ.html

       o   Paper on Color Conversion Algorithms:
	   http://www.poynton.com/PDFs/coloureq.pdf

       o   Paul	Bourke's Webpage with many relevant details:
	   http://local.wasp.uwa.edu.au/~pbourke/texture_colour/

   Books
       o   Computer Graphics - Principles and Practice by James	D. Foley,
	   Andries van Dam, Steven K. Feiner, John F. Hughes (Second Edition
	   in C, 1990, mult. print runs)

	   A comprehensive reference. Beware of	typos in the algorithms!

       o   Introduction	to Computer Graphics by	James D. Foley,	Andries	van
	   Dam,	Steven K. Feiner, John F. Hughes, Richard L. Phillips (1990,
	   mult. print runs)

	   A textbook based on the previous title. Possibly more accessible
	   and available.

       o   Computer Graphics - C Version by Donald Hearn and M.	Pauline	Baker
	   (2nd	ed, 1997)

	   Another textbook.

AUTHOR
       Philipp K. Janert, <janert at ieee dot org >, http://www.beyondcode.org

COPYRIGHT AND LICENSE
       Copyright (C) 2006 by Philipp K.	Janert

       This library is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself, either Perl	version	5.8.3 or, at
       your option, any	later version of Perl 5	you may	have available.

perl v5.32.1			  2007-05-21	       Graphics::ColorUtils(3)

NAME | SYNOPSIS | DESCRIPTION | CONVENTIONS | METHODS | EXPORT | BUGS | TODO | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE

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

home | help