1Color::Calc(3) User Contributed Perl Documentation Color::Calc(3)
2
6 Color::Calc - Simple calculations with RGB colors.
7
9 use Color::Calc ();
10 my $background = 'green';
11 print 'background: ',Color::Calc::color_html($background),";\n";
12 print 'border-top: solid 1px ',Color::Calc::light_html($background),";\n";
13 print 'border-bottom: solid 1px ',Color::Calc::dark_html($background),";\n";
14 print 'color: ',Color::Calc::contrast_bw_html($background),";\n";
15
17 The "Color::Calc" module implements simple calculations with RGB
18 colors. This can be used to create a full color scheme from a few
19 colors.
20 USAGE
22 Constructors
23 Color::Calc->new( ... )
25 This class method creates a new "Color::Calc" object.
26 use Color::Calc();
28 my $cc = new Color::Calc( 'ColorScheme' => 'X', OutputFormat => 'HTML' );
29 print $cc->invert( 'white' );
30 It accepts the following parameters:
32 ColorScheme
34 One of the color schemes accepted by "Graphics::ColorNames",
35 which is used to interpret color names on input. Valid values
36 include "X" (color names used in X-Windows) and "HTML" (color
37 names defined in the HTML 4.0 specification). For a full list
38 of possible values, please refer to the documentation of of
39 "Graphics::ColorNames".
40 Default: "X" (Note: This is incompatible with HTML color
42 names).
43 OutputFormat
45 One of the output formats defined by this module. Possible
46 values are:
47 tuple
49 Returns a list of three values in the range 0..255. The
50 first value is guaranteed to have a "length" that is not a
51 multiple of three.
52 hex Returns a hexadecimal RGB value as a scalar that contains a
54 string in the format RRGGBB and a number representing the
55 hexadecimal number 0xRRGGBB.
56 html
58 Returns a string compatible with W3C's HTML and CSS
59 specifications, i.e. #RRGGBB or one of the sixteen HTML
60 color names.
61 obj (DEPRECATED) Returns a "Color::Object" reference. The
63 module "Color::Object" must be installed, of course.
64 object
66 Returns a "Graphics::ColorObject" reference. The module
67 "Graphics::ColorObject" must be installed, of course.
68 pdf Returns a string compatible with "PDF::API2", i.e. #RRGGBB.
70 __MODEvar
72 (DEPRECATED) Uses the value of $Color::Calc::MODE to select
73 one of the above output formats. You should use "local"
74 when setting this variable:
75 local $Color::Calc::MODE = 'html';
77 Default: "__MODEvar" (for compatibility)
79 Color::Calc->import( ... )
81 This method creates a new, hidden object and binds its methods to
82 the namespace of the calling module.
83 This method is usually not called directly but from perl's "use"
85 statement:
86 use Color::Calc(
88 'ColorScheme' => 'X',
89 'OutputFormat' => 'HTML',
90 'Prefix' => 'cc' );
91 print cc_invert( 'white' ); # prints 'black'
92 On import, you can specify the following parameters:
94 ColorScheme
96 See above.
97 OutputFormat
99 See above.
100 Prefix
102 Adds a prefix to the front of the method names. The calculation
103 methods are bound to the name prefix_method_name (the
104 specified prefix, an underscore, the calculation method's
105 name). Further, prefix is made an alias for prefix"_get".
106 Default: "color"
108 Please note that with perl's "use" and "import" statemehts,
110 omitting the list and specifying an empty list has different
111 meanings:
112 use Color::Calc; # import with default settings (see below)
114 use Color::Calc(); # don't import anything
116 Property "set"/"get" methods
118 These methods are inaccessible without a object reference, i.e. when
120 the functions have been "import"ed.
121 $cc->set_output_format( $format)
123 Changes the output format for an existing "Color::Calc" object.
124 Calculation methods
126 All calculation methods always accept the following formats for $color
128 or $color1/$color2:
129 · An arrayref pointing to an array with three elements in the range
131 0..255 corresponding to the red, green, and blue component.
132 · A list of three values in the range 0..255 corresponding to the
134 red, green, and blue component where the first value does not have
135 3 or a multiple of 3 digits (e.g. "('0128',128,128)").
136 · A string containing a hexadecimal RGB value like
138 "#RGB"/"#RRGGBB"/"#RRRGGGBBB"/..., or
139 "RGB"/"RRGGBB"/"RRRGGGBBB"/...
140 · A color name accepted by "Graphics::ColorNames". The interpretation
142 is controlled by the "ColorScheme" parameter.
143 · A "Graphics::ColorObject" reference.
145 The calculation methods can be either accessed through a "Color::Calc"
147 object reference (here: $cc) or through the method names imported by
148 "import" (here using the prefix color).
149 $cc->get($color) / color($color)
151 Returns $color as-is (but in the selected output format). This
152 function can be used for color format conversion/normalisation.
153 $cc->invert($color) / color_invert($color)
155 Returns the inverse of $color.
156 $cc->opposite($color) / color_opposite($color)
158 Returns a color that is on the opposite side of the color wheel but
159 roughly keeps the saturation and lightness.
160 $cc->bw($color) / color_bw($color)
162 $cc->grey($color) / color_grey($color)
163 $cc->gray($color) / color_gray($color)
164 Converts $color to greyscale.
165 $cc->round($color, $value_count) / color_round($color, $value_count)
167 Rounds each component to to the nearest number determined by
168 dividing the range 0..255 into $value_count+1 portions.
169 The default for $value_count is 6, yielding 6^3 = 216 colors.
171 Values that are one higher than divisors of 255 yield the best
172 results (e.g. 3+1, 5+1, 7+1, 9+1, 15+1, 17+1, ...).
173 $cc->safe($color) / color_safe($color)
175 Rounds each color component to a multiple of 0x33 (dec. 51) or to a
176 named color defined in the HTML 4.01 specification.
177 Historically, these colors have been known as web-safe colors. They
179 still provide a convenient color palette.
180 $cc->mix($color1, $color2 [, $alpha]) / color_mix($color1, $color2 [,
182 $alpha])
183 Returns a color that is the mixture of $color1 and $color2.
184 The optional $alpha parameter can be a value between 0.0 (use
186 $color1 only) and 1.0 (use $color2 only), the default is 0.5.
187 $cc->light($color [, $alpha]) / color_light($color [, $alpha])
189 Returns a lighter version of $color, i.e. returns
190 "mix($color,[255,255,255],$alpha)".
191 The optional $alpha parameter can be a value between 0.0 (use
193 $color only) and 1.0 (use [255,255,255] only), the default is 0.5.
194 $cc->dark($color [, $alpha]) / color_dark($color [, $alpha])
196 Returns a darker version of $color, i.e. returns
197 "mix($color,[0,0,0],$alpha)".
198 The optional $alpha parameter can be a value between 0.0 (use
200 $color only) and 1.0 (use [0,0,0] only), the default is 0.5.
201 $cc->contrast($color [, $cut]) / color_contrast($color [, $cut])
203 Returns a color that has the highest possible contrast to the input
204 color.
205 This is done by setting the red, green, and blue values to 0 if the
207 corresponding value in the input is above "($cut * 255)" and to 255
208 otherwise.
209 The default for $cut is .5, representing a cutoff between 127 and
211 128.
212 $cc->contrast_bw($color [, $cut]) / color_contrast_bw($color [, $cut])
214 Returns black or white, whichever has the higher contrast to
215 $color.
216 This is done by returning black if the grey value of $color is
218 above "($cut * 255)" and white otherwise.
219 The default for $cut is .5, representing a cutoff between 127 and
221 128.
222 $cc->blend($color [, $alpha]) / color_blend($color [, $alpha])
224 Returns a color that blends into the background, i.e. it returns
225 "mix($color,contrast($color),$alpha)".
226 The optional $alpha parameter can be a value between 0.0 (use
228 $color only) and 1.0 (use "contrast($color)" only), the default is
229 0.5.
230 The idea is that $color is the foreground color, so
232 "contrast($color)" is similar to the background color. Mixing them
233 returns a color somewhere between them.
234 You might want to use "mix($color, $background, $alpha)" instead if
236 you know the real background color.
237 $cc->blend_bw($color [, $alpha]) / color_blend_bw($color [, $alpha])
239 Returns a mix of $color and black or white, whichever has the
240 higher contrast to $color.
241 The optional $alpha parameter can be a value between 0.0 (use
243 $color only) and 1.0 (use black/white only), the default is 0.5.
244 Functions
246 The calculation methods are also available as functions. The output
248 format is selected through the function name.
249 These functions are deprecated as they do not allow selecting the
251 scheme of recognized color names, which defaults to
252 Graphics::ColorNames::X (and is incompatible with HTML's color names).
253 By default, i.e. when no list is specified with "use" or "import", all
255 of these functions are exported.
256 color, color_mix, ...
258 Use $Color::Calc::MODE as the output format. This is the default.
259 color_hex, color_mix_html, ...
261 Use "hex" as the output format.
262 color_html, color_mix_html, ...
264 Use "html" as the output format. Please note that the color names
265 recognized are still based on X's color names, which are
266 incompatible with HTML. You can't use the output of these functions
267 as input for other color_*_html functions.
268 See Color::Calc::WWW for an alternative that does not suffer from
270 this problem.
271 color_pdf, color_mix_pdf, ...
273 Use "pdf" as the output format.
274 color_object, color_mix_object, ...
276 Use "object" as the output format.
277
279 Graphics::ColorNames (required); Graphics::ColorObject (optional)
280
282 Claus Faerber <CFAERBER@cpan.org>
283
285 Copyright 2004-2010 Claus Faerber. All rights reserved.
286 This library is free software; you can redistribute it and/or modify it
288 under the same terms as Perl itself.
289perl v5.12.0 2010-02-10 Color::Calc(3)