1Graphics::ColorUtils(3)User Contributed Perl DocumentatioGnraphics::ColorUtils(3)
2
3
4

NAME

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

SYNOPSIS

9         use Graphics::ColorUtils;
10
11         ( $y, $i, $q ) = rgb2yiq( $r, $g, $b );
12         ( $r, $g, $b ) = yiq2rgb( $y, $i, $q );
13         $hex_string    = yiq2rgb( $y, $i, $q );
14
15         ( $c, $m, $y ) = rgb2cmy( $r, $g, $b );
16         ( $r, $g, $b ) = cmy2rgb( $c, $m, $y );
17         $hex_string    = cmy2rgb( $c, $m, $y );
18
19         ( $h, $l, $s ) = rgb2hls( $r, $g, $b );
20         ( $r, $g, $b ) = hls2rgb( $h, $l, $s );
21         $hex_string    = hls2rgb( $h, $l, $s );
22
23         ( $h, $s, $v ) = rgb2hsv( $r, $g, $b );
24         ( $r, $g, $b ) = hsv2rgb( $h, $s, $v );
25         $hex_string    = hsv2rgb( $h, $s, $v );
26
27         # -----
28
29         use Graphics::ColorUtils qw( :gradients );
30
31         ( $r, $g, $b ) = grad2rgb( $name, $f );  # where 0.0 <= $f < 1.0
32         $hex_string    = grad2rgb( $name, $f );
33
34         %color_count_for_gradient_name = available_gradients();
35         $array_ref_of_rgb_triples      = gradient( $name );
36         $array_ref_old_grad            = register_gradient( $name, $array_ref_of_rgb_triples );
37
38         # -----
39
40         use Graphics::ColorUtils qw( :names );
41
42         ( $r, $g, $b ) = name2rgb( $name );
43         $hex_string    = name2rgb( $name );
44
45         $hash_ref_rgb_triples_for_name = available_names();
46         ( $old_r, $old_g, $old_b )     = register_name( $name, $r, $g, $b );
47         $old_hex_string                = register_name( $name, $r, $g, $b );
48         $default_ns                    = get_default_namespace();
49         $old_ns                        = set_default_namespace( $new_ns );
50

DESCRIPTION

52       This modules provides some utility functions to handle colors and color
53       space conversions.
54
55       The interface has been kept simple, so that most functions can be
56       called "inline" when making calls to graphics libraries such as GD, Tk,
57       or when generating HTML/CSS. (E.g. for GD: "$c = $img->colorAllocate(
58       hsv2rgb( 270, 0.5, 0.3 ) );".)
59
60       Features:
61
62       Color Space Conversions
63           Color space conversions, in particular between the "intuitive"
64           color spaces HSV (Hue/Saturation/Value) and HLS
65           (Hue/Lightness/Saturation) to and from RGB (Red/Green/Blue).
66
67       Color Lookup
68           Color lookup by name for three standard sets of colors: WWW/CSS,
69           SVG, and X11.
70
71       Color Gradients
72           Management of color gradients, which can be indexed by a floating
73           point number in the range 0..1. (Mostly intended for false-color
74           data visualization.)
75

CONVENTIONS

77       Legal values:
78
79         Y, I, Q: 0..1
80         C, M, Y: 0..1
81
82         R, G, B: 0..255 (may be float on input, guaranteed int on output)
83
84         H:       0..360 (red=0->yellow->green=120->cyan->blue=240->magenta steps of 60)
85         S, V:    0..1
86         L, S:    0..1
87
88       All "...2rgb" functions return a three-element array in list context,
89       and a string formatted according to "#%02x%02x%02x" (e.g. '#ff3a18') in
90       scalar context.
91

METHODS

93   Color Space Conversions
94       YIQ "rgb2yiq( $r, $g, $b )" and "yiq2rgb( $y, $i, $q)"
95
96       CMY "rgb2cmy( $r, $g, $b )" and "cmy2rgb( $c, $m, $y)"
97
98       HSV "rgb2hsv( $r, $g, $b )" and "hsv2rgb( $h, $s, $v)"
99
100       HLS "rgb2hls( $r, $g, $b )" and "hls2rgb( $h, $l, $s)"
101
102       All these methods take a triple of values and return a triple of
103       converted values. However, in scalar context the "...2rgb" methods
104       return a string formatted according to "#%02x%02x%02x" (e.g.
105       '#ff3a18'). This format is appropriate e.g. for calls to Tk routines:
106       "$mw->widget( -color =" hls2rgb( 180, 0.2, 0.1 ) );>, etc.
107
108   Color Names
109       Names can be arbitrary strings. If names contain a colon (':'), the
110       part of the name before the colon is considered a "namespace"
111       specification. Namespaces allow to have multiple color values
112       corresponding to the same name and to control the priority in which
113       those values will be retrieved.
114
115       "name2rgb( $name )"
116           Returns a triple "( $r, $g, $b )" in list context or a a hex-string
117           in scalar context if the name has been found, "undef" otherwise.
118
119           The name is normalized before lookup is attempted. Normalization
120           consists of: lowercasing and elimination of whitespace. Also,
121           "gray" is replaced with "grey".
122
123           If the name is prefixed with a namespace (separated by colon a
124           ':'), only this namespace is searched. If no namespace is
125           specified, then the lookup occurs first in the global namespace,
126           then in the default namespace.
127
128       "available_names()"
129           Returns a reference to a hash, the keys of which are the color
130           names, and the values are references to three-element arrays of RGB
131           values.
132
133       "register_name( $name, $r, $g, $b )"
134           Takes a name and an RGB triple. Stores the triple for the given
135           name.  The name will be normalized (lowercased, whitespace
136           eliminated, 'gray' replaced by 'grey') before assignment is made.
137
138           If the name is not prefixed by a namespace, the color will be
139           entered into the global namespace.
140
141           Returns the old value for the name, if the name already exists,
142           "undef" otherwise.
143
144       "get_default_namespace()"
145           Returns the current value of the default namespace. Note that the
146           empty string '' corresponds to the global namespace.
147
148       "set_default_namespace()"
149           Sets the default namespace. Returns the previous value.
150
151           Giving an empty string as argument makes the global namespace the
152           default.  Note that the global namespace is initially empty.
153
154           (On startup, the default namespace is 'x11'.)
155
156   Color Gradients
157       "grad2rgb( $name, $f )"
158           Given the name of a gradient and a floating point number between 0
159           and 1, returns the color (as RGB triple or formatted hex-string)
160           corresponding to the position in the gradient given by $f.  Returns
161           "undef" when gradient not found or $f outside valid range.
162
163       "available_gradients()"
164           Returns a hash, the keys of which are the names of the known
165           gradients and the values being the number of colors in the
166           corresponding gradient.
167
168       "gradient( $name )"
169           Given the name of a gradient, returns a reference to an array of
170           RGB triples or "undef" if the gradient is not found.
171
172       "register_gradient( $name, $array_ref )"
173           Takes the name of a (possibly new) gradient and a reference to an
174           array of RGB triples. Stores the array as gradient for that name.
175           If the gradient name already existed, returns a reference to the
176           old array, "undef" otherwise.
177
178       An introduction, together with a large number of sample gradients can
179       be found at Paul Bourke's webpage:
180       http://local.wasp.uwa.edu.au/~pbourke/texture_colour/colourramp/
181

