1Graphics::ColorUtils(3)User Contributed Perl DocumentatioGnraphics::ColorUtils(3)
2
6 Graphics::ColorUtils - Easy-to-use color space conversions and more.
7
9 use Graphics::ColorUtils;
10 ( $y, $i, $q ) = rgb2yiq( $r, $g, $b );
12 ( $r, $g, $b ) = yiq2rgb( $y, $i, $q );
13 $hex_string = yiq2rgb( $y, $i, $q );
14 ( $c, $m, $y ) = rgb2cmy( $r, $g, $b );
16 ( $r, $g, $b ) = cmy2rgb( $c, $m, $y );
17 $hex_string = cmy2rgb( $c, $m, $y );
18 ( $h, $l, $s ) = rgb2hls( $r, $g, $b );
20 ( $r, $g, $b ) = hls2rgb( $h, $l, $s );
21 $hex_string = hls2rgb( $h, $l, $s );
22 ( $h, $s, $v ) = rgb2hsv( $r, $g, $b );
24 ( $r, $g, $b ) = hsv2rgb( $h, $s, $v );
25 $hex_string = hsv2rgb( $h, $s, $v );
26 # -----
28 use Graphics::ColorUtils qw( :gradients );
30 ( $r, $g, $b ) = grad2rgb( $name, $f ); # where 0.0 <= $f < 1.0
32 $hex_string = grad2rgb( $name, $f );
33 %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 # -----
39 use Graphics::ColorUtils qw( :names );
41 ( $r, $g, $b ) = name2rgb( $name );
43 $hex_string = name2rgb( $name );
44 $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
52 This modules provides some utility functions to handle colors and color
53 space conversions.
54 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 Features:
61 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 Color Lookup
68 Color lookup by name for three standard sets of colors: WWW/CSS,
69 SVG, and X11.
70 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
77 Legal values:
78 Y, I, Q: 0..1
80 C, M, Y: 0..1
81 R, G, B: 0..255 (may be float on input, guaranteed int on output)
83 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 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
93 Color Space Conversions
94 YIQ "rgb2yiq( $r, $g, $b )" and "yiq2rgb( $y, $i, $q)"
95 CMY "rgb2cmy( $r, $g, $b )" and "cmy2rgb( $c, $m, $y)"
97 HSV "rgb2hsv( $r, $g, $b )" and "hsv2rgb( $h, $s, $v)"
99 HLS "rgb2hls( $r, $g, $b )" and "hls2rgb( $h, $l, $s)"
101 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 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 "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 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 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 "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 "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 If the name is not prefixed by a namespace, the color will be
139 entered into the global namespace.
140 Returns the old value for the name, if the name already exists,
142 "undef" otherwise.
143 "get_default_namespace()"
145 Returns the current value of the default namespace. Note that the
146 empty string '' corresponds to the global namespace.
147 "set_default_namespace()"
149 Sets the default namespace. Returns the previous value.
150 Giving an empty string as argument makes the global namespace the
152 default. Note that the global namespace is initially empty.
153 (On startup, the default namespace is 'x11'.)
155 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 "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 "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 "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 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
183 Exports by default:
184 rgb2yiq(), yiq2rgb()
186 rgb2cmy(), cmy2rgb()
187 rgb2hls(), hls2rgb()
188 rgb2hsv(), hsv2rgb()
189 Using the export tag ":names", exports the following additional
191 methods:
192 name2rgb()
194 available_names()
195 register_name()
196 set_default_namespace()
197 get_default_namespace()
198 Using the export tag ":gradients", exports the following additional
200 methods:
201 gradient()
203 grad2rgb()
204 available_gradients()
205 register_gradient()
206
208 Input parameter validation
209 Most methods do not explicitly validate that their arguments lie in
210 the valid range.
211 Multiple namespaces
213 Names containing multiple colons may not be handled correctly.
214 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
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 Additional color space conversions
227 For instance to and from XYZ, CIE, Luv; if desired!.
228 Additional pre-defined gradients
230 Suggestions welcome!
231
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 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 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 Color::Scheme
250 Generates pleasant color schemes (sets of colors).
251 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 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 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 Websites
265 • Poynton's Color FAQ: http://www.poynton.com/ColorFAQ.html
266 • Paper on Color Conversion Algorithms:
268 http://www.poynton.com/PDFs/coloureq.pdf
269 • Paul Bourke's Webpage with many relevant details:
271 http://local.wasp.uwa.edu.au/~pbourke/texture_colour/
272 Books
274 • Computer 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 A comprehensive reference. Beware of typos in the algorithms!
279 • Introduction 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 A textbook based on the previous title. Possibly more accessible
285 and available.
286 • Computer Graphics - C Version by Donald Hearn and M. Pauline Baker
288 (2nd ed, 1997)
289 Another textbook.
291
293 Philipp K. Janert, <janert at ieee dot org >, http://www.beyondcode.org
294
296 Copyright (C) 2006 by Philipp K. Janert
297 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.
301perl v5.34.0 2022-01-21 Graphics::ColorUtils(3)