1Chart::Color(3) User Contributed Perl Documentation Chart::Color(3)
2
6 Chart::Color - read only single color holding objects
7
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
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
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 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 my $color = Chart::Color->new('Emerald');
34 my @names = Chart::Color::Constant::all_names(); # select from these
35 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 my $color = Chart::Color->new('SVG:green');
44 my @s = Graphics::ColorNames::all_schemes(); # installed pallets
45 new( '#rgb' )
47 Color definitions in hexadecimal format as widely used in the web, are
48 also acceptable.
49 my $color = Chart::Color->new('#FF0000');
51 my $color = Chart::Color->new('#f00'); # works too
52 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 my $red = Chart::Color->new( 255, 0, 0 );
58 my $red = Chart::Color->new([255, 0, 0]); # does the same
59 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 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 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 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
81 are all read only methods - giving access to different parts of the
82 objects data.
83 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 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 red
97 Integer between 0 .. 255 describing the red portion in RGB space.
98 green
100 Integer between 0 .. 255 describing the green portion in RGB space.
101 blue
103 Integer between 0 .. 255 describing the blue portion in RGB space.
104 rgb
106 Three values of red, green and blue (see above).
107 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 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 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 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 hsl
130 Three values of hue, saturation and lightness (see above).
131
133 create new, related color (objects) or compute similarity of colors
134 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 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 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 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 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 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 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 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 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 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 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 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 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 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 complementary
216 Creates a set of complementary colors. It accepts 3 numerical
217 arguments: n, delta_S and delta_L.
218 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 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 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 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 my @colors = $c->complementary( 3, +20, -10 );
239
241 Copyright 2022 Herbert Breunung.
242 This program is free software; you can redistribute it and/or modify it
244 under same terms as Perl itself.
245
247 Herbert Breunung, <lichtkind@cpan.org>
248perl v5.36.0 2022-08-01 Chart::Color(3)