Graphic...::Color(3)

📦

version 1.972 · 7 versions

1.972 · fedora 44 (latest)
1.710.0 · opensuse-leap 16.0
2.22 · arch rolling
1.71 · fedora 43
1.08 · debian bookworm
1.97.2 · ubuntu resolute, ubuntu stonking
1.71 · debian trixie, ubuntu noble, ubuntu questing

💖 Graphics::Toolkit::Color — the manual, bestie edition 💖

okay so this is the user-contributed Perl documentation for Graphics::Toolkit::Color(3) and honestly? it's giving main character energy. grab a strawberry 🍓, sit down, and let's get into it.

✨ NAME ✨

Graphics::Toolkit::Color — calculate color (sets), IO many spaces and formats

like. it does color math AND it speaks every color language. obsessed.

🌈 SYNOPSIS 🌈

use Graphics::Toolkit::Color qw/color/;

my $red = Graphics::Toolkit::Color->new('red');  # create color object
say $red->add_value( 'blue' => 255 )->name;      # red + blue = 'magenta'
my @blue = color( 0, 0, 255)->values('HSL');     # 240, 100, 50 = blue
$red->mix( to => [HSL => 0,0,80], amount => 10); # mix red with a little grey
$red->gradient( to => '#0000FF', steps => 10);   # 10 colors from red to blue
my @base_triadic = $red->complement( 3 );        # get fitting red green and blue
my @reds = $red->cluster( radius => 4, distance => 1 );

look at that. seven lines and you've already built a whole palette. slay.

💀 DEPRECATION WARNING 💀

bestie. listen. The methods of the old API — and I'm talking string, rgb, red, green, blue, rgb_hex, rgb_hash, hsl, hue, saturation, lightness, hsl_hash, add, set, blend, blend_with, gradient_to, rgb_gradient_to, hsl_gradient_to, complementary — will be removed with release of version 2.0.

so if you're still calling these, it's giving "living in the past" and not in a cute vintage way. migrate, babe. 🙈

🦋 DESCRIPTION 🦋

Graphics::Toolkit::Color, for short GTC, is the top level API of this release and the only package a regular user should be concerned with. Its whole thing is the creation of related colors or sets of them — gradients, complements, that kind of iconic lineup. But you can also use it to convert and/or reformat color definitions. versatile queen. 👑

GTC are read only, one color representing objects with no additional dependencies. Create them in many different ways (see "CONSTRUCTOR"). Access its values via methods from section "GETTER". Measure differences with the distance method. "SINGLE-COLOR" methods create one new object that is related to the current one, and "COLOR-SETS" methods will create a group of colors that are not only related to the current color but also have relations between each other. Error messages will appear as return values instead of the expected result — so if something's off, it just hands you the error instead of the color. no drama, just data. 💅

While this module can understand and output color values to many color spaces, 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 of those plus some color math and many formats should enable you to get the color palette you desire quickly. literally the whole pipeline from eyeball to brain to vibes. 🧠✨

🎀 CONSTRUCTOR 🎀

There are many options to create a color object. In short you can either use the name of a constant (see "name") or provide values, which are coordinates in one of several color spaces. The latter are also understood in many formats. From now on any input that the constructor method new accepts, is called a color definition.

💖 new({ r => $r, g => $g, b => $b })

Most clear, flexible and longest input format: a hash with long or short axis names as keys with fitting values. This can be red, green and blue or r, g and b or names from any other color space. Upper or lower case doesn't matter. case-insensitive icon behavior. 🌸

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( [$r, $g, $b] )

