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

NAME

6       Chart::Color - read only single color holding objects
7

SYNOPSIS

9           my $red = Chart::Color->new('red');
10           say $red->add('blue')->name;              # magenta, mixed in RGB space
11           Chart::Color->new( 0, 0, 255)->hsl        # 240, 100, 50 = blue
12           $blue->blend_with({H=> 0, S=> 0, L=> 80}, 0.1);# mix blue with a little grey
13           $red->gradient( '#0000FF', 10);           # 10 colors from red to blue
14           $red->complementary( 3 );                 # get fitting red green and blue
15

DESCRIPTION

17       This module is designed for internal usage. It handles also all color
18       definitions done by users with method "$chart->set(color => {...})".
19       To see which formats are allowed there, read the next section and
20       please note that ->set() handles only scalar values.
21

CONSTRUCTOR

23       There are many options to create a color objects.  In short you can
24       either use the name of a predefined constant or provide values in RGB
25       or HSL color space.
26
27   new( 'name' )
28       Get a color by providing a name from the X11 or HTML (SVG) standard or
29       a Pantone report. Upper/Camel case will be treated as lower case and
30       inserted underscore letters ('_') will be ignored as perl does in
31       numbers (1_000 == 1000) (see more under Chart::Color::Constant).
32
33           my $color = Chart::Color->new('Emerald');
34           my @names = Chart::Color::Constant::all_names(); # select from these
35
36   new( 'standard:color' )
37       Get a color by name from a specific standard as provided by an external
38       module Graphics::ColorNames::* , which has to be installed separately.
39       * is a placeholder for the pallet name, which might be: Crayola, CSS,
40       EmergyC, GrayScale, HTML, IE, SVG, Werner, WWW or X. In ladder case
41       Graphics::ColorNames::X has to be installed.
42
43           my $color = Chart::Color->new('SVG:green');
44           my @s = Graphics::ColorNames::all_schemes();    # installed pallets
45
46   new( '#rgb' )
47       Color definitions in hexadecimal format as widely used in the web, are
48       also acceptable.
49
50           my $color = Chart::Color->new('#FF0000');
51           my $color = Chart::Color->new('#f00');   # works too
52
53   new( [$r, $g, $b] )
54       Triplet of integer RGB values ("red", "green" and "blue" : 0 .. 255).
55       Out of range values will be corrected to the closest value in range.
56
57           my $red = Chart::Color->new( 255, 0, 0 );
58           my $red = Chart::Color->new([255, 0, 0]); # does the same
59
60   new( {r => $r, g => $g, b => $b} )
61       Hash with the keys 'r', 'g' and 'b' does the same as previous
62       paragraph, only more declarative. Casing of the keys will be normalised
63       and only the first letter of each key is significant.
64
65           my $red = Chart::Color->new( r => 255, g => 0, b => 0 );
66           my $red = Chart::Color->new({r => 255, g => 0, b => 0}); # works too
67           ... Color->new( Red => 255, Green => 0, Blue => 0);      # also fine
68
69   new( {h => $h, s => $s, l => $l} )
70       To define a color in HSL space, with values for "hue", "saturation" and
71       "lightness", use the following keys, which will be normalized as
72       decribed in previous paragraph. Out of range values will be corrected
73       to the closest value in range. Since "hue" is a polar coordinate, it
74       will be rotated into range, e.g. 361 = 1.
75
76           my $red = Chart::Color->new( h =>   0, s => 100, b => 50 );
77           my $red = Chart::Color->new({h =>   0, s => 100, b => 50}); # good too
78           ... ->new( Hue => 0, Saturation => 100, Lightness => 50 ); # also fine
79

GETTER / ATTRIBUTES

81       are all read only methods - giving access to different parts of the
82       objects data.
83
84   name
85       Name of the color in the X11 or HTML (SVG) standard or the Pantone
86       report.  The name will be found and filled in, even when the object is
87       created with RGB or HSL values. If the color is not found in any of the
88       mentioned standards, it returns an empty string. All names are at:
89       "NAMES" in Chart::Color::Constant
90
91   string
92       String to reproduce color object by: Chart::Color->new (eval $string).
93       It is either the name (if color has one) or the stringified triplet: "[
94       $red, $green, $blue ]".
95
96   red
97       Integer between 0 .. 255 describing the red portion in RGB space.
98
99   green
100       Integer between 0 .. 255 describing the green portion in RGB space.
101
102   blue
103       Integer between 0 .. 255 describing the blue portion in RGB space.
104
105   rgb
106       Three values of red, green and blue (see above).
107
108   rgb_hex
109       String starting with '#', followed by six hexadecimal figures.  Two
110       digits for each of red, green and blue value - the format used in CSS.
111
112   hue
113       Integer between 0 .. 359 describing the angle (in degrees) of the
114       circular dimension in HSL space named hue.  0 approximates red, 30 -
115       orange, 60 - yellow, 120 - green, 180 - cyan, 240 - blue, 270 - violet,
116       300 - magenta, 330 - pink.  0 and 360 point to the same coordinate, but
117       this module only deals with 0.
118
119   saturation
120       Integer between 0 .. 100 describing percentage of saturation in HSL
121       space.  0 is grey and 100 the most colorful (except when lightness is 0
122       or 100).
123
124   lightness
125       Integer between 0 .. 100 describing percentage of lightness in HSL
126       space.  0 is always black, 100 is always white and 50 the most colorful
127       (depending on hue value) (or grey - if saturation = 0).
128
129   hsl
130       Three values of hue, saturation and lightness (see above).
131

METHODS

