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 selects along which color space dimension the distance will be measured. The default is all dimensions. It requires one or several (in a 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