takes a triplet of integer RGB values (red, green and blue : 0 .. 255). They can, but don't have to be put into an ARRAY reference (square brackets). If you want to define a color by values from another color space, you have to prepend the values with the name of a supported color space. Out of range values will be corrected (clamped). so if you go wild with the numbers, it gently pulls you back. 🫶

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 ARRAY syntax
my $red = Graphics::Toolkit::Color->new(  RGB => 255, 0, 0 ); # with fat comma
my $red = Graphics::Toolkit::Color->new([ RGB => 255, 0, 0]); # and brackets
my $red = Graphics::Toolkit::Color->new(  RGB =>[255, 0, 0]); # separate name and values
my $red = Graphics::Toolkit::Color->new(  YUV =>.299,-0.168736, .5); # same color in YUV

✨ new('rgb($r,$g,$b)')

String format that is supported by CSS (css_string format): it starts with the case insensitive color space name (lower case is default), followed by the (optionally with) comma separated values in round braces. The value suffixes that are defined by the color space ('%' in case of HSV) are optional. so chill of it.

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')

String format named named_string (good for serialisation) that maximizes readability. for when you want your color to be readable by humans AND by perl. 👑

my $red = Graphics::Toolkit::Color->new( 'rgb: 255, 0, 0' );
my $blue = Graphics::Toolkit::Color->new( 'HSV: 240, 100, 100' );

💅 new('#rgb')

Color definitions in hexadecimal format as widely used in the web, are also acceptable (RGB only). the classic. the moment. the format.

my $color = Graphics::Toolkit::Color->new('#FF0000');
my $color = Graphics::Toolkit::Color->new('#f00');    # short works too

🎀 new('name')

Get a color object by providing a name from the X11, HTML (CSS) or SVG scheme 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 here.

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 or with Bundle::Graphics::ColorNames. See all scheme names here. The color name will be normalized as above.

my $color = Graphics::Toolkit::Color->new('SVG:green');
my @schemes = Graphics::ColorNames::all_schemes();      # look up the installed

💜 color

If writing

Graphics::Toolkit::Color->new( ...);

is too much typing work for you or takes up to much space in the code file, import the subroutine color, which accepts all the same arguments as new. shorter. cuter. same energy. 🫶

use Graphics::Toolkit::Color qw/color/;
my $green = color('green');
my $darkblue = color([20, 20, 250]);

okay bestie, that's part one and we are NOT done yet. more sections incoming. stay seated. 💖

🫶 GETTER 🫶

giving you access to all the different parts of the object's data, bestie. it's giving open the hood and look inside energy.

✨ values ✨

Returns the numeric values of the color, held by the object. The method accepts five optional, named arguments: in (color space), as (format), range, precision and suffix. In most cases, only the first one is needed. periodt.

When given no arguments, the method returns a list with the integer values: red, green and blue in 0 .. 255 range, since RGB is the default color space of this module. slay.

If one positional argument is provided, the values get converted into the color space of the given name. The same is done when using the named argument in (full explanation behind the link). The named argument range is also explained in its own section. Please note you have to use the range argument only, if you like to deviate from the value ranges defined by the chosen color space.

The maybe most characteristic argument for this method is as, which enables all the same formats the constructor method new accepts. GTC is built with the design principle of total serialisation. This means: every constructor input format can be reproduced by a getter method and vice versa. These formats are: list (default), named_array, hash, char_hash, named_string, css_string, array (RGB only) and hex_string (RGB only). The remaining two — name and full:name — are produced by the method name. Format names are case insensitive. For more explanations, please see: formats section in GTC::Space::Hub.

precision is a more exotic argument, but sometimes you need to escape the numeric precision, set by a color space's definition. For instance LAB values will have maximally three decimals, no matter how precise the input was. In case you prefer 4 decimals, just use precision => 4. A zero means no decimals and -1 stands for maximal precision — which can spit out more decimals than you prefer. Different precisions per axis are possible via an ARRAY ref: precision => [1,2,3].

In the same way you can attach a little string per value by using the suffix argument. Normally these are percentage signs, but in some spaces where they appear by default you can suppress them by adding suffix => ''.

