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 Unlike "Graphics::ColorNames", barewords are always interpreted
42 as a module name under "Graphics::ColorNames". If you really
43 want to use a filename like "foo", you have to write it as
44 "./foo".
45 Default: "X" (Note: This is incompatible with HTML color
47 names).
48 OutputFormat
50 One of the output formats defined by this module. Possible
51 values are:
52 tuple
54 Returns a list of three values in the range 0..255. The
55 first value is guaranteed to have a "length" that is not a
56 multiple of three.
57 hex Returns a hexadecimal RGB value as a scalar that contains a
59 string in the format RRGGBB and a number representing the
60 hexadecimal number 0xRRGGBB.
61 html
63 Returns a string compatible with W3C's HTML and CSS
64 specifications, i.e. #RRGGBB or one of the sixteen HTML
65 color names.
66 obj (DEPRECATED) Returns a "Color::Object" reference. The
68 module "Color::Object" must be installed, of course.
69 object
71 Returns a "Graphics::ColorObject" reference. The module
72 "Graphics::ColorObject" must be installed, of course.
73 pdf Returns a string compatible with "PDF::API2", i.e. #RRGGBB.
75 __MODEvar
77 (DEPRECATED) Uses the value of $Color::Calc::MODE to select
78 one of the above output formats. You should use "local"
79 when setting this variable:
80 local $Color::Calc::MODE = 'html';
82 Default: "__MODEvar" (for compatibility)
84 Color::Calc->import( ... )
86 This method creates a new, hidden object and binds its methods to
87 the namespace of the calling module.
88 This method is usually not called directly but from perl's "use"
90 statement:
91 use Color::Calc(
93 'ColorScheme' => 'X',
94 'OutputFormat' => 'HTML',
95 'Prefix' => 'cc' );
96 print cc_invert( 'white' ); # prints 'black'
97 On import, you can specify the following parameters:
99 ColorScheme
101 See above.
102 OutputFormat
104 See above.
105 Prefix
107 Adds a prefix to the front of the method names. The calculation
108 methods are bound to the name prefix_method_name (the
109 specified prefix, an underscore, the calculation method's
110 name). Further, prefix is made an alias for prefix"_get".
111 Default: "color"
113 Please note that with perl's "use" and "import" statemehts,
115 omitting the list and specifying an empty list has different
116 meanings:
117 use Color::Calc; # import with default settings (see below)
119 use Color::Calc(); # don't import anything
121 Property "set"/"get" methods
123 These methods are inaccessible without a object reference, i.e. when
125 the functions have been "import"ed.
126 $cc->set_output_format( $format)
128 Changes the output format for an existing "Color::Calc" object.
129 Calculation methods
131 All calculation methods always accept the following formats for $color
133 or $color1/$color2:
134 • An arrayref pointing to an array with three elements in the range
136 0..255 corresponding to the red, green, and blue component.
137 • A list of three values in the range 0..255 corresponding to the
139 red, green, and blue component where the first value does not have
140 3 or a multiple of 3 digits (e.g. "('0128',128,128)").
141 • A string containing a hexadecimal RGB value like
143 "#RGB"/"#RRGGBB"/"#RRRGGGBBB"/..., or
144 "RGB"/"RRGGBB"/"RRRGGGBBB"/...
145 • A color name accepted by "Graphics::ColorNames". The interpretation
147 is controlled by the "ColorScheme" parameter.
148 • A "Graphics::ColorObject" reference.
150 The calculation methods can be either accessed through a "Color::Calc"
152 object reference (here: $cc) or through the method names imported by
153 "import" (here using the prefix color).
154 $cc->get($color) / color($color)
156 Returns $color as-is (but in the selected output format). This
157 function can be used for color format conversion/normalisation.
158 $cc->invert($color) / color_invert($color)
160 Returns the inverse of $color.
161 $cc->opposite($color) / color_opposite($color)
163 Returns a color that is on the opposite side of the color wheel but
164 roughly keeps the saturation and lightness.
165 $cc->bw($color) / color_bw($color)
167 $cc->grey($color) / color_grey($color)
168 $cc->gray($color) / color_gray($color)
169 Converts $color to greyscale.
170 $cc->round($color, $value_count) / color_round($color, $value_count)
172 Rounds each component to to the nearest number determined by
173 dividing the range 0..255 into $value_count+1 portions.
174 The default for $value_count is 6, yielding 6^3 = 216 colors.
176 Values that are one higher than divisors of 255 yield the best
177 results (e.g. 3+1, 5+1, 7+1, 9+1, 15+1, 17+1, ...).
178 $cc->safe($color) / color_safe($color)
180 Rounds each color component to a multiple of 0x33 (dec. 51) or to a
181 named color defined in the HTML 4.01 specification.
182 Historically, these colors have been known as web-safe colors. They
184 still provide a convenient color palette.
185 $cc->mix($color1, $color2 [, $alpha]) / color_mix($color1, $color2 [,
187 $alpha])
188 Returns a color that is the mixture of $color1 and $color2.
189 The optional $alpha parameter can be a value between 0.0 (use
191 $color1 only) and 1.0 (use $color2 only), the default is 0.5.
192 $cc->light($color [, $alpha]) / color_light($color [, $alpha])
194 Returns a lighter version of $color, i.e. returns
195 "mix($color,[255,255,255],$alpha)".
196 The optional $alpha parameter can be a value between 0.0 (use
198 $color only) and 1.0 (use [255,255,255] only), the default is 0.5.
199 $cc->dark($color [, $alpha]) / color_dark($color [, $alpha])
201 Returns a darker version of $color, i.e. returns
202 "mix($color,[0,0,0],$alpha)".
203 The optional $alpha parameter can be a value between 0.0 (use
205 $color only) and 1.0 (use [0,0,0] only), the default is 0.5.
206 $cc->contrast($color [, $cut]) / color_contrast($color [, $cut])
208 Returns a color that has the highest possible contrast to the input
209 color.
210 This is done by setting the red, green, and blue values to 0 if the
212 corresponding value in the input is above "($cut * 255)" and to 255
213 otherwise.
214 The default for $cut is .5, representing a cutoff between 127 and
216 128.
217 $cc->contrast_bw($color [, $cut]) / color_contrast_bw($color [, $cut])
219 Returns black or white, whichever has the higher contrast to
220 $color.
221 This is done by returning black if the grey value of $color is
223 above "($cut * 255)" and white otherwise.
224 The default for $cut is .5, representing a cutoff between 127 and
226 128.
227 $cc->blend($color [, $alpha]) / color_blend($color [, $alpha])
229 Returns a color that blends into the background, i.e. it returns
230 "mix($color,contrast($color),$alpha)".
231 The optional $alpha parameter can be a value between 0.0 (use
233 $color only) and 1.0 (use contrast($color) only), the default is
234 0.5.
235 The idea is that $color is the foreground color, so
237 contrast($color) is similar to the background color. Mixing them
238 returns a color somewhere between them.
239 You might want to use "mix($color, $background, $alpha)" instead if
241 you know the real background color.
242 $cc->blend_bw($color [, $alpha]) / color_blend_bw($color [, $alpha])
244 Returns a mix of $color and black or white, whichever has the
245 higher contrast to $color.
246 The optional $alpha parameter can be a value between 0.0 (use
248 $color only) and 1.0 (use black/white only), the default is 0.5.
249 Functions
251 The calculation methods are also available as functions. The output
253 format is selected through the function name.
254 These functions are deprecated as they do not allow selecting the
256 scheme of recognized color names, which defaults to
257 Graphics::ColorNames::X (and is incompatible with HTML's color names).
258 By default, i.e. when no list is specified with "use" or "import", all
260 of these functions are exported.
261 color, color_mix, ...
263 Use $Color::Calc::MODE as the output format. This is the default.
264 color_hex, color_mix_html, ...
266 Use "hex" as the output format.
267 color_html, color_mix_html, ...
269 Use "html" as the output format. Please note that the color names
270 recognized are still based on X's color names, which are
271 incompatible with HTML. You can't use the output of these functions
272 as input for other color_*_html functions.
273 See Color::Calc::WWW for an alternative that does not suffer from
275 this problem.
276 color_pdf, color_mix_pdf, ...
278 Use "pdf" as the output format.
279 color_object, color_mix_object, ...
281 Use "object" as the output format.
282
284 Graphics::ColorNames (required); Graphics::ColorObject (optional)
285
287 Claus Färber <CFAERBER@cpan.org>
288
290 Copyright 2004-2010 Claus Färber. All rights reserved.
291 This library is free software; you can redistribute it and/or modify it
293 under the same terms as Perl itself.
294perl v5.38.0 2023-07-20 Color::Calc(3)