133       create new, related color (objects) or compute similarity of colors
134
135   distance_to
136       A number that measures the distance (difference) between two colors: 1.
137       the calling object (C1) and 2. a provided first argument C2 - color
138       object or scalar data that is acceptable by new method : name or #hex
139       or [$r, $g, $b] or {...} (see chapter CONSTRUCTOR).
140
141       If no second argument is provided, than the difference is the Euclidean
142       distance in cylindric HSL space. If second argument is 'rgb' or 'RGB',
143       then its the Euclidean distance in RGB space. But als subspaces of both
144       are possible, as r, g, b, rg, rb, gb, h, s, l, hs, hl, and sl.
145
146           my $d = $blue->distance_to( 'lapisblue' ); # how close to lapis color?
147           # how different is my blue value to airy_blue
148           $d = $blue->distance_to( 'airyblue', 'Blue'); # same amount of blue?
149           $d = $color->distance_to( $c2, 'Hue' ); # same hue ?
150           $d = $color->distance_to( [10, 32, 112 ], 'rgb' );
151           $d = $color->distance_to( { Hue => 222, Sat => 23, Light => 12 } );
152
153   add
154       Create a Chart::Color object, by adding any RGB or HSL values to
155       current color. (Same rules apply for key names as in new - values can
156       be negative.)  RGB and HSL can be combined, but please note that RGB
157       are applied first.
158
159       If the first argument is a Chart::Color object, than RGB values will be
160       added.  In that case an optional second argument is a factor (default =
161       1), by which the RGB values will be multiplied before being added.
162       Negative values of that factor lead to darkening of result colors, but
163       its not subtractive color mixing, since this module does not support
164       CMY color space. All RGB operations follow the logic of additive
165       mixing, and the result will be rounded (trimmed), to keep it inside the
166       defined RGB space.
167
168           my $blue = Chart::Color->new('blue');
169           my $darkblue = $blue->add( Lightness => -25 );
170           my $blue2 = $blue->add( blue => 10 );
171           $blue->distance( $blue2 );           # == 0, can't get bluer than blue
172           my $color = $blue->add( $c2, -1.2 ); # subtract color c2 with factor 1.2
173
174   blend_with
175       Create Chart::Color object, that is the average of two colors in HSL
176       space: 1. the calling object (C1) and 2. a provided argument C2 (object
177       or a refrence to data that is acceptable definition).
178
179       The second argument is the blend ratio, which defaults to 0.5 ( 1:1 ).
180       0 represents here C1 and 1 C2. Numbers below 0 and above 1 are
181       possible, and will be applied, as long the result is inside the finite
182       HSL space.  There is a slight overlap with the add method which mostly
183       operates in RGB (unless told so), while this method always operates in
184       HSL space.
185
186           my $c = $color->blend_with( Chart::Color->new('silver') );
187           $color->blend_with( 'silver' );                        # same thing
188           $color->blend_with( [192, 192, 192] );                 # still same
189           my $difference = $color->blend_with( $c2, -1 );
190
191   gradient_to
192       Creates a gradient (a list of colors that build a transition) between
193       current (C1) and a second, given color (C2).
194
195       The first argument is C2. Either as an Chart::Color object or a scalar
196       (name, hex or reference), which is acceptable to the method new.
197
198       Second argument is the number $n of colors, which make up the gradient
199       (including C1 and C2). It defaults to 3. These 3 colors C1, C2 and a
200       color in between, which is the same as the result of method blend_with.
201
202       Third argument is also a positive number $p, which defaults to one.  It
203       defines the dynamics of the transition between the two colors.  If $p
204       == 1 you get a linear transition - meaning the distance in HSL space
205       (distance_hsl) is equal from one color to the next. If $p != 1, the
206       formula $n ** $p starts to create a parabola function, which defines a
207       none linear mapping. For values $n > 1 the transition starts by
208       sticking to C1 and slowly getting faster and faster toward C2. Values
209       $n < 1 do the opposite: starting by moving fastest from C1 to C2 (big
210       distances) and becoming slower and slower.
211
212           my @colors = $c->gradient_to( $grey, 5 );         # we turn to grey
213           @colors = $c1->gradient_to( [14,10,222], 10, 3 ); # none linear gradient
214
215   complementary
216       Creates a set of complementary colors.  It accepts 3 numerical
217       arguments: n, delta_S and delta_L.
218
219       Imagine an horizontal circle in HSL space, whith a center in the (grey)
220       center column. The saturation and lightness of all colors on that
221       circle is the same, they differ only in hue. The color of the current
222       color object ($self a.k.a C1) lies on that circle as well as C2, which
223       is 180 degrees (half the circumference) apposed to C1.
224
225       This circle will be divided in $n (first argument) equal partitions,
226       creating $n equally distanced colors. All of them will be returned, as
227       objects, starting with C1. However, when $n is set to 1 (default), the
228       result is only C2, which is THE complementary color to C1.
229
230       The second argument moves C2 along the S axis (both directions), so
231       that the center of the circle is no longer in the HSL middle column and
232       the complementary colors differ in saturation. (C1 stays unmoved. )
233
234       The third argument moves C2 along the L axis (vertical), which gives
235       the circle a tilt, so that the complementary colors will differ in
236       lightness.
237
238           my @colors = $c->complementary( 3, +20, -10 );
239
241       Copyright 2022 Herbert Breunung.
242
243       This program is free software; you can redistribute it and/or modify it
244       under same terms as Perl itself.
245

AUTHOR

247       Herbert Breunung, <lichtkind@cpan.org>
248
249
250
251perl v5.36.0                      2022-08-01                   Chart::Color(3)
Impressum