$blue->values();                                    # 0, 0, 255
$blue->values( in => 'RGB', as => 'list');          # 0, 0, 255 # explicit arguments
$blue->values(              as => 'array');         # [0, 0, 255] - RGB only
$blue->values( in => 'RGB', as => 'named_array');   # ['RGB', 0, 0, 255]
$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 => 'named_string');  # 'rgb: 0, 0, 255'
$blue->values( in => 'RGB', as => 'css_string');    # 'rgb( 0, 0, 255)'
$blue->values(              as => 'hex_string');    # '#0000ff' - RGB only
$blue->values(           range => 2**16 );          # 0, 0, 65536
$blue->values('HSL');                               # 240, 100, 50
$blue->values( in => 'HSL',suffix => ['', '%','%']);# 240, '100%', '50%'
$blue->values( in => 'HSB',  as => 'hash')->{'hue'};# 240
($blue->values( 'HSB'))[0];                          # 240
$blue->values( in => 'XYZ', range => 1, precision => 2);# normalized, 2 decimals max.

🌸 name 🌸

Returns the normalized name string (lower case, without _) that represents the RGB values of this color in the default color scheme, which is X11 + HTML (SVG) + Pantone report (see all names). These are the same ones which can be used with new('name').

Alternatively you may provide named arguments or one positional argument, which is the same as the named argument from. That requires a name of a color scheme, as listed here. You also can submit a list thereof inside an ARRAY ref which also dictates the order of the resulting color names. Please note that all color schemes, except the default one, depend on external modules, which have to be installed separately or via Bundle::Graphics::ColorNames. If you try to use a scheme from a not installed module you will get an error message instead of a color name. You can also create your custom color naming scheme via Graphics::Toolkit::Color::Name::Scheme.

The second named argument is all, which needs to be a perly boolean. It defaults to false. But if set to 1, you will get a list of all names that are associated with the current values. There will be no duplicates, when several schemes are searched. iconic.

A third named argument is full — also needing a perly boolean that defaults to false. When set true (1), the schema name becomes part of the returned color name as in 'SVG:red'. These full names are also accepted by the constructor.

The fourth named argument is distance, which means the same thing as in distance and it defaults to zero. It is most useful in combination with all to get all color names that are within a certain distance.

$blue->name();                                   # 'blue'
$blue->name('SVG');                              # 'blue'
$blue->name( from => [qw/CSS X/], all => 1);     # 'blue', 'blue1'
$blue->name( from => 'CSS', full => 1);          # 'CSS:blue'
$blue->name( distance => 3, all => 1) ;          # all names within the distance

🦋 closest_name 🦋

Returns in scalar context a color name, which has the shortest distance in RGB into the current color. In list context, you get additionally the just mentioned distance as a second return value. This method works almost identically as method name, but guarantees a non-empty result, unless invoking an unusually empty color scheme.

All arguments work as mentioned above, only here there is no distance argument. The only difference is (due to the second return value), multiple names (when requested) have to come in the form of an ARRAY as the first return value.

my $name = $red_like->closest_name;              # closest name in default scheme
my $name = $red_like->closest_name('HTML');      # closest HTML constant
($red_name, $distance) = $red_like->closest_name( from => 'Pantone', all => 1 );

💅 distance 💅

Is a floating point number that measures the Euclidean distance between two colors, which represent two points in a color space. One color is the calling object itself and the second one has to be provided as either the only argument or the named argument to, which is the only required one.

The distance is measured in RGB color space unless told otherwise by the argument in. Please use the OKLAB or CIELUV space, if you are interested in getting a result that matches the human perception.

The third argument is named select. It's useful if you want to regard only certain dimensions (axis — long and short axis names are accepted). For instance if you want to know only the difference in brightness between two colors, you type select => 'lightness' or select => 'l'. This naturally works only if you did also choose HSL as a color space or something similar that has a lightness axis like LAB or OKLAB. The select argument accepts a string or an ARRAY with several axis names, which can also repeat. For instance there is a formula to compute distances in RGB that weights the squared value deltas: $distance = sqrt( 3 * delta_red**2 + 4 * delta_green**2 + 2 * delta_blue**2 ). You can recreate that formula by typing select => [qw/ r r r g g g g b b/].

