perldoc > Graphics::Toolkit::Color::Values

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 AT cpan.org>