Graphic...:Values(3)

🌈 NAME 🌈

Okay bestie, welcome to Graphic...:Values(3) — the User Contributed Perl Documentation page for Graphics::Toolkit::Color::Value — single color related high level methods. 💅

---

✨ SYNOPSIS ✨

It's a readonly object that holds values of a color. It gives you methods to get the values back in different formats, to measure difference to other colors, or to create value objects of related colors. Obsessed. 🫶

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 🦋

This object holds the normalized values of the original color definition (the getter argument) and the normalized RGB tripled, if the color was not defined in RGB values. The whole point? To omit conversion and rounding errors as much as possible. No cap. ✨

This package is a mediation layer between Graphics::Toolkit::Color::Space::Hub below — where it's 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. It's giving internal bestie, not public-facing icon. 💀

---

🎀 METHODS 🎀

🌸 new

The constructor takes only one required argument: a scalar that completely and numerically defines a color. Inside color definitions, color space names are 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 the reverse function to new. It can return the color's values in all supported color spaces (first argument) — see "COLOR-SPACES" in Graphics::Toolkit::Color::Space::Hub — and all the mentioned formats above (second argument). Additionally, a third arguments can convert the numerical values into different ranges. The default name space is RGB, the default format is a list, and every color space has its default range. Slay. 🔥

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 also takes a HASH reference as input and also produces a related color object like the previous set. The only difference is: the hash values will be added to the current ones. If they go outside of the defined limits, they will be clamped (or rotated in case of circular dimensions). Periodt. ✨

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 in 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). Main character math moment. 💖

The first and only required argument is the second color as a 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. Ngl, that's iconic. 🦋

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>

---

And that's the whole vibe check, bestie: perl v5.42.0, dated 2024-03-08, page Graphic...:Values(3) — mwah 💋✨