Graphic...:Getter(3)

✨ NAME ✨

Graphics::Toolkit::Color::Manual::Getter — the reference of value access or value calculating methods. That's the official NAME, and yes, it's exactly what we're doing, bestie. 💅

This is the Graphic...:Getter(3) page from the User Contributed Perl Documentation, part 1 of the getter manual.

---

🌈 SYNOPSIS 🌈

This manual page contains the most detailed description of the five methods: values, name, closest_name, distance and is_in_gamut. These methods return various information about a color, but not a GTC object. They might trigger an error if called incorrectly.

🧚 METHODS 🧚

🎀 values 🎀

values is the universal getter for numerical color values. It can be used to convert, quantize or reformat the values of the color held by the object. The method accepts six optional, named arguments: in, as, raw, range, precision and suffix.

If none are provided, the method returns a list with the RGB values in default range (0 .. 255), since RGB is the default color space for IO. If one positional argument is provided, it is understood as the named argument in, the name of the color space the values will be converted into.

• as — lets you select the output format of the color definition, which defaults to 'list'. Other options are: 'hash', 'char_hash', 'named_array', 'nested_array', 'named_string', 'css_string', 'array' (RGB only) and 'hex_string' (RGB only).
• raw — awaits a pseudo boolean which defaults to false. When false, the values will be clamped into range, which is either the default range of the selected color space (in) or the range set by the user (range).
• range — requires a range definition (follow the link for details about that). It will define the minimum and maximum value per axis.
• precision — needs a precision definition, that determines how many decimals the result values will have. Use 5 to require five decimals (and so forth), insert 0 to get no decimals (int) and -1 to get all the decimals (max. 15). If every value should have a different amount, use an ARRAY reference and put inside a precision number for each axis in the same order as in a range definition: precision => [1,2,3].
• suffix — accepts a suffix definition, which is a string or an ARRAY reference with strings (one per axis), pretty much like a precision definition. That string will be attached to the value(s) in question, which is in many cases a percent sign '%'. For instance an output in HSL space will have saturation and lightness values with a suffix of '%'. This can be suppressed 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-1 );            # 0, 0, 65535 - RGB16 values
$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 🌸

name returns a string with the name of the color or an empty string if the color held by the object has no name. This name will be normalized (lower case, no special character — read more here). In rare cases the method might return more than one color name. It accepts four named, optional arguments: from, full, all and distance. If only one, positional argument is provided, then it is understood as the from value.

• from — selects the color scheme the color names have to come from. Follow the last link to read what color schemes are and how to install them. The options are: Crayola, CSS, EmergyC, GrayScale, HTML, IE, Mozilla, Netscape, Pantone, PantoneReport, SVG, VACCC, Werner, Windows and WWW. It is possible to select more than one scheme by providing an ARRAY reference with several scheme names. If no scheme name is provided, then the default scheme is selected. Please note that even if the color object is created by numeric values, name will return a color name.
• full — receives a pseudo boolean that defaults to false (0). When set to true (1), the method will return full color names which are explained here. In short: if $color->name(from => 'SVG') returns 'green', $color->name(from => 'SVG', full => 1) will return 'SVG:green'. Colors from the default scheme will never contain a scheme name.
• all — gets also a pseudo boolean that defaults to false (0). When set to true (1), the method might return several color names that identify the same color, like 'gray' and 'gray50'. This might be the case if the default color scheme is selected or several schemes are chosen. In the latter case it is helpful to add the argument full.
• distance (or short d) — expects a number which defaults to 0. When set to a number larger than zero, the method will search for names of colors that are part of the chosen color scheme and that have a smaller or equal distance to the color held by the object. It is very useful to combine it with the all argument. The names will be sorted by distance (closest first) or it will return the name of the closest color. But this ordering is not guaranteed when searching across several schemes. However, all returned names will always be unique, which is another reason to use full.

$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 🦋

closest_name will always return one and only one color name, which has the shortest distance in RGB to the current color. However, should you provide a self made, empty color scheme and you insist on only using this one, this method will return an empty string. In list context the caller will receive a second return value, which is the distance between the current color and the color whose name was found. The method accepts three named, optional arguments: from, full and all, which work almost identically as for the method name. If only one, positional argument is provided, then it is understood as the from value.

all has a slightly different meaning here, since there can be only one closest color. But this color can have several names. Get all of them by switching this argument to true (1).

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 🎯

distance returns 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 positional argument or the named argument to, which is the only required one. The other three, optional arguments are: only (alias select), range and in.

• to — receives a color definition in any format or a GTC object.
• only (alias select) — selects along which color space dimension the distance will be measured. The default is all dimensions. It requires one or several (in an ARRAY reference) axis names (long or short). For instance if you want to know only the difference in brightness between two colors, you choose only => 'lightness' or only => 'l'. This naturally works only if you did also select OKLAB as the color space or something similar that has a lightness axis like CIELAB or HSL. It is allowed to repeat axis names to weight their influence on the outcome. For instance to reproduce the formula: $distance = sqrt( 3 * $delta_red**2 + 4 * $delta_green**2 + 2 * $delta_blue**2) insert only => [qw/ r r r g g g g b b/].
• range — requires a range definition (follow the link for details about that). It will define the minimum and maximum value per axis and thus greatly change the result. Please note that this has nothing to do with how the color definition of the second color is read. Use constructor arguments and provide the object if the second color uses non-default ranges. This argument enables you for instance to calculate the distance in RGB as if the values were normalized. In that case use range => 1.
• in — sets the color space the distance is calculated in. For compatibility it still defaults to RGB, but this will change with version 3.0. Please use the OKLAB (better) or CIELUV space, if you are interested in getting a result that matches the human perception.

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

🧚 is_in_gamut 🧚

is_in_gamut returns a perlish pseudo boolean (zero or one). It will tell you, if a color is within the gamut (value range) of a color space. It exists as method and as an importable subroutine.

The method has one optional default argument: in which defaults to the space the color was defined in. If a space name is provided the method asks the question, can I convert into that space without clamping?

The subroutine has only one positional argument which works like the named argument color, only with raw set to 1 (true).

$color->is_in_gamut( in => 'okLab');                    # is $color in OKLAB gamut?

use Graphics::Toolkit::Color qw/is_in_gamut/;
is_in_gamut([ RGB =>  255, 0, 0]);                      # is it in RGB gamut ?
if (is_in_gamut('rgb: 0, 0, 300')){...}                 # false, 300 has to be clamped to 255

💖 AUTHOR 💖

Herbert Breunung, <lichtkind@cpan.org>

📜 COPYRIGHT 📜

Copyright 2026 Herbert Breunung.

🎀 LICENSE 🎀

okay so this is the part where the lawyers show up, but like… in a cute way 💅

the whole license section is literally one sentence, and it says:

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

that's it. that's the section. no cap, no fine print novel, no 47-page EULA you gotta scroll through at 3am 😭

so like — this program is free software, and you can redistribute it and/or modify it, and the terms you do that under are the same terms as Perl itself. iconic behavior honestly, it's giving "share the love" 🌈✨

bestie you made it to the end of the page, and there was no cliffhanger, just a lil legal heart 🫶

---

and that's a wrap, diva 👑 the whole thing came from perl v5.42.2, stamped 2026-06-21 — go forth and get those Graphics, mwah 💖🧚‍♀️