is_in_gamut¶

is_in_gamut returns a perlish pseudo boolean that answers the question: is this color inside the value range of a color space (gamut). It can be used as a method or an importable subroutine. In method mode it takes one optional positional argument, which is a color space name (like in). The color will be converted into that space, before a check is performed. If no space name is provided, the check happens in the color space the original values (when the object was created) were defined in.

When used as a subroutine, it requires only one positional argument, that has to be a color definition (like with the "color" routine). This check will be performed in the color space the color is defined in. For color names this would be RGB, which makes the result always true (1).

    $color->is_in_gamut( 'okLab');               # is current color inside OKLAB?
    use Graphics::Toolkit::Color qw/is_in_gamut/;
    is_in_gamut('rgb: 0, 0, 300');               # false, SRGB ranges span up to 255
    is_in_gamut('#000000');                      # true, black is always included

values¶

values returns the numeric values of the color, held by the object and accepts six optional, named arguments: in (color space), "as" ( format), range (min. and max. values), "precision", "suffix" and raw (defaults to false, which clamps values into range). "in" is the default argument (used as only positional) and if no arguments are provided, the method will return a list with RGB values.

    $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
    $blue->values('HSL');                                   # 240, 100, 50 # HSL is only argument
    $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 the normalized name of the current color, if it (converted to RGB) is part of a color scheme. It has four optional named arguments: from (scheme name), "all" (allows to return more names), "full" (include scheme name in color name) and "distance" (all colors within distance). The default argument is "from" which defaults to the default scheme. All other arguments default to zero.

    $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 (almost) always returns a normalized color name (unlike name). In list context it also returns the "distance" between the current color and the color belonging to the returned name. It has three optional, named arguments: "from", "all", "full" which work the same way as in "name".

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

distance¶

distance returns a numeric value, the Euclidean distance between two colors in some color space, which works even in cylindrical spaces. It accepts four named arguments: to, range, only and in. Only the "to" is required and can be provided as the only positional argument.

    my $d = $blue->distance( 'lapisblue' );                        # how close is blue to lapisblue?
    $d = $blue->distance( to => 'airyblue', only => 'b');          # do they have the same amount of blue?
    $d = $color->distance( to => $c2, only => 'hue', in => 'HSL' );# 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

lighten¶

lighten increases the lightness by an absolute amount, but does not touch saturation. The result will be clamped, so lighten(1) will always return white.

    my $c = $mint->lighten( 0.1 );                      # is the same as :
    my $c = $mint->lighten( by => 0.1, in => 'OKHSL' );

darken¶

darken decreases the lightness by an absolute amount, but does not touch saturation. The result will be clamped, so darken(1) will always return black.

saturate¶

saturate increases the saturation by an absolute amount, but does not touch lightness. The result will be clamped, so saturate(1) will always return the purest possible color.

desaturate¶

desaturate decreases the saturation by an absolute amount, but does not touch lightness. The result will be clamped, so desaturate(1) will always return a shade of grey with the same lightness as the given color.

tint¶

tint mixes ("mix") a color with white by the given percentage (0.2 = 20% white, 80% given color). That lightens and desaturates at once. The result of tint(1) will always be white.

tone¶

tone mixes ("mix") a color with mid gray (gray50) by the given percentage (0.2 = 20% gray50, 80% given color). That darkens or lightens and desaturates at once. The result of tone(1) will always be gray50.

shade¶

shade mixes ("mix") a color with black by the given percentage (0.2 = 20% black, 80% given color). That darkens and desaturates at once. The result of shade(1) will always be black.

tone_curve¶

tone_curve computes a gamma correction. It has two named arguments: "gamma" and in, the first one being required and the default argument. "in" defaults here to LinearRGB.

    my $c = $blue->tone_curve( gamma => 2.2 );                          # is the same as :
    my $c = $blue->tone_curve( gamma => {r => 2.2, g =>2.2, b => 2.2}, in => 'LinearRGB' );

set_value¶

set_value returns a color that differs in some chosen values from the current one. Its arguments have to be short or long axis names from one selected color space. You may additionally provide the color space in mind with the argument in if the axis names alone are too ambiguous.

    my $blue = $black->set_value( blue => 255 );                    # same as #0000ff
    my $color = $blue->set_value( saturation => 50, in => 'HSV' );  # would otherwise use OKHSL

add_value¶

Works exactly as "set_value" with only one difference: the provided axis values will be added to the current ones and not exchanged.

    my $darkblue = $blue->add_value( Lightness => -25 );    # get a darker tone
    my $blue3 = $blue->add_value( l => 10, in => 'LAB' );   # lighter color according to CIELAB

mix¶

mix computes a color that is a blend between two or more other colors. It has three named arguments: to, by and in. The first one ("to") is the only required one and also the default argument. "by" defaults to a 50:50 blend and "in" to OKLAB.

    $blue->mix( $silver );                                     # 50% silver, 50% blue
    $blue->mix( to => 'silver', by => .6 );                    # 60% silver, 40% blue
    $blue->mix( to => [qw/silver green/], by => [.1, .2]);     # 10% silver, 20% green, 70% blue

invert¶

invert computes a color with opposite properties (values). It has two named, optional arguments: only (select axes) and in (color space name, defaults to OKHSL).

    my $still_gray = $gray->invert();                 # got same color back
    my $blue = $yellow->invert('hue');                # invert hue in 'OKHSL'
    $yellow->invert( in => 'OKHSL', only => 'hue' );  # same in long form, same result as $yellow->complement();

complement¶

complement computes colors that form a circle of complementary colors. This can only work in cylindrical spaces of the HSL family. It understands five named arguments: steps (color count), tilt, "target", "skew" and in (color space name, defaults to OKHSL). With no argument given it computes THE complementary color.

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

analogous¶

analogous creates a list of colors where values of neighbours differ from each other the same way as the two given colors. It accepts four named arguments: to (next color), steps (max. color count, default 4), tilt and in (color space name, defaults to OKHSL). Only "to" is required and also the default argument.

    my @colors = $darkblue->analogous( to => $midblue, steps => 5);     # 5 shades of blue
    @colors = $c->analogous( to => [14,10,222], steps => 3, tilt => 0.2, in => 'RGB' );

gradient¶

gradient creates a list of colors that are a gradual blend between two or more given colors. It accepts four named arguments: to, steps (color count), "tilt" and in (color space name, defaults to OKLAB). Only "to" is required and also the default argument.

    my @colors = $c->gradient( to => $grey, steps => 5);       # we turn to grey
    @colors = $c1->gradient( to => [14,10,222], steps => 10, tilt => 1, in => 'HSL' );

cluster¶

cluster creates a list of GTC color objects that look similar to the calling color but distinctly different. It accepts three named arguments: "radius", "minimal_distance" and in (color space name, defaults to OKLAB). "radius", "minimal_distance" are required and can be written "r" and "min_d".

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