1Color::Calc(3)        User Contributed Perl Documentation       Color::Calc(3)
2
3
4

NAME

6       Color::Calc - Simple calculations with RGB colors.
7

SYNOPSIS

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

DESCRIPTION

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
21   USAGE
22       Constructors
23
24       Color::Calc->new( ... )
25           This class method creates a new "Color::Calc" object.
26
27             use Color::Calc();
28             my $cc = new Color::Calc( 'ColorScheme' => 'X', OutputFormat => 'HTML' );
29             print $cc->invert( 'white' );
30
31           It accepts the following parameters:
32
33           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
41               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
46               Default: "X" (Note: This is incompatible with HTML color
47               names).
48
49           OutputFormat
50               One of the output formats defined by this module. Possible
51               values are:
52
53               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
58               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
62               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
67               obj (DEPRECATED) Returns a "Color::Object" reference. The
68                   module "Color::Object" must be installed, of course.
69
70               object
71                   Returns a "Graphics::ColorObject" reference. The module
72                   "Graphics::ColorObject" must be installed, of course.
73
74               pdf Returns a string compatible with "PDF::API2", i.e. #RRGGBB.
75
76               __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
81                     local $Color::Calc::MODE = 'html';
82
83               Default: "__MODEvar" (for compatibility)
84
85       Color::Calc->import( ... )
86           This method creates a new, hidden object and binds its methods to
87           the namespace of the calling module.
88
89           This method is usually not called directly but from perl's "use"
90           statement:
91
92             use Color::Calc(
93               'ColorScheme' => 'X',
94               'OutputFormat' => 'HTML',
95               'Prefix' => 'cc' );
96             print cc_invert( 'white' );   # prints 'black'
97
98           On import, you can specify the following parameters:
99
100           ColorScheme
101               See above.
102
103           OutputFormat
104               See above.
105
106           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
112               Default: "color"
113
114           Please note that with perl's "use" and "import" statemehts,
115           omitting the list and specifying an empty list has different
116           meanings:
117
118             use Color::Calc;      # import with default settings (see below)
119
120             use Color::Calc();    # don't import anything
121
122       Property "set"/"get" methods
123
124       These methods are inaccessible without a object reference, i.e. when
125       the functions have been "import"ed.
126
127       $cc->set_output_format( $format)
128           Changes the output format for an existing "Color::Calc" object.
129
130       Calculation methods
131
132       All calculation methods always accept the following formats for $color
133       or $color1/$color2:
134
135       •   An arrayref pointing to an array with three elements in the range
136           0..255 corresponding to the red, green, and blue component.
137
138       •   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
142       •   A string containing a hexadecimal RGB value like
143           "#RGB"/"#RRGGBB"/"#RRRGGGBBB"/..., or
144           "RGB"/"RRGGBB"/"RRRGGGBBB"/...
145
146       •   A color name accepted by "Graphics::ColorNames". The interpretation
147           is controlled by the "ColorScheme" parameter.
148
149       •   A "Graphics::ColorObject" reference.
150
151       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
155       $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
159       $cc->invert($color) / color_invert($color)
160           Returns the inverse of $color.
161
162       $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
166       $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
171       $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
175           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
179       $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
183           Historically, these colors have been known as web-safe colors. They
184           still provide a convenient color palette.
185
186       $cc->mix($color1, $color2 [, $alpha]) / color_mix($color1, $color2 [,
187       $alpha])
188           Returns a color that is the mixture of $color1 and $color2.
189
190           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
193       $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
197           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
200       $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
204           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
207       $cc->contrast($color [, $cut]) / color_contrast($color [, $cut])
208           Returns a color that has the highest possible contrast to the input
209           color.
210
211           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
215           The default for $cut is .5, representing a cutoff between 127 and
216           128.
217
218       $cc->contrast_bw($color [, $cut]) / color_contrast_bw($color [, $cut])
219           Returns black or white, whichever has the higher contrast to
220           $color.
221
222           This is done by returning black if the grey value of $color is
223           above "($cut * 255)" and white otherwise.
224
225           The default for $cut is .5, representing a cutoff between 127 and
226           128.
227
228       $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
232           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
236           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
240           You might want to use "mix($color, $background, $alpha)" instead if
241           you know the real background color.
242
243       $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
247           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
250       Functions
251
252       The calculation methods are also available as functions. The output
253       format is selected through the function name.
254
255       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
259       By default, i.e. when no list is specified with "use" or "import", all
260       of these functions are exported.
261
262       color, color_mix, ...
263           Use $Color::Calc::MODE as the output format. This is the default.
264
265       color_hex, color_mix_html, ...
266           Use "hex" as the output format.
267
268       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
274           See Color::Calc::WWW for an alternative that does not suffer from
275           this problem.
276
277       color_pdf, color_mix_pdf, ...
278           Use "pdf" as the output format.
279
280       color_object, color_mix_object, ...
281           Use "object" as the output format.
282

SEE ALSO

284       Graphics::ColorNames (required); Graphics::ColorObject (optional)
285

AUTHOR

287       Claus Färber <CFAERBER@cpan.org>
288

LICENSE

290       Copyright 2004-2010 Claus Färber. All rights reserved.
291
292       This library is free software; you can redistribute it and/or modify it
293       under the same terms as Perl itself.
294
295
296
297perl v5.38.0                      2023-07-20                    Color::Calc(3)
Impressum