.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" 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 "Graphics::ColorUtils 3pm"
.TH Graphics::ColorUtils 3pm "2022-11-19" "perl v5.36.0" "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"
Graphics::ColorUtils \- Easy\-to\-use color space conversions and more.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  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 );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This modules provides some utility functions to handle colors and
color space conversions.
.PP
The interface has been kept simple, so that most functions can be called
\&\*(L"inline\*(R" when making calls to graphics libraries such as \s-1GD,\s0 Tk, or
when generating \s-1HTML/CSS.\s0 (E.g. for \s-1GD:\s0
\&\f(CW\*(C`$c = $img\->colorAllocate( hsv2rgb( 270, 0.5, 0.3 ) );\*(C'\fR.)
.PP
Features:
.IP "Color Space Conversions" 4
.IX Item "Color Space Conversions"
Color space conversions, in particular between the \*(L"intuitive\*(R" color
spaces \s-1HSV\s0 (Hue/Saturation/Value) and \s-1HLS\s0 (Hue/Lightness/Saturation)
to and from \s-1RGB\s0 (Red/Green/Blue).
.IP "Color Lookup" 4
.IX Item "Color Lookup"
Color lookup by name for three standard sets of colors: \s-1WWW/CSS, SVG,\s0 and X11.
.IP "Color Gradients" 4
.IX Item "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.)
.SH "CONVENTIONS"
.IX Header "CONVENTIONS"
Legal values:
.PP
.Vb 2
\&  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
.Ve
.PP
All \f(CW\*(C`...2rgb\*(C'\fR functions return a three-element array in list context, 
and a string formatted according to \f(CW"#%02x%02x%02x"\fR (e.g. \f(CW\*(Aq#ff3a18\*(Aq\fR)
in scalar context.
.SH "METHODS"
.IX Header "METHODS"
.SS "Color Space Conversions"
.IX Subsection "Color Space Conversions"
.IP "\s-1YIQ\s0" 4
.IX Item "YIQ"
\&\f(CW\*(C`rgb2yiq( $r, $g, $b )\*(C'\fR and \f(CW\*(C`yiq2rgb( $y, $i, $q)\*(C'\fR
.IP "\s-1CMY\s0" 4
.IX Item "CMY"
\&\f(CW\*(C`rgb2cmy( $r, $g, $b )\*(C'\fR and \f(CW\*(C`cmy2rgb( $c, $m, $y)\*(C'\fR
.IP "\s-1HSV\s0" 4
.IX Item "HSV"
\&\f(CW\*(C`rgb2hsv( $r, $g, $b )\*(C'\fR and \f(CW\*(C`hsv2rgb( $h, $s, $v)\*(C'\fR
.IP "\s-1HLS\s0" 4
.IX Item "HLS"
\&\f(CW\*(C`rgb2hls( $r, $g, $b )\*(C'\fR and \f(CW\*(C`hls2rgb( $h, $l, $s)\*(C'\fR
.PP
All these methods take a triple of values and return a triple of
converted values. However, \fBin scalar context\fR the \f(CW\*(C`...2rgb\*(C'\fR
methods return a string formatted according to \f(CW"#%02x%02x%02x"\fR 
(e.g. \f(CW\*(Aq#ff3a18\*(Aq\fR). This format is appropriate e.g. for calls to
Tk routines: \f(CW\*(C`$mw\->widget( \-color =\*(C'\fR hls2rgb( 180, 0.2, 0.1 ) );>, etc.
.SS "Color Names"
.IX Subsection "Color Names"
Names can be arbitrary strings. If names contain a colon (\f(CW\*(Aq:\*(Aq\fR),
the part of the name before the colon is considered a \*(L"namespace\*(R"
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.
.ie n .IP """name2rgb( $name )""" 4
.el .IP "\f(CWname2rgb( $name )\fR" 4
.IX Item "name2rgb( $name )"
Returns a triple \f(CW\*(C`( $r, $g, $b )\*(C'\fR in list context or a a hex-string
in scalar context if the name has been found, \f(CW\*(C`undef\*(C'\fR otherwise.
.Sp
The name is normalized before lookup is attempted. Normalization consists
of: lowercasing and elimination of whitespace. Also, \*(L"gray\*(R" is replaced 
with \*(L"grey\*(R".
.Sp
If the name is prefixed with a namespace (separated by colon a \f(CW\*(Aq:\*(Aq\fR),
only this namespace is searched. If no namespace is specified, then
the lookup occurs first in the global namespace, then in the default
namespace.
.ie n .IP """available_names()""" 4
.el .IP "\f(CWavailable_names()\fR" 4
.IX Item "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 \s-1RGB\s0 values.
.ie n .IP """register_name( $name, $r, $g, $b )""" 4
.el .IP "\f(CWregister_name( $name, $r, $g, $b )\fR" 4
.IX Item "register_name( $name, $r, $g, $b )"
Takes a name and an \s-1RGB\s0 triple. Stores the triple for the given name.
The name will be normalized (lowercased, whitespace eliminated, 'gray' 
replaced by 'grey') before assignment is made.
.Sp
If the name is not prefixed by a namespace, the color will be entered 
into the global namespace.
.Sp
Returns the old value for the name, if the name already exists, 
\&\f(CW\*(C`undef\*(C'\fR otherwise.
.ie n .IP """get_default_namespace()""" 4
.el .IP "\f(CWget_default_namespace()\fR" 4
.IX Item "get_default_namespace()"
Returns the current value of the default namespace. Note that the 
empty string \f(CW\*(Aq\*(Aq\fR corresponds to the \fIglobal\fR namespace.
.ie n .IP """set_default_namespace()""" 4
.el .IP "\f(CWset_default_namespace()\fR" 4
.IX Item "set_default_namespace()"
Sets the default namespace. Returns the previous value.
.Sp
Giving an empty string as argument makes the global namespace the default.
Note that the global namespace is initially \fIempty\fR.
.Sp
(On startup, the default namespace is \f(CW\*(Aqx11\*(Aq\fR.)
.SS "Color Gradients"
.IX Subsection "Color Gradients"
.ie n .IP """grad2rgb( $name, $f )""" 4
.el .IP "\f(CWgrad2rgb( $name, $f )\fR" 4
.IX Item "grad2rgb( $name, $f )"
Given the name of a gradient and a floating point number between 0 and 1,
returns the color (as \s-1RGB\s0 triple or formatted hex-string) corresponding 
to the position in the gradient given by \f(CW$f\fR.
Returns \f(CW\*(C`undef\*(C'\fR when gradient not found or \f(CW$f\fR outside valid range.
.ie n .IP """available_gradients()""" 4
.el .IP "\f(CWavailable_gradients()\fR" 4
.IX Item "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.
.ie n .IP """gradient( $name )""" 4
.el .IP "\f(CWgradient( $name )\fR" 4
.IX Item "gradient( $name )"
Given the name of a gradient, returns a reference to an array of \s-1RGB\s0 
triples or \f(CW\*(C`undef\*(C'\fR if the gradient is not found.
.ie n .IP """register_gradient( $name, $array_ref )""" 4
.el .IP "\f(CWregister_gradient( $name, $array_ref )\fR" 4
.IX Item "register_gradient( $name, $array_ref )"
Takes the name of a (possibly new) gradient and a reference to an 
array of \s-1RGB\s0 triples. Stores the array as gradient for that name.
If the gradient name already existed, returns a reference to the
old array, \f(CW\*(C`undef\*(C'\fR otherwise.
.PP
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/
.SH "EXPORT"
.IX Header "EXPORT"
Exports by default:
.PP
.Vb 4
\&  rgb2yiq(), yiq2rgb()
\&  rgb2cmy(), cmy2rgb()
\&  rgb2hls(), hls2rgb()
\&  rgb2hsv(), hsv2rgb()
.Ve
.PP
Using the export tag \f(CW\*(C`:names\*(C'\fR, exports the following additional methods:
.PP
.Vb 5
\&  name2rgb()
\&  available_names()
\&  register_name()
\&  set_default_namespace()
\&  get_default_namespace()
.Ve
.PP
Using the export tag \f(CW\*(C`:gradients\*(C'\fR, exports the following additional methods:
.PP
.Vb 4
\&  gradient()
\&  grad2rgb()
\&  available_gradients()
\&  register_gradient()
.Ve
.SH "BUGS"
.IX Header "BUGS"
.IP "Input parameter validation" 4
.IX Item "Input parameter validation"
Most methods do \fInot\fR explicitly validate that their arguments lie
in the valid range.
.IP "Multiple namespaces" 4
.IX Item "Multiple namespaces"
Names containing multiple colons may not be handled correctly.
.IP "Hue wrap-around" 4
.IX Item "Hue wrap-around"
While hue should be restricted to 0..360, both \f(CW\*(C`hsv2rgb()\*(C'\fR and
\&\f(CW\*(C`hls2rgb()\*(C'\fR tolerate \*(L"moderate\*(R" violation of this constraint (up
to +/\- 359).
.SH "TODO"
.IX Header "TODO"
.IP "Perl Versions" 4
.IX Item "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.
.IP "Additional color space conversions" 4
.IX Item "Additional color space conversions"
For instance to and from \s-1XYZ, CIE,\s0 Luv; \fIif desired!\fR.
.IP "Additional pre-defined gradients" 4
.IX Item "Additional pre-defined gradients"
Suggestions welcome!
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.SS "Related Modules"
.IX Subsection "Related Modules"
.IP "Color::Rgb" 4
.IX Item "Color::Rgb"
Lookup of color values for names. Similar to the \*(L"names\*(R" methods
in this module. Requires \fIX11/rgb.txt\fR.
.IP "Graphics::ColorNames" 4
.IX Item "Graphics::ColorNames"
Lookup of color values for names. Similar to the \*(L"names\*(R" methods
in this module. Does \fInot\fR require \fIX11/rgb.txt\fR. Comes with
several sets of predefined color names (similar to this module).
.IP "Graphics::ColorObject" 4
.IX Item "Graphics::ColorObject"
Color space conversions, including conversions to and from \s-1XYZ\s0
and Luv. Object-oriented interface requires instantiation of a 
\&\*(L"color-object\*(R" for each color, which can then provide a 
representation of itself in all color spaces.
.IP "Color::Scheme" 4
.IX Item "Color::Scheme"
Generates pleasant color schemes (sets of colors).
.SS "Standard Color Sets"
.IX Subsection "Standard Color Sets"
.IP "\s-1WWW/CSS\s0" 4
.IX Item "WWW/CSS"
The 16 (or 17, including \*(L"orange\*(R") colors defined by the W3:
http://www.w3.org/TR/css3\-color
.IP "\s-1SVG\s0" 4
.IX Item "SVG"
The 138 unique named colors (140 normalized unique names) defined for 
\&\s-1SVG\s0 by the W3: http://www.w3.org/TR/SVG/types.html#ColorKeywords
.IP "X11" 4
.IX Item "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
.SS "Websites"
.IX Subsection "Websites"
.IP "\(bu" 4
Poynton's Color \s-1FAQ:\s0 http://www.poynton.com/ColorFAQ.html
.IP "\(bu" 4
Paper on Color Conversion Algorithms: http://www.poynton.com/PDFs/coloureq.pdf
.IP "\(bu" 4
Paul Bourke's Webpage with many relevant details: http://local.wasp.uwa.edu.au/~pbourke/texture_colour/
.SS "Books"
.IX Subsection "Books"
.IP "\(bu" 4
\&\fBComputer Graphics \- Principles and Practice\fR
by James D. Foley, Andries van Dam, Steven K. Feiner, John F. Hughes
(Second Edition in C, 1990, mult. print runs)
.Sp
\&\fIA comprehensive reference. \f(BIBeware of typos in the algorithms!\fI\fR
.IP "\(bu" 4
\&\fBIntroduction to Computer Graphics\fR
by James D. Foley, Andries van Dam, Steven K. Feiner, John F. Hughes, 
Richard L. Phillips (1990, mult. print runs)
.Sp
\&\fIA textbook based on the previous title. Possibly more accessible and
available.\fR
.IP "\(bu" 4
\&\fBComputer Graphics \- C Version\fR
by Donald Hearn and M. Pauline Baker (2nd ed, 1997)
.Sp
\&\fIAnother textbook.\fR
.SH "AUTHOR"
.IX Header "AUTHOR"
Philipp K. Janert, <janert at ieee dot org >, http://www.beyondcode.org
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2006 by Philipp K. Janert
.PP
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.