The last argument is named range, which can change the result drastically.

my $d = $blue->distance( 'lapisblue' );                 # how close is blue to lapis?
$d = $blue->distance( to => 'airyblue', select => 'b'); # have they the same amount of blue?
$d = $color->distance( to => $c2, in => 'HSL', select => 'hue' );  # same hue?
$d = $color->distance( to => $c2, range => 'normal' );  # distance with values in 0 .. 1 range
$d = $color->distance( to => $c2, select => [qw/r g b b/]); # double the weight of blue value differences

🌈 SINGLE COLOR 🌈

okay so these methods all hand you back a brand new color object that's related to the one you called them on (the invocant, bestie). and like — you might be sitting there expecting set_value to just mutate the invocant's values, but nope! GTC objects are, as we already said back in the DESCRIPTION, read only. and honestly? that's a feature. it means you get a whole functional programming vibe plus method stacking, like:

$color->add_value( saturation => 5)->invert->mix( to => 'green');

look at that chain. iconic. no cap. 💅

🎀 `set_value`

creates a new GTC color object that shares some values with the current one but differs in others. the altered values you hand over are absolute numbers. and if the resulting color would end up outside the given color space, the values get clamped so it becomes a regular color of that space. no wild out-of-bounds colors allowed here, we stay in our lane. ✨

so — the axes of all supported color spaces have long names and short names. for instance HSL has hue, saturation and lightness, and the short equivalents are h, s and l. this method takes these axis names as named arguments and does not care whether you write them upper or lower case. slay.

⚠️ but heads up — this method can not work if you mix axis names from different spaces, or if you pick the same axis more than once. one solvable issue though: when axes in different spaces have the same name. for instance HSL and HSV both have a saturation axis. to disambiguate, just add the named argument in. 🫶

my $blue = $black->set_value( blue => 255 );              # same as #0000ff
my $pale_blue = $blue->set_value( saturation => 50 );        # ->( s => 50) works too
my $color = $blue->set_value( saturation => 50, in => 'HSV' );  # previous was HSL

💜 `add_value`

creates a new GTC color object that shares some values with the current one but differs in others — except the altered values here are provided relative to the current ones. everything else works exactly like set_value described above. this method was mainly created so you can get lighter, darker or more saturated colors by using it like:

my $blue = Graphics::Toolkit::Color->new('blue');
my $darkblue = $blue->add_value( Lightness => -25 );  # get a darker tone
my $blue2 = $blue->add_value( blue => 10 );           # bluer than blue ?
my $blue3 = $blue->add_value( l => 10, in => 'LAB' ); # lighter color according CIELAB

"bluer than blue" is sending me honestly 😭💙

🦋 `mix`

create a new GTC object that has the average values between the calling object and another color (or several colors). it accepts three named arguments: to, amount and in — but only the first one is required. casual.

to works like it does in other methods, with one exception: it also accepts an ARRAY ref (square brackets) with several color definitions inside. yes queen, variety.

per default, mix computes a 50-50 (1:1) mix. wanna change that? employ the amount argument, which is the weight the mixed-in color(s) get, counted in percentages. the remaining percentage up to 100 is the weight of the color held by the caller object. now — this would naturally be nothing if the amount is greater than hundret, which is especially something to consider if you're mixing more than two colors. in that case both to and amount have to get an array of colors and respectively their amounts (same order). obviously both arrays MUST have the same length. if the sum of amounts is greater than 100, the original color is ignored but the weight ratios will be kept. and you may actually give amount a scalar value while mixing a list of colors — then that amount is applied to every color mentioned under the to argument. in which case you go over the sum of 100% very quickly. fyi. 🍓

