NAME Graphics::Toolkit::Color - color palette creation helper SYNOPSIS use Graphics::Toolkit::Color qw/color/; my $red = Graphics::Toolkit::Color->new('red'); # create color object say $red->add( 'blue' => 256 )->name; # mix in HSL: 'fuchsia' color( 0, 0, 255)->values('HSL'); # 240, 100, 50 = blue # mix blue with a little grey in HSL $blue->blend( with => {H=> 0, S=> 0, L=> 80}, pos => 0.1); $red->gradient( to => '#0000FF', steps => 10); # 10 colors from red to blue $red->complementary( 3 ); # get fitting red green and blue DESCRIPTION ATTENTION: deprecated methods of the old API will be removed on version 2.0. Graphics::Toolkit::Color, for short GTC, is the top level API of this module. It is designed to get fast access to a set of related colors, that serve your need. While it can understand and output many color formats, its primary (internal) format is RGB, because this it is about colors that can be shown on the screen. Humans access colors on hardware level (eye) in RGB, on cognition level in HSL (brain) and on cultural level (language) with names. Having easy access to all three and some color math should enable you to get the color palette you desire quickly. GTC are read only color holding objects with no additional dependencies. Create them in many different ways (see section *CONSTRUCTOR*). Access its values via methods from section *GETTER* or measure differences and create related color objects via methods listed under *METHODS*. CONSTRUCTOR There are many options to create a color objects. In short you can either use the name of a predefined constant or provide values in several "COLOR-SPACES" in Graphics::Toolkit::Color::Value new('name') Get a color by providing a name from the X11, HTML (CSS) or SVG standard or a Pantone report. UPPER or CamelCase will be normalized to lower case and inserted underscore letters ('_') will be ignored as perl does in numbers (1_000 == 1000). All available names are listed under "NAMES" in Graphics::Toolkit::Color::Name::Constant. (See also: "name") my $color = Graphics::Toolkit::Color->new('Emerald'); my @names = Graphics::Toolkit::Color::Name::all(); # select from these new('scheme:color') Get a color by name from a specific scheme or standard as provided by an external module Graphics::ColorNames::* , which has to be installed separately. * is a placeholder for the pallet name, which might be: Crayola, CSS, EmergyC, GrayScale, HTML, IE, Mozilla, Netscape, Pantone, PantoneReport, SVG, VACCC, Werner, Windows, WWW or X. In ladder case Graphics::ColorNames::X has to be installed. You can get them all at once via Bundle::Graphics::ColorNames. The color name will be normalized as above. my $color = Graphics::Toolkit::Color->new('SVG:green'); my @s = Graphics::ColorNames::all_schemes(); # look up the installed new( '#rgb' ) Color definitions in hexadecimal format as widely used in the web, are also acceptable. my $color = Graphics::Toolkit::Color->new('#FF0000'); my $color = Graphics::Toolkit::Color->new('#f00'); # works too new( [$r, $g, $b] ) Triplet of integer RGB values (red, green and blue : 0 .. 255). Out of range values will be corrected to the closest value in range. my $red = Graphics::Toolkit::Color->new( 255, 0, 0 ); my $red = Graphics::Toolkit::Color->new([255, 0, 0]); # does the same my $red = Graphics::Toolkit::Color->new('RGB' => 255, 0, 0); # named tuple syntax my $red = Graphics::Toolkit::Color->new(['RGB' => 255, 0, 0]); # named ARRAY The named array syntax of the last example works for nany supported space. new( {r => $r, g => $g, b => $b} ) Hash with the keys 'r', 'g' and 'b' does the same as shown in previous paragraph, only more declarative. Casing of the keys will be normalised and only the first letter of each key is significant. my $red = Graphics::Toolkit::Color->new( r => 255, g => 0, b => 0 ); my $red = Graphics::Toolkit::Color->new({r => 255, g => 0, b => 0}); # works too ... Color->new( Red => 255, Green => 0, Blue => 0); # also fine new( {h => $h, s => $s, l => $l} ) To define a color in HSL space, with values for "hue", "saturation" and "lightness", use the following keys, which will be normalized as decribed in previous paragraph. Out of range values will be corrected to the closest value in range. Since "hue" is a polar coordinate, it will be rotated into range, e.g. 361 = 1. my $red = Graphics::Toolkit::Color->new( h => 0, s => 100, l => 50 ); my $red = Graphics::Toolkit::Color->new({h => 0, s => 100, l => 50}); # good too ... ->new( Hue => 0, Saturation => 100, Lightness => 50 ); # also fine color If writing Graphics::Toolkit::Color->new( ...); is too much typing for you or takes to much space, import the subroutine "color", which takes all the same arguments as described above. use Graphics::Toolkit::Color qw/color/; my $green = color('green'); my $darkblue = color([20, 20, 250]); GETTER / ATTRIBUTES are read only methods - giving access to different parts of the objects data. name String with normalized name (lower case without *'_'*) of the color as in X11 or HTML (SVG) standard or the Pantone report. The name will be found and filled in, even when the object was created with RGB or HSL values. If no color is found, "name" returns an empty string. All names are at: "NAMES" in Graphics::Toolkit::Color::Constant (See als: "new(-'name'-)") string String that can be serialized back into a color an object (recreated by Graphics::Toolkit::Color->new( $string )). It is either the color "name" (if color has one) or result of "rgb_hex". values Returns the color values. First argument is the name of a color space: The options are: 'rgb' (default), hsl, cmyk and cmy. Second argument is the format. That can vary from space to space but generally available are "list" (default), "hash", "char_hash" and names or initials of the value names of that particular space. RGB also provides the option "hex" to get values like '#aabbcc'. say $color->values(); # get list of rgb : 0, 0, 255 say $blue->values('RGB', 'hash'); # { red => 0. green => 0, blue => 255} say $blue->values('RGB', 'char_hash'); # { r => 0. g => 0, b => 255} say $blue->values('RGB', 'hex'); # '#00FFFF' say $color->values('HSL', 'saturation'); # 100 hue DEPRECATED: Integer between 0 .. 359 describing the angle (in degrees) of the circular dimension in HSL space named hue. 0 approximates red, 30 - orange, 60 - yellow, 120 - green, 180 - cyan, 240 - blue, 270 - violet, 300 - magenta, 330 - pink. 0 and 360 point to the same coordinate. This module only outputs 0, even if accepting 360 as input. saturation DEPRECATED: Integer between 0 .. 100 describing percentage of saturation in HSL space. 0 is grey and 100 the most colorful (except when lightness is 0 or 100). lightness DEPRECATED: Integer between 0 .. 100 describing percentage of lightness in HSL space. 0 is always black, 100 is always white and 50 the most colorful (depending on "hue" value) (or grey - if saturation = 0). rgb DEPRECATED: List (no *ARRAY* reference) with values of "red", "green" and "blue". hsl DEPRECATED: List (no *ARRAY* reference) with values of "hue", "saturation" and "lightness". rgb_hex DEPRECATED: String starting with character '#', followed by six hexadecimal lower case figures. Two digits for each of "red", "green" and "blue" value - the format used in CSS (#rrggbb). rgb_hash DEPRECATED: Reference to a *HASH* containing the keys 'red', 'green' and 'blue' with their respective values as defined above. hsl_hash DEPRECATED: Reference to a *HASH* containing the keys 'hue', 'saturation' and 'lightness' with their respective values as defined above. COLOR RELATION METHODS create new, related color (objects) or compute similarity of colors distance A floating pointnumber that measures the distance (difference) between two colors (color of the calling object and C2, first argument). The *distance* is measured in HSL space unless told otherwise. It takes three arguments, only the first is required. 1. Second color (C2) in any scalar definition as *new* would accept (see chapter "CONSTRUCTOR"). 2. The color space the difference is measured in. (see "COLOR-SPACES" in Graphics::Toolkit::Color::Value) 3. The subspace as a string. For instance you want to ignore lightness in HSL, then you subspace would be *'hs'* (initials of the other two dimensions). If you want to observe only one dimension of a color space you can name is also fully (*Hue*). # how close is blue to lapis color? my $d = $blue->distance( to => 'lapisblue' ); # same amount of blue? $d = $blue->distance( to => 'airyblue', in => 'RGB', notice_only => 'Blue'); # same hue ? $d = $color->distance( to => $c2, in => 'HSL', notice_only => 'hue' ); # same command in hash syntax: $d = $color->distance( {to => $c2, in => 'HSL', notice_only => 'Hue' }); set Create a new object that differs in certain values defined in the arguments as a hash. $black->set( blue => 255 )->name; # blue, same as #0000ff $blue->set( saturation => 50 ); # pale blue, same as $blue->set( s => 50 ); add Create a Graphics::Toolkit::Color object, by adding any RGB or HSL values to current color. (Same rules apply for key names as in new - values can be negative.) RGB and HSL can be combined, but please note that RGB are applied first. If the first argument is a Graphics::Toolkit::Color object, than RGB values will be added. In that case an optional second argument is a factor (default = 1), by which the RGB values will be multiplied before being added. Negative values of that factor lead to darkening of result colors, but its not subtractive color mixing, since this module does not support CMY color space. All RGB operations follow the logic of additive mixing, and the result will be rounded (trimmed), to keep it inside the defined RGB space. my $blue = Graphics::Toolkit::Color->new('blue'); my $darkblue = $blue->add( Lightness => -25 ); my $blue2 = $blue->add( blue => 10 ); # this is bluer than blue blend Create a Graphics::Toolkit::Color object, that has the average values between the calling object (color 1 - C1) and another color (C2). It takes three named arguments, only the first is required. 1. The color C2 (scalar that is acceptable by the constructor: object, string, ARRAY, HASH). The name of the argument is *with* (color is blended with ...). 2. Blend position is a floating point number, which defaults to 0.5. (blending ratio of 1:1 ). 0 represents here C1 and 1 is pure C2. Numbers below 0 and above 1 are possible, butlikely to be trimmed to fit inside the color space. Name of the argument is *pos*. 3. Color space name (default is *HSL* - all can be seen unter "COLOR-SPACES" in Graphics::Toolkit::Color::Value). Name of the argument is *in*. # a little more silver than $color in the mix $color->blend( with => 'silver', pos => 0.6 ); $color->blend({ with => 'silver', pos => 0.6 }); # works too! $blue->blend( with => {H => 240, S =>100, L => 50}, in => 'RGB' ); # teal COLOR SET CREATION METHODS gradient Creates a gradient (a list of colors that build a transition) between current (C1) and a second, given color (C2) by named argument *to*. The only required argument you have to give under the name *to* is C2. Either as an Graphics::Toolkit::Color object or a scalar (name, hex, hash or reference), which is acceptable to a "constructor". This is the same behaviour as in "distance". An optional argument under the name *steps* is the number of colors, which make up the gradient (including C1 and C2). It defaults to 3. Negative numbers will berectified by "abs". These 3 color objects: C1, C2 and a color in between, which is the same as the result of method "blend". Another optional argument under the name *dynamic* is also a float number, which defaults to zero. It defines the position of weight of the transition between the two colors. If $dynamic == 0 you get a linear transition, meaning the "distance" between neighbouring colors in the gradient. If $dynamic > 0, the weight is moved toward C1 and vice versa. The greater $dynamic, the slower the color change is in the beginning of the gradient and faster at the end (C2). The last optional argument names *in* defines the color space the changes are computed in. It parallels the argument of the same name of the method "blend" and "distance". # we turn to grey my @colors = $c->gradient( to => $grey, steps => 5, in => 'RGB'); # none linear gradient in HSL space : @colors = $c1->gradient( to =>[14,10,222], steps => 10, dynamic => 3 ); complementary Creates a set of complementary colors. It accepts 3 numerical arguments: n, delta_S and delta_L. Imagine an horizontal circle in HSL space, whith a center in the (grey) center column. The saturation and lightness of all colors on that circle is the same, they differ only in hue. The color of the current color object ($self a.k.a C1) lies on that circle as well as C2, which is 180 degrees (half the circumference) apposed to C1. This circle will be divided in $n (first argument) equal partitions, creating $n equally distanced colors. All of them will be returned, as objects, starting with C1. However, when $n is set to 1 (default), the result is only C2, which is THE complementary color to C1. The second argument moves C2 along the S axis (both directions), so that the center of the circle is no longer in the HSL middle column and the complementary colors differ in saturation. (C1 stays unmoved. ) The third argument moves C2 along the L axis (vertical), which gives the circle a tilt, so that the complementary colors will differ in lightness. my @colors = $c->complementary( 3, +20, -10 ); SEE ALSO * Color::Scheme * Graphics::ColorUtils * Color::Fade * Graphics::Color * Graphics::ColorObject * Color::Calc * Convert::Color * Color::Similarity COPYRIGHT & LICENSE Copyright 2022-2023 Herbert Breunung. This program is free software; you can redistribute it and/or modify it under same terms as Perl itself. AUTHOR Herbert Breunung,