Provided by: libgraphics-toolkit-color-perl_1.71-1_all 
NAME
Graphics::Toolkit::Color - color palette constructor
SYNOPSIS
use Graphics::Toolkit::Color qw/color/;
my $red = Graphics::Toolkit::Color->new('red'); # create color object
say $red->add( 'blue' => 255 )->name; # add blue value: 'fuchsia'
my $blue = color( 0, 0, 255)->values('HSL'); # 240, 100, 50 = blue
$blue->blend( with => [HSL => 0,0,80], pos => 0.1);# mix blue with a little grey in HSL
$red->gradient( to => '#0000FF', steps => 10); # 10 colors from red to blue
$red->complement( 3 ); # get fitting red green and blue
DESCRIPTION
ATTENTION: deprecated methods of the old API ( string, rgb, red, green, blue, rgb_hex,
rgb_hash, hsl, hue, saturation, lightness, hsl_hash, blend_with, gradient_to,
rgb_gradient_to, hsl_gradient_to, complementary) will be removed on version 2.0.
Graphics::Toolkit::Color, for short GTC, is the top level API of this module and the only
one a regular user should be concerned with. Its main purpose is the creation of sets of
related colors, such as gradients, complements and others.
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". Measure differences with the distance method. "SINGLE-COLOR" methods
create one a object that is related to the current one and "COLOR-SETS" methods will
create a host of color that are not only related to the current color but also have
relations between each other.
While this module can understand and output color values in many spaces, such as YIQ, HSL
and many more, RGB is the (internal) primal one, because GTC is about colors that can be
shown on the screen, and these are usually encoded in RGB.
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.
CONSTRUCTOR
There are many options to create a color objects. In short you can either use the name of
a constant or provide values in one of several "COLOR-SPACES" in
Graphics::Toolkit::Color::Space::Hub, which also can be formatted in many ways as
described in this paragraph.
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, as any here following, work for any supported
color 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
... ->new( Red => 255, Green => 0, Blue => 0); # also fine
... ->new( Hue => 0, Saturation => 100, Lightness => 50 ); # same color
... ->new( Hue => 0, whiteness => 0, blackness => 0 ); # still the same
new('rgb: $r, $g, $b')
String format (good for serialisation) that maximizes readability.
my $red = Graphics::Toolkit::Color->new( 'rgb: 255, 0, 0' );
my $blue = Graphics::Toolkit::Color->new( 'HSV: 240, 100, 100' );
new('rgb($r,$g,$b)')
Variant of string format that is supported by CSS.
my $red = Graphics::Toolkit::Color->new( 'rgb(255, 0, 0)' );
my $blue = Graphics::Toolkit::Color->new( 'hsv(240, 100, 100)' );
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
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 numerical values. If no color is found, "name" returns an empty
string. All names are at: "NAMES" in Graphics::Toolkit::Color::Name::Constant (See als:
"new('name')")
values
Returns the values of the color in given color space and format. It accepts three named,
optional arguments.
First argument is the name of a color space (named argument "in"). All options are under:
"COLOR-SPACES" in Graphics::Toolkit::Color::Space::Hub The order of named arguments is of
course chosen by the user, but I call it the first (most important) argument, because if
you give the method only one value, it is assumed to be the color space.
Second argument is the format (name: "as"). In short any SCALAR format acceptable to the
"CONSTRUCTOR" can also be reproduced by a getter method and the numerical cases by this
one. Not all formats are available under all color spaces, but the always present options
are: "list" (default), "hash", "char_hash" and "array".
Third named argument is the range inside which the numerical values have to be. RGB are
normally between 0 .. 255 and CMYK between 0 .. 1 ('normal'). Only a range of 1 a.k.a.
'normal' displays decimals. There are three syntax option to set the ranges. One value
will be understood as upper limit of all dimensions and zero being the lower one. If you
want to set the upper limits of all dimensions separately, you have to deliver an ARRAY
ref with the 3 or 4 upper limits. To also define the lower boundary, you replace the
number with an ARRAY ref containing the lower and then the upper limit.
$blue->values(); # get list in RGB: 0, 0, 255
$blue->values( in => 'RGB', as => 'list'); # same call
$blue->values( in => 'RGB', as => 'hash'); # { red => 0, green => 0, blue => 255}
$blue->values( in => 'RGB', as => 'char_hash');# { r => 0, g => 0, b => 255}
$blue->values( in => 'RGB', as => 'hex'); # '#00FFFF'
$color->values('HSL'); # 240, 100, 50
$color->values( in => 'HSL', range => 1); # 0.6666, 1, 0.5
$color->values( in => 'RGB', range => 2**16); # values in RGB16
$color->values( in => 'HSB', as => 'hash')->{'hue'}; # how to get single values
($color->values( 'HSB'))[0]; # same, but shorter
distance
Is a floating point number that measures the Euclidean distance between two colors. One
color is the calling object itself and the second (C2) has to provided as a named argument
(to), which is the only required one. It ca come in the form of a second GTC object or
any scalar color definition new would accept. The distance is measured in HSL color space
unless told otherwise by the argument in. The third argument is named metric. It's useful
if you want to notice only certain dimensions. Metric is the long or short name of that
dimension or the short names of several dimensions. They all have to come from one color
space and one shortcut letter can be used several times to heighten the weight of this
dimension. The last argument in named range and is a range definition, unless you don't
want to compute the distance with the default ranges of the selected color space.
my $d = $blue->distance( to => 'lapisblue' ); # how close is blue to lapis color?
$d = $blue->distance( to => 'airyblue', in => 'RGB', select => 'Blue'); # same amount of blue?
$d = $color->distance( to => $c2, in => 'HSL', select => 'hue' ); # same hue?
# compute distance when with all value ranges 0 .. 1
$d = $color->distance( to => $c2, in => 'HSL', select => 'hue', range => 'normal' );
SINGLE COLOR
construct colors that are related to the current object.
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 (clamped), 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 clamped 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::Space::Hub). 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 SETS
construct many interrelated color objects at once.
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 ARRAY), which is
acceptable to a "CONSTRUCTOR". This is the same behaviour as in "distance".
An optional argument under the name steps sets the number of colors, which make up the
gradient (including C1 and C2). It defaults to 3. Negative numbers will be rectified 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 a float number, that defines the
position of weight in the color transition from C1 to C2. It defaults to zero which gives
you a linear transition, meaning the "distance" between neighbouring colors in the
gradient is equal. 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 the
faster at the end (C2).
The last optional argument named in defines the color space the changes are computed in.
It parallels the argument of the same name from 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 );
complement
Creates a set of complementary colors, which will be computed in HSL color space. It
accepts 4 optional, named arguments. Complementary colors have a different hue value but
same saturation and lightness. Because they form a circle in HSL, they will be called in
this paragraph a circle.
If you provide no names (just a single argument), the value is understood as steps. steps
is the amount (count) of complementary colors, which defaults to 1 (giving you then THE
complementary color). If more than one color is requested, the result will contain the
calling object as the first color.
The second optional argument is hue_tilt, in short h, which defaults to zero. When zero,
the hue distance between all resulting colors on the circle is the same. When not zero,
the hue_tilt gets added (see "add") to THE complementary color. The so computed color
divides the circle in a shorter and longer part. Both of these parts will now contain an
equal amount of result colors. The distribution will be computed in a way, that there will
be a place on the circle where the distance between colors is the highest (let's call it
Dmax) and one where it is the lowest (Dmin). The distance between two colors increases or
decreases steadily. When hue_tilt is zero, the axis through Dmax and Dmin and the axis
through $self and C2 are orthogonal.
The third optional argument saturation_tilt, or short s, which also defaults to zero. If
the value differs from zero it gets added the color on Dmax (last paragraph), subtracted
on Dmin, changed accordingly in between, so that the circle gets moved in direction Dmin.
If you want to move the circle in any other direction you have to give saturation_tilt a
HASH reference with 2 keys. First is saturation or s, which is the value as described.
Secondly hue or h rotates the direction in which the circle will be moved. Please not,
this will not change the position of Dmin and Dmax, because it just defines the angle
between the Dmin-Dmax axis and the direction where the circle is moved.
The fourth optional argument is lightness_tilt or lm which works analogously to
saturation_tilt. Only difference is that it tilts the circle in the up-down direction,
which is in HSL color space lightness.
my @colors = $c->complement( 4 ); # $self + 3 compementary (square) colors
my @colors = $c->complement( steps => 3, s => 20, l => -10 );
my @colors = $c->complement( steps => 3, hue_tilt => -40,
saturation_tilt => {saturation => 300, hue => -50},
lightness_tilt => {l => -10, hue => 30} );
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, <lichtkind@cpan.org>