$blue->mix( 'silver');                                         # 50% silver, 50% blue
$blue->mix( to => 'silver', amount => 60 );                    # 60% silver, 40% blue
$blue->mix( to => [qw/silver green/], amount => [10, 20]);     # 10% silver, 20% green, 70% blue
$blue->mix( to => [qw/silver green/] );                        # 50% silver, 50% green
$blue->mix( to => {H => 240, S =>100, L => 50}, in => 'RGB' ); # teal

🌸 `invert`

computes a new color object where all values are inverted according to the ranges of the chosen color space (peep the in section). it takes only one optional, positional argument — a space name. simple. clean. effective.

my $black = $white->invert();         # to state the obvious
my $blue = $yellow->invert( 'LUV' );  # invert in LUV space
$yellow->invert( in => 'LUV' );       # would work too

👑 COLOR SETS 👑

construct several interrelated color objects at once. family reunion energy. 💖

🧚 `complement`

creates a set of complementary colors (GTC objects), which will be computed in HSL color space. the method accepts three optional, named arguments: steps, tilt and target. but if none are provided, THE (one) complementary color will be produced. just the one. the main character.

one singular, positional argument defines the number of produced colors, same as the named argument steps would have. if you want 'triadic' colors, choose 3 as an argument for steps — 4 would get you the 'tetradic' colors, .... and so on and so forth. the given color is always last in the row of produced complementary colors.

if you need split-complementary colors, just use the tilt argument, which defaults to zero. without any tilt, complementary colors are equally distanced dots on a horizontal circle around the vertical, central column in HSL space. in other words: complementary colors all have the same 'saturation' (distance from the column) and 'lightness' (height). they differ only in 'hue' (position on the circle). the given color and its (THE) complement sit on opposite sides of the circle. the greater the tilt amount, the more these colors (minus the given one) will move on the circle toward THE complement and vice versa. what is traditionally meant by split-complementary colors, you'll get here with a tilt factor of around 3.42 and three steps, or a tilt of 1.585 and four steps (depending on whether you need THE complement also in your set).

to get an even greater variety of complementary colors, you can use the target argument and move around THE complement and thus shape the circle in all three directions. hue (or h) values move it circularly, saturation (or s) move it away — or with negative values toward — the central column, and lightness (or l) move it up and down.

my @colors = $c->complement( 4 );                       # 'tetradic' colors
my @colors = $c->complement( steps => 4, tilt => 4 );   # split-complementary colors
my @colors = $c->complement( steps => 3, tilt => { move => 2, target => {l => -10}} );
my @colors = $c->complement( steps => 3, tilt => { move => 2,
                                                 target => { h => 20, s=> -5, l => -10 } });

🌈 `gradient`

creates a gradient (a list of color objects that build a transition) between the current color held by the object and a second color, provided by the named argument to, which is required. optionally, to accepts an ARRAY ref (square braces) with a list of colors in order, so you can create the most fancy, custom and nonlinear gradients. go off.

also required is the named argument steps, which is the gradient length or count of colors that are part of this gradient. included in there are the start color (given by this object) and the end color (given with to). both ends count, bestie, don't forget it.

the optional, floating point valued argument tilt makes the gradient skewed toward one end or the other. default is zero, which results in a linear, uniform transition between start and stop. greater values of the argument let the color change rate start small, steadily getting bigger. negative values work vice versa. the bigger the absolute numeric value, the bigger the effect. please have in mind that values over 2 result in a very strong tilt. like, buckle up. 💀

optional is the named argument in (color space — details behind link). tip: use oklab and cieluv spaces for visually smooth gradients. chef's kiss. 🎀

# we turn to grey
my @colors = $c->gradient( to => $grey, steps => 5);
# none linear gradient in HSL space :
@colors = $c1->gradient( to =>[14,10,222], steps => 10, tilt => 1, in => 'HSL' );
@colors = $c1->gradient( to =>['blue', 'brown', {h => 30, s => 44, l => 50}] );