EXPORT

183       Exports by default:
184
185         rgb2yiq(), yiq2rgb()
186         rgb2cmy(), cmy2rgb()
187         rgb2hls(), hls2rgb()
188         rgb2hsv(), hsv2rgb()
189
190       Using the export tag ":names", exports the following additional
191       methods:
192
193         name2rgb()
194         available_names()
195         register_name()
196         set_default_namespace()
197         get_default_namespace()
198
199       Using the export tag ":gradients", exports the following additional
200       methods:
201
202         gradient()
203         grad2rgb()
204         available_gradients()
205         register_gradient()
206

BUGS

208       Input parameter validation
209           Most methods do not explicitly validate that their arguments lie in
210           the valid range.
211
212       Multiple namespaces
213           Names containing multiple colons may not be handled correctly.
214
215       Hue wrap-around
216           While hue should be restricted to 0..360, both "hsv2rgb()" and
217           "hls2rgb()" tolerate "moderate" violation of this constraint (up to
218           +/- 359).
219

TODO

221       Perl Versions
222           This module has only been explicitly tested with Perl 5.8, but
223           nothing (should) prevent it from running fine with other versions
224           of Perl.
225
226       Additional color space conversions
227           For instance to and from XYZ, CIE, Luv; if desired!.
228
229       Additional pre-defined gradients
230           Suggestions welcome!
231

SEE ALSO

233   Related Modules
234       Color::Rgb
235           Lookup of color values for names. Similar to the "names" methods in
236           this module. Requires X11/rgb.txt.
237
238       Graphics::ColorNames
239           Lookup of color values for names. Similar to the "names" methods in
240           this module. Does not require X11/rgb.txt. Comes with several sets
241           of predefined color names (similar to this module).
242
243       Graphics::ColorObject
244           Color space conversions, including conversions to and from XYZ and
245           Luv. Object-oriented interface requires instantiation of a "color-
246           object" for each color, which can then provide a representation of
247           itself in all color spaces.
248
249       Color::Scheme
250           Generates pleasant color schemes (sets of colors).
251
252   Standard Color Sets
253       WWW/CSS
254           The 16 (or 17, including "orange") colors defined by the W3:
255           http://www.w3.org/TR/css3-color
256
257       SVG The 138 unique named colors (140 normalized unique names) defined
258           for SVG by the W3:
259           http://www.w3.org/TR/SVG/types.html#ColorKeywords
260
261       X11 The 502 unique named colors (549 normalized unique names) defined
262           by the X11 libraries in /usr/lib/X11/rgb.txt on an X11 system
263
264   Websites
265       •   Poynton's Color FAQ: http://www.poynton.com/ColorFAQ.html
266
267       •   Paper on Color Conversion Algorithms:
268           http://www.poynton.com/PDFs/coloureq.pdf
269
270       •   Paul Bourke's Webpage with many relevant details:
271           http://local.wasp.uwa.edu.au/~pbourke/texture_colour/
272
273   Books
274Computer Graphics - Principles and Practice by James D. Foley,
275           Andries van Dam, Steven K. Feiner, John F. Hughes (Second Edition
276           in C, 1990, mult. print runs)
277
278           A comprehensive reference. Beware of typos in the algorithms!
279
280Introduction to Computer Graphics by James D. Foley, Andries van
281           Dam, Steven K. Feiner, John F. Hughes, Richard L. Phillips (1990,
282           mult. print runs)
283
284           A textbook based on the previous title. Possibly more accessible
285           and available.
286
287Computer Graphics - C Version by Donald Hearn and M. Pauline Baker
288           (2nd ed, 1997)
289
290           Another textbook.
291

AUTHOR

293       Philipp K. Janert, <janert at ieee dot org >, http://www.beyondcode.org
294
296       Copyright (C) 2006 by Philipp K. Janert
297
298       This library is free software; you can redistribute it and/or modify it
299       under the same terms as Perl itself, either Perl version 5.8.3 or, at
300       your option, any later version of Perl 5 you may have available.
301
302
303
304perl v5.34.0                      2022-01-21           Graphics::ColorUtils(3)
Impressum