1Graphics::Toolkit::ColoUrs(e3r)Contributed Perl DocumentGartaipohnics::Toolkit::Color(3)
2
6 Graphics::Toolkit::Color - color palette creation helper
7
9 my $red = Graphics::Toolkit::Color->new('red'); # create color object
10 say $red->add('blue')->name; # mix in RGB: 'magenta'
11 Graphics::Toolkit::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 in HSL
13 $red->rgb_gradient_to( '#0000FF', 10); # 10 colors from red to blue
14 $red->complementary( 3 ); # get fitting red green and blue
15
17 Read only color holding objects with no additional dependencies.
18 Create them in many different ways (see section CONSTRUCTOR). Access
19 its values via methods from section GETTER or measure differences and
20 create related color objects via methods listed under METHODS.
21 Humans access colors on hardware level (eye) in RGB, on cognition level
23 in HSL (brain) and on cultural level (language) with names. Having
24 easy access to all three and some color math should enable you to get
25 the color palette you desire quickly.
26
28 There are many options to create a color objects. In short you can
29 either use the name of a predefined constant or provide values in RGB
30 or HSL color space.
31 new( 'name' )
33 Get a color by providing a name from the X11, HTML (CSS) or SVG
34 standard or a Pantone report. UPPER or CamelCase will be normalized to
35 lower case and inserted underscore letters ('_') will be ignored as
36 perl does in numbers (1_000 == 1000). All available names are listed
37 under "NAMES" in Graphics::Toolkit::Color::Constant. (See also: "name")
38 my $color = Graphics::Toolkit::Color->new('Emerald');
40 my @names = Graphics::Toolkit::Color::Constant::all_names(); # select from these
41 new( 'scheme:color' )
43 Get a color by name from a specific scheme or standard as provided by
44 an external module Graphics::ColorNames::* , which has to be installed
45 separately. * is a placeholder for the pallet name, which might be:
46 Crayola, CSS, EmergyC, GrayScale, HTML, IE, Mozilla, Netscape, Pantone,
47 PantoneReport, SVG, VACCC, Werner, Windows, WWW or X. In ladder case
48 Graphics::ColorNames::X has to be installed. You can get them all at
49 once via Bundle::Graphics::ColorNames. The color name will be
50 normalized as above.
51 my $color = Graphics::Toolkit::Color->new('SVG:green');
53 my @s = Graphics::ColorNames::all_schemes(); # look up the installed
54 new( '#rgb' )
56 Color definitions in hexadecimal format as widely used in the web, are
57 also acceptable.
58 my $color = Graphics::Toolkit::Color->new('#FF0000');
60 my $color = Graphics::Toolkit::Color->new('#f00'); # works too
61 new( [$r, $g, $b] )
63 Triplet of integer RGB values ("red", "green" and "blue" : 0 .. 255).
64 Out of range values will be corrected to the closest value in range.
65 my $red = Graphics::Toolkit::Color->new( 255, 0, 0 );
67 my $red = Graphics::Toolkit::Color->new([255, 0, 0]); # does the same
68 new( {r => $r, g => $g, b => $b} )
70 Hash with the keys 'r', 'g' and 'b' does the same as shown in previous
71 paragraph, only more declarative. Casing of the keys will be normalised
72 and only the first letter of each key is significant.
73 my $red = Graphics::Toolkit::Color->new( r => 255, g => 0, b => 0 );
75 my $red = Graphics::Toolkit::Color->new({r => 255, g => 0, b => 0}); # works too
76 ... Color->new( Red => 255, Green => 0, Blue => 0); # also fine
77 new( {h => $h, s => $s, l => $l} )
79 To define a color in HSL space, with values for "hue", "saturation" and
80 "lightness", use the following keys, which will be normalized as
81 decribed in previous paragraph. Out of range values will be corrected
82 to the closest value in range. Since "hue" is a polar coordinate, it
83 will be rotated into range, e.g. 361 = 1.
84 my $red = Graphics::Toolkit::Color->new( h => 0, s => 100, l => 50 );
86 my $red = Graphics::Toolkit::Color->new({h => 0, s => 100, l => 50}); # good too
87 ... ->new( Hue => 0, Saturation => 100, Lightness => 50 ); # also fine
88 color
90 If writing
91 Graphics::Toolkit::Color->new( ...);
93 is too much typing for you or takes to much space, import the
95 subroutine "color", which takes all the same arguments as described
96 above.
97 use Graphics::Toolkit::Color qw/color/;
99 my $green = color('green');
100 my $darkblue = color([20, 20, 250]);
101
103 are read only methods - giving access to different parts of the objects
104 data.
105 name
107 String with normalized name (lower case without '_') of the color as in
108 X11 or HTML (SVG) standard or the Pantone report. The name will be
109 found and filled in, even when the object was created with RGB or HSL
110 values. If no color is found, "name" returns an empty string. All
111 names are at: "NAMES" in Graphics::Toolkit::Color::Constant (See als:
112 "new(-'name'-)")
113 string
115 String that can be serialized back into a color an object (recreated by
116 Graphics::Toolkit::Color->new( $string )). It is either the color
117 "name" (if color has one) or result of "rgb_hex".
118 red
120 Integer between 0 .. 255 describing the red portion in RGB space.
121 Higher value means more color and an lighter color.
122 green
124 Integer between 0 .. 255 describing the green portion in RGB space.
125 Higher value means more color and an lighter color.
126 blue
128 Integer between 0 .. 255 describing the blue portion in RGB space.
129 Higher value means more color and an lighter color.
130 hue
132 Integer between 0 .. 359 describing the angle (in degrees) of the
133 circular dimension in HSL space named hue. 0 approximates red, 30 -
134 orange, 60 - yellow, 120 - green, 180 - cyan, 240 - blue, 270 - violet,
135 300 - magenta, 330 - pink. 0 and 360 point to the same coordinate.
136 This module only outputs 0, even if accepting 360 as input.
137 saturation
139 Integer between 0 .. 100 describing percentage of saturation in HSL
140 space. 0 is grey and 100 the most colorful (except when lightness is 0
141 or 100).
142 lightness
144 Integer between 0 .. 100 describing percentage of lightness in HSL
145 space. 0 is always black, 100 is always white and 50 the most colorful
146 (depending on "hue" value) (or grey - if saturation = 0).
147 rgb
149 List (no ARRAY reference) with values of "red", "green" and "blue".
150 hsl
152 List (no ARRAY reference) with values of "hue", "saturation" and
153 "lightness".
154 rgb_hex
156 String starting with character '#', followed by six hexadecimal lower
157 case figures. Two digits for each of "red", "green" and "blue" value -
158 the format used in CSS (#rrggbb).
159 rgb_hash
161 Reference to a HASH containing the keys 'red', 'green' and 'blue' with
162 their respective values as defined above.
163 hsl_hash
165 Reference to a HASH containing the keys 'hue', 'saturation' and
166 'lightness' with their respective values as defined above.
167
169 create new, related color (objects) or compute similarity of colors
170 distance_to
172 A number that measures the distance (difference) between two colors: 1.
173 the calling object (C1) and 2. a provided first argument C2 - color
174 object or scalar data that is acceptable by new method : name or #hex
175 or [$r, $g, $b] or {...} (see chapter CONSTRUCTOR).
176 If no second argument is provided, than the difference is the Euclidean
178 distance in cylindric HSL space. If second argument is 'rgb' or 'RGB',
179 then its the Euclidean distance in RGB space. But als subspaces of both
180 are possible, as r, g, b, rg, rb, gb, h, s, l, hs, hl, and sl.
181 my $d = $blue->distance_to( 'lapisblue' ); # how close to lapis color?
183 # how different is my blue value to airy_blue
184 $d = $blue->distance_to( 'airyblue', 'Blue'); # same amount of blue?
185 $d = $color->distance_to( $c2, 'Hue' ); # same hue ?
186 $d = $color->distance_to( [10, 32, 112 ], 'rgb' );
187 $d = $color->distance_to( { Hue => 222, Sat => 23, Light => 12 } );
188 add
190 Create a Graphics::Toolkit::Color object, by adding any RGB or HSL
191 values to current color. (Same rules apply for key names as in new -
192 values can be negative.) RGB and HSL can be combined, but please note
193 that RGB are applied first.
194 If the first argument is a Graphics::Toolkit::Color object, than RGB
196 values will be added. In that case an optional second argument is a
197 factor (default = 1), by which the RGB values will be multiplied before
198 being added. Negative values of that factor lead to darkening of result
199 colors, but its not subtractive color mixing, since this module does
200 not support CMY color space. All RGB operations follow the logic of
201 additive mixing, and the result will be rounded (trimmed), to keep it
202 inside the defined RGB space.
203 my $blue = Graphics::Toolkit::Color->new('blue');
205 my $darkblue = $blue->add( Lightness => -25 );
206 my $blue2 = $blue->add( blue => 10 );
207 $blue->distance( $blue2 ); # == 0, can't get bluer than blue
208 my $color = $blue->add( $c2, -1.2 ); # subtract color c2 with factor 1.2
209 blend_with
211 Create Graphics::Toolkit::Color object, that is the average of two
212 colors in HSL space: 1. the calling object (C1) and 2. a provided
213 argument C2 (object or a refrence to data that is acceptable
214 definition).
215 The second argument is the blend ratio, which defaults to 0.5 ( 1:1 ).
217 0 represents here C1 and 1 C2. Numbers below 0 and above 1 are
218 possible, and will be applied, as long the result is inside the finite
219 HSL space. There is a slight overlap with the add method which mostly
220 operates in RGB (unless told so), while this method always operates in
221 HSL space.
222 my $c = $color->blend_with( Graphics::Toolkit::Color->new('silver') );
224 $color->blend_with( 'silver' ); # same thing
225 $color->blend_with( [192, 192, 192] ); # still same
226 my $difference = $color->blend_with( $c2, -1 );
227
229 rgb_gradient_to
230 Creates a gradient (a list of colors that build a transition) between
231 current (C1) and a second, given color (C2).
232 The first argument is C2. Either as an Graphics::Toolkit::Color object
234 or a scalar (name, hex or reference), which is acceptable to a
235 constructor.
236 Second argument is the number $n of colors, which make up the gradient
238 (including C1 and C2). It defaults to 3. These 3 colors C1, C2 and a
239 color in between, which is the same as the result of method blend_with.
240 Third argument is also a positive number $p, which defaults to one. It
242 defines the dynamics of the transition between the two colors. If $p
243 == 1 you get a linear transition - meaning the distance in RGB space is
244 equal from one color to the next. If $p != 1, the formula $n ** $p
245 starts to create a parabola function, which defines a none linear
246 mapping. For values $n > 1 the transition starts by sticking to C1 and
247 slowly getting faster and faster toward C2. Values $n < 1 do the
248 opposite: starting by moving fastest from C1 to C2 (big distances) and
249 becoming slower and slower.
250 my @colors = $c->rgb_gradient_to( $grey, 5 ); # we turn to grey
252 @colors = $c1->rgb_gradient_to( [14,10,222], 10, 3 ); # none linear gradient
253 hsl_gradient_to
255 Same as "rgb_gradient_to" (what you normally want), but in HSL space.
256 complementary
258 Creates a set of complementary colors. It accepts 3 numerical
259 arguments: n, delta_S and delta_L.
260 Imagine an horizontal circle in HSL space, whith a center in the (grey)
262 center column. The saturation and lightness of all colors on that
263 circle is the same, they differ only in hue. The color of the current
264 color object ($self a.k.a C1) lies on that circle as well as C2, which
265 is 180 degrees (half the circumference) apposed to C1.
266 This circle will be divided in $n (first argument) equal partitions,
268 creating $n equally distanced colors. All of them will be returned, as
269 objects, starting with C1. However, when $n is set to 1 (default), the
270 result is only C2, which is THE complementary color to C1.
271 The second argument moves C2 along the S axis (both directions), so
273 that the center of the circle is no longer in the HSL middle column and
274 the complementary colors differ in saturation. (C1 stays unmoved. )
275 The third argument moves C2 along the L axis (vertical), which gives
277 the circle a tilt, so that the complementary colors will differ in
278 lightness.
279 my @colors = $c->complementary( 3, +20, -10 );
281
283 • Color::Scheme
284 • Graphics::ColorUtils
286 • Color::Fade
288 • Graphics::Color
290 • Graphics::ColorObject
292 • Color::Calc
294 • Convert::Color
296 • Color::Similarity
298
300 Copyright 2022-2023 Herbert Breunung.
301 This program is free software; you can redistribute it and/or modify it
303 under same terms as Perl itself.
304
306 Herbert Breunung, <lichtkind@cpan.org>
307perl v5.38.0 2023-07-24 Graphics::Toolkit::Color(3)