NAME
Graphics::Toolkit::Color - color palette creation helper
SYNOPSIS
my $red = Graphics::Toolkit::Color->new('red'); # create color object
say $red->add('blue')->name; # mix in RGB: 'magenta'
Graphics::Toolkit::Color->new( 0, 0, 255)->hsl; # 240, 100, 50 = blue
$blue->blend_with({H=> 0, S=> 0, L=> 80}, 0.1); # mix blue with a little grey in HSL
$red->rgb_gradient_to( '#0000FF', 10); # 10 colors from red to blue
$red->complementary( 3 ); # get fitting red green and blue
DESCRIPTION
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 create related color objects
via methods listed under *METHODS*.
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 predefined constant or provide values in RGB or
HSL color space.
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
Graphics::Toolkit::Color::Constant.
my $color = Graphics::Toolkit::Color->new('Emerald');
my @names = Graphics::Toolkit::Color::Constant::all_names(); # 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
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, b => 50 );
my $red = Graphics::Toolkit::Color->new({h => 0, s => 100, b => 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 name of the color in the X11 or HTML (SVG) standard or the
Pantone report. The name will be found and filled in, even when the
object is created with RGB or HSL values. If the color is not found in
any of the mentioned standards, it returns an empty string. All names
are at: "NAMES" in Graphics::Toolkit::Color::Constant
string
String that can be serialized back into a color object (recreated by
Graphics::Toolkit::Color->new( $string )). It is either the color "name"
(if color has one) or result of "rgb_hex".
red
Integer between 0 .. 255 describing the red portion in RGB space. Higher
value means more color and an lighter color.
green
Integer between 0 .. 255 describing the green portion in RGB space.
Higher value means more color and an lighter color.
blue
Integer between 0 .. 255 describing the blue portion in RGB space.
Higher value means more color and an lighter color.
hue
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
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
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
List (no *ARRAY* reference) with values of "red", "green" and "blue".
hsl
List (no *ARRAY* reference) with values of "hue", "saturation" and
"lightness".
rgb_hex
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
Reference to a *HASH* containing the keys 'red', 'green' and 'blue' with
their respective values as defined above.
hsl_hash
Reference to a *HASH* containing the keys 'hue', 'saturation' and
'lightness' with their respective values as defined above.
METHODS
create new, related color (objects) or compute similarity of colors
distance_to
A number that measures the distance (difference) between two colors: 1.
the calling object (C1) and 2. a provided first argument C2 - color
object or scalar data that is acceptable by new method : name or #hex or
[$r, $g, $b] or {...} (see chapter CONSTRUCTOR).
If no second argument is provided, than the difference is the Euclidean
distance in cylindric HSL space. If second argument is 'rgb' or 'RGB',
then its the Euclidean distance in RGB space. But als subspaces of both
are possible, as r, g, b, rg, rb, gb, h, s, l, hs, hl, and sl.
my $d = $blue->distance_to( 'lapisblue' ); # how close to lapis color?
# how different is my blue value to airy_blue
$d = $blue->distance_to( 'airyblue', 'Blue'); # same amount of blue?
$d = $color->distance_to( $c2, 'Hue' ); # same hue ?
$d = $color->distance_to( [10, 32, 112 ], 'rgb' );
$d = $color->distance_to( { Hue => 222, Sat => 23, Light => 12 } );
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 );
$blue->distance( $blue2 ); # == 0, can't get bluer than blue
my $color = $blue->add( $c2, -1.2 ); # subtract color c2 with factor 1.2
blend_with
Create Graphics::Toolkit::Color object, that is the average of two
colors in HSL space: 1. the calling object (C1) and 2. a provided
argument C2 (object or a refrence to data that is acceptable
definition).
The second argument is the blend ratio, which defaults to 0.5 ( 1:1 ). 0
represents here C1 and 1 C2. Numbers below 0 and above 1 are possible,
and will be applied, as long the result is inside the finite HSL space.
There is a slight overlap with the add method which mostly operates in
RGB (unless told so), while this method always operates in HSL space.
my $c = $color->blend_with( Graphics::Toolkit::Color->new('silver') );
$color->blend_with( 'silver' ); # same thing
$color->blend_with( [192, 192, 192] ); # still same
my $difference = $color->blend_with( $c2, -1 );
rgb_gradient_to
Creates a gradient (a list of colors that build a transition) between
current (C1) and a second, given color (C2).
The first argument is C2. Either as an Graphics::Toolkit::Color object
or a scalar (name, hex or reference), which is acceptable to a
constructor.
Second argument is the number $n of colors, which make up the gradient
(including C1 and C2). It defaults to 3. These 3 colors C1, C2 and a
color in between, which is the same as the result of method blend_with.
Third argument is also a positive number $p, which defaults to one. It
defines the dynamics of the transition between the two colors. If $p ==
1 you get a linear transition - meaning the distance in RGB space is
equal from one color to the next. If $p != 1, the formula $n ** $p
starts to create a parabola function, which defines a none linear
mapping. For values $n > 1 the transition starts by sticking to C1 and
slowly getting faster and faster toward C2. Values $n < 1 do the
opposite: starting by moving fastest from C1 to C2 (big distances) and
becoming slower and slower.
my @colors = $c->rgb_gradient_to( $grey, 5 ); # we turn to grey
@colors = $c1->rgb_gradient_to( [14,10,222], 10, 3 ); # none linear gradient
hsl_gradient_to
Same as "rgb_gradient_to" (what you normally want), but in HSL space.
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
* Color::Library
* Graphics::ColorUtils
* Graphics::ColorObject
* Color::Calc
* Convert::Color
* Color::Similarity
COPYRIGHT & LICENSE
Copyright 2022 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>