NAME
    Graphics::Toolkit::Color - color palette constructor

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

        my $red = Graphics::Toolkit::Color->new('red'); # create color object
        say $red->add( 'blue' => 255 )->name;           # add blue value: 'fuchsia'
        my $blue = color( 0, 0, 255)->values('HSL');    # 240, 100, 50 = blue
        $blue->blend( with => [HSL => 0,0,80], pos => 0.1);# mix blue with a little grey in HSL
        $red->gradient( to => '#0000FF', steps => 10);  # 10 colors from red to blue
        $red->complement( 3 );                          # get fitting red green and blue

DESCRIPTION
    ATTENTION: deprecated methods of the old API ( *string*, *rgb*, *red*,
    *green*, *blue*, *rgb_hex*, *rgb_hash*, *hsl*, *hue*, *saturation*,
    *lightness*, *hsl_hash*, *blend_with*, *gradient_to*, *rgb_gradient_to*,
    *hsl_gradient_to*, *complementary*) will be removed on version 2.0.

    Graphics::Toolkit::Color, for short GTC, is the top level API of this
    module and the only one a regular user should be concerned with. Its
    main purpose is the creation of sets of related colors, such as
    gradients, complements and others.

    GTC are 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". Measure differences with
    the *distance* method. "SINGLE-COLOR" methods create one a object that
    is related to the current one and "COLOR-SETS" methods will create a
    host of color that are not only related to the current color but also
    have relations between each other.

    While this module can understand and output color values in many spaces,
    such as YIQ, HSL and many more, 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 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 constant or provide values in one of several
    "COLOR-SPACES" in Graphics::Toolkit::Color::Space::Hub, which also can
    be formatted in many ways as described in this paragraph.

  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 "NAMES" in
    Graphics::Toolkit::Color::Name::Constant. (See also: "name")

        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. * 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
        my $red = Graphics::Toolkit::Color->new('RGB' => 255, 0, 0);  # named tuple syntax
        my $red = Graphics::Toolkit::Color->new(['RGB' => 255, 0, 0]); # named ARRAY

    The named array syntax of the last example, as any here following, work
    for any supported color space.

  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
                            ... ->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('rgb: $r, $g, $b')
    String format (good for serialisation) that maximizes readability.

        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)')
    Variant of string format that is supported by CSS.

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

  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
    giving access to different parts of the objects data.

  name
    String with normalized name (lower case without *'_'*) of the color as
    in X11 or HTML (SVG) standard or the Pantone report. The name will be
    found and filled in, even when the object was created numerical values.
    If no color is found, "name" returns an empty string. All names are at:
    "NAMES" in Graphics::Toolkit::Color::Name::Constant (See als:
    "new('name')")

  values
    Returns the values of the color in given color space and format. It
    accepts three named, optional arguments.

    First argument is the name of a color space (named argument "in"). All
    options are under: "COLOR-SPACES" in
    Graphics::Toolkit::Color::Space::Hub The order of named arguments is of
    course chosen by the user, but I call it the first (most important)
    argument, because if you give the method only one value, it is assumed
    to be the color space.

    Second argument is the format (name: "as"). In short any SCALAR format
    acceptable to the "CONSTRUCTOR" can also be reproduced by a getter
    method and the numerical cases by this one. Not all formats are
    available under all color spaces, but the always present options are:
    "list" (default), "hash", "char_hash" and "array".

    Third named argument is the range inside which the numerical values have
    to be. RGB are normally between 0 .. 255 and CMYK between 0 .. 1
    ('normal'). Only a range of 1 a.k.a. 'normal' displays decimals. There
    are three syntax option to set the ranges. One value will be understood
    as upper limit of all dimensions and zero being the lower one. If you
    want to set the upper limits of all dimensions separately, you have to
    deliver an ARRAY ref with the 3 or 4 upper limits. To also define the
    lower boundary, you replace the number with an ARRAY ref containing the
    lower and then the upper limit.

        $blue->values();                               # get list in RGB: 0, 0, 255
        $blue->values( in => 'RGB', as => 'list');     # same call
        $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 => 'hex');      # '#00FFFF'
        $color->values('HSL');                         # 240, 100, 50
        $color->values( in => 'HSL', range => 1);      # 0.6666, 1, 0.5
        $color->values( in => 'RGB', range => 2**16);  # values in RGB16
        $color->values( in => 'HSB', as => 'hash')->{'hue'};  # how to get single values
       ($color->values( 'HSB'))[0];                           # same, but shorter

  distance
    Is a floating point number that measures the Euclidean distance between
    two colors. One color is the calling object itself and the second (C2)
    has to provided as a named argument (*to*), which is the only required
    one. It ca come in the form of a second GTC object or any scalar color
    definition *new* would accept. The *distance* is measured in HSL color
    space unless told otherwise by the argument *in*. The third argument is
    named *metric*. It's useful if you want to notice only certain
    dimensions. Metric is the long or short name of that dimension or the
    short names of several dimensions. They all have to come from one color
    space and one shortcut letter can be used several times to heighten the
    weight of this dimension. The last argument in named *range* and is a
    range definition, unless you don't want to compute the distance with the
    default ranges of the selected color space.

        my $d = $blue->distance( to => 'lapisblue' );              # how close is blue to lapis color?
        $d = $blue->distance( to => 'airyblue', in => 'RGB', select => 'Blue'); # same amount of blue?
        $d = $color->distance( to => $c2, in => 'HSL', select => 'hue' );                  # same hue?
        # compute distance when with all value ranges 0 .. 1
        $d = $color->distance( to => $c2, in => 'HSL', select => 'hue', range => 'normal' );

SINGLE COLOR
    construct colors that are related to the current object.

  set
    Create a new object that differs in certain values defined in the
    arguments as a hash.

        $black->set( blue => 255 )->name;   # blue, same as #0000ff
        $blue->set( saturation => 50 );     # pale blue, same as $blue->set( s => 50 );

  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 (clamped), 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 );        # this is bluer than blue

  blend
    Create a Graphics::Toolkit::Color object, that has the average values
    between the calling object (color 1 - C1) and another color (C2).

    It takes three named arguments, only the first is required.

    1. The color C2 (scalar that is acceptable by the constructor: object,
    string, ARRAY, HASH). The name of the argument is *with* (color is
    blended with ...).

    2. Blend position is a floating point number, which defaults to 0.5.
    (blending ratio of 1:1 ). 0 represents here C1 and 1 is pure C2. Numbers
    below 0 and above 1 are possible, butlikely to be clamped to fit inside
    the color space. Name of the argument is *pos*.

    3. Color space name (default is *HSL* - all can be seen unter
    "COLOR-SPACES" in Graphics::Toolkit::Color::Space::Hub). Name of the
    argument is *in*.

        # a little more silver than $color in the mix
        $color->blend( with => 'silver', pos => 0.6 );
        $color->blend({ with => 'silver', pos => 0.6 });             # works too!
        $blue->blend( with => {H => 240, S =>100, L => 50}, in => 'RGB' ); # teal

COLOR SETS
    construct many interrelated color objects at once.

  gradient
    Creates a gradient (a list of colors that build a transition) between
    current (C1) and a second, given color (C2) by named argument *to*.

    The only required argument you have to give under the name *to* is C2.
    Either as an Graphics::Toolkit::Color object or a scalar (name, hex,
    HASH or ARRAY), which is acceptable to a "CONSTRUCTOR". This is the same
    behaviour as in "distance".

    An optional argument under the name *steps* sets the number of colors,
    which make up the gradient (including C1 and C2). It defaults to 3.
    Negative numbers will be rectified by "abs". These 3 color objects: C1,
    C2 and a color in between, which is the same as the result of method
    "blend".

    Another optional argument under the name *dynamic* is a float number,
    that defines the position of weight in the color transition from C1 to
    C2. It defaults to zero which gives you a linear transition, meaning the
    "distance" between neighbouring colors in the gradient is equal. If
    $dynamic > 0, the weight is moved toward C1 and vice versa. The greater
    $dynamic, the slower the color change is in the beginning of the
    gradient and the faster at the end (C2).

    The last optional argument named *in* defines the color space the
    changes are computed in. It parallels the argument of the same name from
    the method "blend" and "distance".

        # we turn to grey
        my @colors = $c->gradient( to => $grey, steps => 5, in => 'RGB');
        # none linear gradient in HSL space :
        @colors = $c1->gradient( to =>[14,10,222], steps => 10, dynamic => 3 );

  complement
    Creates a set of complementary colors, which will be computed in *HSL*
    color space. It accepts 4 optional, named arguments. Complementary
    colors have a different *hue* value but same *saturation* and
    *lightness*. Because they form a circle in HSL, they will be called in
    this paragraph a circle.

    If you provide no names (just a single argument), the value is
    understood as *steps*. *steps* is the amount (count) of complementary
    colors, which defaults to 1 (giving you then THE complementary color).
    If more than one color is requested, the result will contain the calling
    object as the first color.

    The second optional argument is *hue_tilt*, in short *h*, which defaults
    to zero. When zero, the hue distance between all resulting colors on the
    circle is the same. When not zero, the *hue_tilt* gets added (see "add")
    to THE complementary color. The so computed color divides the circle in
    a shorter and longer part. Both of these parts will now contain an equal
    amount of result colors. The distribution will be computed in a way,
    that there will be a place on the circle where the distance between
    colors is the highest (let's call it Dmax) and one where it is the
    lowest (Dmin). The distance between two colors increases or decreases
    steadily. When *hue_tilt* is zero, the axis through Dmax and Dmin and
    the axis through $self and C2 are orthogonal.

    The third optional argument *saturation_tilt*, or short *s*, which also
    defaults to zero. If the value differs from zero it gets added the color
    on Dmax (last paragraph), subtracted on Dmin, changed accordingly in
    between, so that the circle gets moved in direction Dmin. If you want to
    move the circle in any other direction you have to give
    *saturation_tilt* a HASH reference with 2 keys. First is *saturation* or
    *s*, which is the value as described. Secondly *hue* or *h* rotates the
    direction in which the circle will be moved. Please not, this will not
    change the position of Dmin and Dmax, because it just defines the angle
    between the Dmin-Dmax axis and the direction where the circle is moved.

    The fourth optional argument is *lightness_tilt* or *l*m which works
    analogously to *saturation_tilt*. Only difference is that it tilts the
    circle in the up-down direction, which is in HSL color space lightness.

        my @colors = $c->complement( 4 );    # $self + 3 compementary (square) colors
        my @colors = $c->complement( steps => 3, s => 20, l => -10 );
        my @colors = $c->complement( steps => 3, hue_tilt => -40,
                                         saturation_tilt => {saturation => 300, hue => -50},
                                         lightness_tilt => {l => -10, hue => 30} );

SEE ALSO
    *   Color::Scheme

    *   Graphics::ColorUtils

    *   Color::Fade

    *   Graphics::Color

    *   Graphics::ColorObject

    *   Color::Calc

    *   Convert::Color

    *   Color::Similarity

COPYRIGHT & LICENSE
    Copyright 2022-2023 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>