NAME

       Graphics::Toolkit::Color::Value - single color related high level methods

SYNOPSIS

       Readonly object that holds values of a color. It provides methods to get the values back
       in different formats, to measure difference to other colors or to create value objects of
       related colors.

           use Graphics::Toolkit::Color::Value;

           my $blue = Graphics::Toolkit::Color::Value->new( 'hsl(220,50,60)' );
           my @rgb = $blue->get();
           my $purple = $blue->set({red => 220});

DESCRIPTION

       The object that holds the normalized values of the original color definition (getter
       argument) and the normalized RGB tripled, if the color was not defined in RGB values. This
       way we omit conversion and rounding errors as much as possible.

       This package is a mediation layer between Graphics::Toolkit::Color::Space::Hub below,
       where its just about number crunching of value vectors and the user API above in
       Graphics::Toolkit::Color, where it's mainly about producing sets of colors and handling
       the arguments. This module is not meant to be used as an public API since it has much less
       comfort than Graphics::Toolkit::Color.

METHODS

   new
       The constructor takes only one required argument, a scalar that completely and numerically
       defines a color. Inside color definitions are color space names case insensitive. Some
       possible formats are

           [ 1, 2, 3 ]                  # RGB triplet
           [ HSL => 220, 100, 3 ]       # named HSL vector
           { h => 220, s =>100, l => 3} # char hash
           { cyan => 1, magenta => 0.5, yellow => 0} # hash
           'hwb: 20, 60, 30'            # string
           'hwb(20,60,30)'              # css_string
           '#2211FF'                    # rgb hex string

   get
       Universal getter method -almost reverse function to new: It can return the colors values
       in all supported color spaces (first argument) (see: "COLOR-SPACES" in
       Graphics::Toolkit::Color::Space::Hub) and all mentioned formats above (second argument).
       Additionally a third arguments can convert the numerical values into different ranges.
       The default name space is RGB, default format is a list and every color space has its
       default range.

           my @rgb = $val_object->get();
           my @cmyk = $val_object->get('CMYK', 'list', 255);
           my $YIQ = $val_object->get('YIQ', 'string');

   set
       Constructs a new "Graphics::Toolkit::Color::Value" object by absolutely changing some
       values of the current object and keeping others. (add changes some values relatively.) The
       only and required argument is a HASH reference which has keys that match only one of the
       supported color spaces (see: "COLOR-SPACES" in Graphics::Toolkit::Color::Space::Hub).
       Values outside of the defined limits will be clamped to an acceptable value (or rotated in
       case of circular dimensions).

           my $more_blend_color = $val_object->set( {saturation => 40} );
           my $bright_color = $val_object->set( {saturation => 2240} ); #saturation will be 100

   add
       This method takes also a HASH reference as input and also produces a related color object
       as previous set. Only difference is: the hash values will be added to the current. If they
       go outside of the defined limits, they will be clamped (or rotated in case of circular
       dimensions).

           my $darker_color = $val_object->set( {lightness => -10} );

   blend
       Creates a color value object by mixing two colors.  First and only required argument is
       the second color value object.  Second argument is the mixing ratio. Zero would result in
       the original color and one to the second color. Default value is 0.5 (1:1 mix). Values
       outside the 0..1 rande are possible and values will be clamped if they leave the defined
       bounds of the required color space.

       Third optional argument is the name of the color space the mix will be calculated in - it
       defaults to 'HSL'.

           my $green = Graphics::Toolkit::Color::Values->new( '#00ff00' );
           my $cyan = $blue->blend( $green, 0.6, 'YIQ' );

   distance
       Computes a real number which designates the (Euclidean) distance between two points in a
       color space (a.k.a. colors).

       The first and only required argument is the second color as an
       Graphics::Toolkit::Color::Value object. Second and optional argument is the name of the
       color space, where the distance is calculated in (default is 'HSL'). Third argument is the
       metric, which currently is just the subset of dimension in the chosen space that should be
       observed.  One can also mention the shortcut name of a dimension several times to increase
       their weight in the calculation. Fourth optional argument are the numeric ranges of the
       dimensions. If none are given, the method only uses normalised (range: 0..1) values.

           my $blue = Graphics::Toolkit::Color::Values->new( '#0000ff' );
           my $green = Graphics::Toolkit::Color::Values->new( '#00ff00' );
           my $d = $blue->distance( $green, 'HSV', 's', 255); # 0 : both have same saturation

SEE ALSO

       •   Convert::Color

COPYRIGHT & LICENSE

       Copyright 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>