⭐ `cluster`

computes a set of colors that are all similar but not the same. it's giving siblings, not twins. the method accepts three named arguments: radius, distance and in, of which the first two are required.

the produced colors form a ball or cuboid in a color space around the given color, depending on what the argument radius got. if it's a single number, it'll be a ball with the given radius. if it's an ARRAY of values, you get a cuboid with the given dimensions.

the minimal distance between any two colors of a cluster is set by the minimal_distance argument, which is computed the same way as the method distance, and it has a short alias min_d. in a cuboid shaped cluster the colors will form a cubic grid — inside the ball shaped cluster they form a cuboctahedral grid, which is packed tighter but still obeys the minimal distance. geometry queen. 📐✨

my @blues = $blue->cluster( radius => 4, minimal_distance => 0.3 );
my @c = $color->cluster( r => [2,2,3], min_d => 0.4, in => YUV );

✨ ARGUMENTS ✨

some named arguments of the above listed methods reappear in several methods, so they're explained here once instead of a million times. efficient. we love a shared glossary.

🫶 please note that you must NOT wrap the named args in curly braces (HASH ref).

💙 `in`

the named argument in expects the name of a color space as listed here. the default color space in this module is RGB. depending on the chosen space, the results of all methods can be very different, since colors are arranged there very differently and have different distances to each other. some colors might not even exist in some spaces. 🙈 so like, choose wisely.

🌸 `range`

every color space comes with range definitions for its values. for instance red, green and blue in RGB usually go from zero to 255 (0..255). in order to change that, many methods accept the named argument range. when only one integer value is provided, it changes the upper bound on all three axes, and the lower bound is assumed zero. let's say you need RGB16 values with a range of 0 .. 65536, then you type range => 65536 or range => 2**16. math girlies rise up. 🧮

if you provide an ARRAY ref, you can change the upper bounds of all axes individually — and in order to change even the lower boundaries, use ARRAY refs even inside that. for instance, in HSL the hue is normally 0 .. 359 and the other two axes are 0 .. 100. in order to set hue to -100 .. 100 but keep the other two untouched, you would have to insert: range => [[-100,100],100,100]. nested arrays, we're in our depth era. 💅

🎀 `to`

this argument receives a second or target color. it may come in the form of another GTC object or a color definition that is acceptable to the constructor. but it has to be a scalar (string or (HASH) reference), not a value list or hash. periodt.

💖 SEE ALSO 💖

go read these too, they're the besties:

Color::Scheme
Graphics::ColorUtils
Color::Fade
Graphics::Color
Graphics::ColorObject
Color::Calc
Convert::Color
Color::Similarity

🫶 ACKNOWLEDGEMENT 🫶

Okay so bestie, this whole thing would NOT be the iconic masterpiece it is without the absolute legends who showed up with patches, bug reports and genuinely useful comments. Shoutout to every single one of them, no cap:

Petr Pisar (ppisar)
Slaven Rezic (srezic)
Gabor Szabo (szabgab)
Gene Boggs (GENE)
Stefan Reddig (sreagle)

The way that they just. contributed. 💖 Heroes, fr fr.

👑 AUTHOR 👑

Herbert Breunung, <lichtkind@cpan.org>

Main character energy, honestly. 🌟

(Yes, it's still going. Slay.)

📜 LICENSE 📜

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

So basically: same deal as Perl itself, bestie. Not my rules, but they're pretty chill. 💅

and that's the whole page, you made it to the end, so proud of you 🥹

This was perl v5.42.0, dated 2026-01-17, living at Graphic...::Color(3) — tysm for reading, go forth and color responsibly, mwah 💋✨🎀

📦 where this page comes from

fedora 44: perl-Graphics-Toolkit-Color 1.972-2.fc44 · GPL-1.0-or-later OR Artistic-1.0-Perl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms